POST/charges

Cobrar no Cartão ou Boleto

Gera uma cobrança no cartão de crédito (link de pagamento seguro) ou um boleto bancário. Quando o pagador paga, o valor cai em reais no seu saldo e o seu webhook recebe transaction.completed.

Cartão: crédito à vista. O pagador preenche o cartão numa página segura e a confirmação é na hora; o valor entra no saldo na hora e fica disponível para saque em 30 dias (recebimento em D+30). Boleto: vence em 3 dias úteis e compensa em até 3 dias úteis depois de pago. Taxas e limites de cada forma em GET /charges/methods. Não funciona no modo sandbox.

Headers

Parâmetro	Tipo	Descrição
`X-API-Key`*	string	Sua API Key de produção
`X-Idempotency-Key`	string	Opcional. Repetir a chamada com a mesma chave devolve a cobrança já criada (sem duplicar)

Request Body

Parâmetro	Tipo	Descrição
`method`*	string	CARD (cartão de crédito) ou BOLETO
`amount`*	number	Valor em reais. Limites em /charges/methods (os mesmos do depósito normal da conta)
`payerName`	string	Nome de quem vai pagar. Obrigatório no boleto (sai impresso)
`payerDocument`	string	CPF ou CNPJ de quem vai pagar. Obrigatório no boleto
`payerEmail`	string	No cartão, com payerDocument, abre o checkout já preenchido
`payerPhone`	string	Celular do pagador (opcional)
`description`	string	Descrição da cobrança (até 140 caracteres)
`feeToCustomer`	boolean	true = o pagador paga a taxa por cima e você recebe o valor cheio
`externalReference`	string	ID do pedido no seu sistema. Volta na consulta e nos webhooks
`completionUrl`	string	Cartão: pra onde o pagador vai depois de pagar (https). Padrão: a página de pagamento da VamPay
`returnUrl`	string	Cartão: pra onde o pagador vai ao clicar em Voltar (https)

Exemplo: cartão de crédito

curlbash

curl -X POST "https://api.vampay.com.br/charges" \
  -H "X-API-Key: vampay_sua_api_key" \
  -H "X-Idempotency-Key: pedido-8812" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "CARD",
    "amount": 150,
    "description": "Pedido #8812",
    "externalReference": "8812",
    "completionUrl": "https://sualoja.com/obrigado"
  }'

201 Createdjson

{
  "success": true,
  "data": {
    "id": "6ad11c0e5b3f4a0012c9e7a1",
    "method": "CARD",
    "status": "PENDING",
    "amount": 150,
    "fee": 5.85,
    "netAmount": 144.15,
    "feeToCustomer": false,
    "description": "Pedido #8812",
    "externalReference": "8812",
    "paymentLink": "https://vampay.com.br/pay/6ad11c0e5b3f4a0012c9e7a1",
    "card": {
      "checkoutUrl": "https://app.abacatepay.com/pay/bill_k8pqr2mnvx",
      "brand": null,
      "last4": null
    },
    "boleto": null,
    "refunded": false,
    "createdAt": "2026-10-23T14:02:11.000Z",
    "completedAt": null
  }
}

Mande o pagador pro paymentLink (página pronta da VamPay) ou direto pro card.checkoutUrl. Depois de pagar, ele volta pra sua completionUrl.

Exemplo: boleto

curlbash

curl -X POST "https://api.vampay.com.br/charges" \
  -H "X-API-Key: vampay_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "BOLETO",
    "amount": 250,
    "payerName": "Mariana Costa",
    "payerDocument": "98765432100",
    "description": "Mensalidade outubro"
  }'

201 Createdjson

{
  "success": true,
  "data": {
    "id": "6ad11d4a5b3f4a0012c9e7b9",
    "method": "BOLETO",
    "status": "PENDING",
    "amount": 250,
    "fee": 2.5,
    "netAmount": 247.5,
    "paymentLink": "https://vampay.com.br/pay/6ad11d4a5b3f4a0012c9e7b9",
    "card": null,
    "boleto": {
      "digitableLine": "23793.38128 60007.827263 37000.963779 4 10010000025000",
      "barCode": "23793381286000782726337000963779410010000025000",
      "url": "https://app.abacatepay.com/pay/bole_k8pqr2mnvx/boleto",
      "expiresAt": "2026-10-28T02:59:59.999Z"
    },
    "refunded": false,
    "createdAt": "2026-10-23T14:05:40.000Z",
    "completedAt": null
  }
}

Mostre a boleto.digitableLine (linha digitável) e o link boleto.url (PDF), ou mande o pagador pro paymentLink.

Webhook

Quando o pagamento confirma, seu webhook recebe transaction.completed, igual a um PIX pago, com paymentMethod = CARD ou BOLETO e o seu externalReference.

transaction.completedjson

{
  "event": "transaction.completed",
  "data": {
    "id": "6ad11c0e5b3f4a0012c9e7a1",
    "externalId": "bill_k8pqr2mnvx",
    "externalReference": "8812",
    "type": "DEPOSIT",
    "paymentMethod": "CARD",
    "status": "COMPLETED",
    "amount": 150,
    "netAmount": 144.15,
    "payerName": "João Silva",
    "completedAt": "2026-10-23T14:03:02.000Z"
  }
}

Erros

Parâmetro	Tipo	Descrição
`400`	erro	Dado inválido: método, valor fora dos limites, CPF/CNPJ inválido ou falta o pagador do boleto
`400 SANDBOX_UNSUPPORTED`	erro	Cartão e boleto não funcionam no modo sandbox
`429`	erro	Muitas cobranças em aberto na última hora
`503 CHARGES_UNAVAILABLE`	erro	Cartão e boleto ainda não foram ativados na plataforma