DOCS

POST /v1/charges

Create a charge — card, Pix, or boleto.

Cria uma cobrança. Aceita os métodos card, pix e boleto. Requer os cabeçalhos Authorization com sua chave secreta (Basic, com a chave como usuário e senha vazia, ou Bearer <chave>) e Idempotency-Key com uma chave única por intenção (até 255 caracteres, apenas A-Z a-z 0-9 _ - : .).

Exemplo (curl)

curl -X POST https://api.kirvex.com.br/v1/charges   -u "$KIRVEX_SECRET_KEY:"   -H "Content-Type: application/json"   -H "Idempotency-Key: pedido-1234-pix-1"   -d '{
    "amount": { "amount": "9990", "currency": "BRL" },
    "method": "pix",
    "description": "Pedido #1234",
    "customer": {
      "email": "ada@lovelace.com",
      "name": "Ada Lovelace",
      "document": "12345678909",
      "phone": "+5511987654321",
      "address": {
        "zipcode": "01310100",
        "street": "Avenida Paulista",
        "number": "1000",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP"
      }
    },
    "pix": { "expiresInSeconds": 3600 },
    "metadata": { "product_id": "prod_...", "offer_id": "poff_..." }
  }'

O painel mostra este mesmo exemplo já preenchido com os IDs do seu produto em Produtos → (produto) → Integrações.

Modo de teste: sk_test_ e sk_live_

Existe uma só API, em https://api.kirvex.com.br. É a chave que decide o modo, não a URL:

  • sk_live_ cobra de verdade.
  • sk_test_ nunca move dinheiro real. A cobrança vai para o ambiente de teste (sandbox) do adquirente — Stripe para cartão, Woovi ou Pagar.me para Pix, Pagar.me para boleto, conforme o que estiver configurado na Kirvex.

Uma cobrança de teste volta com "livemode": false. Ela não entra no seu saldo, não vira saque e não aparece nas vendas, relatórios e exportações do painel. Os webhooks dela chegam com "livemode": false.

Se o método pedido não tem sandbox configurado, a cobrança é recusada com 422 e o código test_mode_unavailable. Ela nunca é enviada para produção no lugar. A aba Produtos → (produto) → Integrações do painel mostra, por método, se o teste está disponível agora.

Cada chave só enxerga os objetos do seu modo: GET, estorno, captura e cancelamento de uma cobrança real com uma chave sk_test_ respondem 404, e o mesmo vale ao contrário. As chaves de idempotência também são separadas por modo.

Operações que só existem com dinheiro real recusam a chave sk_test_ com test_mode_unavailable: saque (/v1/payouts), antecipação, faturas e saques em cripto, recebedores, assinaturas e links de pagamento.

O que a cobrança pela API não faz

A cobrança criada por esta rota não gera pedido. Ela não envia o e-mail de entrega do produto, não libera área de membros e não gera comissão de afiliado nem rateio de coprodução — isso só acontece em vendas pelo checkout ou pelo link de pagamento. O valor cobrado é sempre o de amount: a API não lê preço de produto ou oferta. Para amarrar a cobrança a um produto, mande os IDs em metadata; a Kirvex guarda e devolve esse campo em GET /v1/charges/{id}. Os eventos de webhook trazem o charge_id, não o metadata.

Vendas da API na UTMify

Se a UTMify está ligada em Configurações → Rastreamento, cada cobrança real (sk_live_) criada por esta rota vira um pedido na UTMify, sem nada a mais para configurar. O pedido usa o id da cobrança e muda de status sozinho: "aguardando pagamento" quando o Pix ou o boleto é gerado, "pago" quando o pagamento cai, e "recusado" ou "reembolsado" depois. Cobranças de teste (sk_test_) não vão, porque a UTMify não grava pedido de teste.

Para a venda aparecer na campanha certa, mande no metadata as UTMs que o comprador trouxe na URL do seu site:

"metadata": {
  "product_id": "prod_...",
  "utm_source": "facebook",
  "utm_medium": "cpc",
  "utm_campaign": "black-friday",
  "utm_content": "video-1",
  "utm_term": "curso",
  "src": "...",
  "sck": "..."
}
  • Todas são opcionais. As que não vierem vão vazias para a UTMify.
  • O produto do pedido é o de metadata.product_id, se for um produto seu. Sem ele, a linha leva o description da cobrança.
  • Mande customer.name (no boleto, vale o boleto.payerName) para o pedido sair com o nome do comprador. A UTMify exige nome e e-mail: se um deles faltar, a Kirvex manda um identificador da cobrança no lugar ("Cliente A1B2C3" e um e-mail @comprador.kirvex.com.br, que não recebe mensagens). CPF e telefone nunca são inventados: se não vierem, vão vazios.

Pix sem dados do comprador

Para um Pix de um clique no seu site, a cobrança pode ir sem customer e sem customer_id:

{
  "amount": { "amount": "9990", "currency": "BRL" },
  "method": "pix",
  "description": "Pedido #1234",
  "metadata": { "product_id": "prod_...", "utm_source": "facebook" }
}
  • Quem paga é identificado pelo próprio banco na hora do pagamento; a Kirvex não inventa nome, CPF nem e-mail no lugar do que não veio.
  • Esse Pix vai só para as adquirentes que não exigem dados do pagador. A Pagar.me exige e-mail, telefone e endereço, então fica de fora. Se a sua conta só tiver a Pagar.me para Pix, a cobrança é recusada com 503.
  • Na UTMify, o pedido sai com o identificador da cobrança no lugar do nome e do e-mail (veja a seção acima).
  • Cartão e boleto continuam exigindo o comprador.

Request body

{
  "amount": { "amount": "9990", "currency": "BRL" },
  "method": "pix",
  "description": "Pedido #1234",
  "customer": {
    "email": "ada@lovelace.com",
    "name": "Ada Lovelace",
    "document": "12345678909",
    "phone": "+5511987654321",
    "address": {
      "zipcode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Conjunto 12"
    }
  },
  "pix": { "expiresInSeconds": 3600 },
  "metadata": { "product_id": "prod_...", "offer_id": "poff_..." }
}
  • Cartão e boleto: customer ou customer_id (um dos dois é obrigatório). Sem customer_id, customer.email é obrigatório.
  • Pix: o comprador é opcional. Dá para mandar só parte dele (o nome, por exemplo) ou nada. Veja "Pix sem dados do comprador" abaixo.
  • customer.phone e customer.address: opcionais, mas a Pagar.me exige os dois (e o e-mail) — veja abaixo.
  • metadata: objeto de texto → texto, opcional. Guardado com a cobrança.
  • pix.expiresInSeconds: de 60 a 86400.

Telefone e endereço do comprador

A Pagar.me exige o telefone e o endereço do comprador em todo pedido: Pix, boleto e cartão. No cartão, o endereço também vai como endereço de cobrança.

  • Pix ou boleto sem os dois: a Kirvex manda a cobrança para outra adquirente configurada. Se a Pagar.me é a única que atende o método, a cobrança volta 503 com a mensagem Pagar.me requires the buyer's phone and address.
  • Cartão sem os dois: a cobrança segue para a Pagar.me, que pode recusar.

Se a sua conta usa a Pagar.me, mande sempre customer.phone e customer.address.

CampoFormato
phoneNúmero brasileiro com DDD. Aceita +5511987654321, 11987654321 ou (11) 98765-4321; a Kirvex converte para +5511987654321
address.zipcodeCEP com 8 dígitos. O hífen é aceito e removido (01310-100 → 01310100)
address.streetRua, até 200 caracteres
address.numberNúmero, até 20 caracteres
address.neighborhoodBairro, até 120 caracteres
address.cityCidade, até 120 caracteres
address.stateUF com 2 letras (SP; minúsculas são aceitas)
address.complementOpcional, até 120 caracteres

Telefone ou endereço fora do formato voltam 400 validation_error, com o campo em param (por exemplo customer.address.zipcode). Um telefone com código de outro país (+1 …) é recusado.

Com customer_id

O cliente salvo em /v1/customers fornece e-mail, nome, documento e telefone. Ele não guarda endereço. Por isso, mande o endereço em customer, junto com o customer_id:

{
  "amount": { "amount": "9990", "currency": "BRL" },
  "method": "pix",
  "customer_id": "cus_...",
  "customer": {
    "address": {
      "zipcode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP"
    }
  }
}

Com customer_id, a Kirvex lê só phone e address desse objeto. Um phone enviado aqui substitui o telefone salvo. E-mail, nome e documento continuam os do cliente salvo. Um telefone salvo que não seja brasileiro não é enviado à adquirente.

Response 201

{
  "id": "ch_018f1c4b00007abcdef1234567890abc",
  "object": "charge",
  "status": "pending",
  "method": "pix",
  "amount": { "amount": "9990", "currency": "BRL" },
  "vendor": "woovi",
  "vendor_ref": "ch_vnd_xxx",
  "created_at": "2026-04-29T12:34:56Z",
  "pix": { "qrCode": "00020126..." }
}

Errors

Toda resposta de erro segue o envelope:

{
  "error": {
    "type": "...",
    "code": "...",
    "message": "...",
    "request_id": "...",
    "retryable": false
  }
}

Códigos previstos:

  • validation_error
  • idempotency_conflict
  • unauthorized
  • vendor_unavailable
  • card_declined
  • kyc_required
  • internal_error

Refund, capture, void

Endpoints relacionados (todos requerem Idempotency-Key):

  • POST /v1/charges/{id}/refund — full ou partial refund. Aceita amount opcional no body. Boleto exige buyer_pix_key e é devolvido por Pix ao comprador, saindo do seu saldo (veja Refunds).
  • POST /v1/charges/{id}/capture — captura explícita para cards em modo manual capture.
  • POST /v1/charges/{id}/void — cancela uma cobrança autorizada (não capturada).

OpenAPI

A spec completa está em /openapi.json.

On this page