Criar cobrança
POST/v1/chargesCria uma cobrança PIX e devolve o checkoutUrl para mandar ao cliente. A cobrança nasce com status PENDING e muda quando o pagador paga ou o prazo acaba; você fica sabendo pelos webhooks.
Valores sempre em texto decimal com a moeda ao lado. "150.00" é certo; o número 150 volta VALIDATION_ERROR.
Cabeçalhos
AuthorizationtextoobrigatórioBearer com a sua chave: sk_test_… no teste, sk_live_… em produção.Idempotency-KeytextoobrigatórioUm valor único por pedido (ex.: o número do pedido), até 255 caracteres visíveis, sem espaços. Mesmo corpo de novo: a resposta guardada, com Idempotent-Replayed: true. Outro corpo: 409. Vale por 7 dias.Content-Typetextoobrigatórioapplication/json
Corpo
amounttextoobrigatórioValor em texto decimal com ponto, ex.: "150.00", até as casas da moeda (BRL: 2; COP em pesos inteiros, sem centavos). Número (150) volta VALIDATION_ERROR.currencytextoobrigatório"BRL" (PIX). MXN (SPEI), COP (PSE, Nequi e Bre-B) e USDT: em breve.descriptiontextoopcionalAté 500 caracteres. Aparece no checkout e no extrato. Ex.: "Plano Pro".customer.nametextoopcionalNome de quem paga, até 160 caracteres.customer.document.typetextoopcional"CPF" ou "CNPJ" em BRL; em COP, "CC", "CE", "NIT", "PA", "PPT", "TI", "RC", "TE" ou "DIE".customer.document.numbertextoopcionalNúmero do documento, com ou sem pontuação. O CNPJ pode ser alfanumérico.customer.emailtextoopcionalE-mail de quem paga.customer.phonetextoopcionalTelefone de quem paga, com DDI e DDD, ex.: "+5511999998888". Em COP, o celular colombiano (10 dígitos começando com 3, com ou sem +57).customer.bankCodetextoopcionalSó em COP com PSE: o banco de quem paga, um código de GET /v1/banks?method=PSE.expiresInnúmeroopcionalValidade em segundos, de 300 (5 min) a 604800 (7 dias). Padrão: 1800 (30 min).returnUrlURLopcionalEndereço do link "Voltar para a sua empresa" no checkout (o checkout não redireciona sozinho). Só https, até 2048 caracteres.metadataobjetoopcionalAté 20 chaves suas (nome até 40 caracteres; valor texto até 500, número, booleano ou null), devolvidas na cobrança e nos webhooks.externalIdtextoopcionalO identificador do pedido no seu sistema, até 120 caracteres, único por empresa e ambiente. Repetir com o mesmo conteúdo devolve a cobrança existente (200); com outro conteúdo, 409 EXTERNAL_ID_CONFLICT.methodslistaopcionalO meio da moeda: ["PIX"] em BRL. Sem o campo, vale o meio padrão da moeda. Em COP é obrigatório e é um só: "PSE", "NEQUI" ou "BREB".splitslistaopcionalAté 10 divisões só desta cobrança, além das regras permanentes: recipientId (destinatário cadastrado no painel) com percent ou amount.
Só amount e currency são obrigatórios. Escopo da chave: charges em write.
Mande o nome e o CPF/CNPJ de quem paga sempre que tiver. Em produção, há provedores de PIX que exigem esses dados: sem eles, a rota pula esse provedor e, se nenhum outro servir, a resposta é 503 PROVIDER_UNAVAILABLE. A plataforma nunca preenche dado de pagador por você.
Em COP, os bancos e carteiras da Colômbia exigem nome, documento, e-mail e celular de quem paga, e o banco no PSE (customer.bankCode). Faltando algum, a resposta é 422 VALIDATION_ERROR com os campos em error.details. O pagador conclui na página do banco ou da carteira: em attempt.instructions vem kind: "REDIRECT" com o url, e o checkout leva até ela.
Respostas
- 201CreatedA cobrança foi criada com status "PENDING". Traz fee, net, checkoutUrl e, em attempt.instructions, o PIX copia e cola. Numa repetição com o mesmo corpo, vem com Idempotent-Replayed: true.
- 200OKO externalId já existia com o mesmo conteúdo: devolve a cobrança existente, sem criar outra.
- 401UnauthorizedAPI_KEY_INVALID: chave inválida, revogada ou vencida.
- 403ForbiddenAPI_KEY_SCOPE: a chave não tem write em charges. IP_NOT_ALLOWED: o IP não está na lista da chave.
- 409ConflictIDEMPOTENCY_KEY_REUSED: a mesma chave já foi usada com outro corpo. EXTERNAL_ID_CONFLICT: o externalId já existe com outro conteúdo.
- 422Unprocessable EntityVALIDATION_ERROR: algum campo não passou; veja error.details. Campos desconhecidos também são recusados.
- 503Service UnavailablePROVIDER_UNAVAILABLE ou CHARGES_DISABLED: nada foi criado. Tente de novo com a mesma Idempotency-Key.
O recurso completo, campo a campo, está em Consultar cobrança.
Erros
Todo erro vem no mesmo formato: success: false, message em português, statusCode e error.code em inglês, com error.details (path e message) quando for de campo. Veja Formato de erro.
| Código | HTTP | Quando acontece |
|---|---|---|
VALIDATION_ERROR | 422 | Campo ausente, com formato errado, desconhecido ou fora do permitido. |
IDEMPOTENCY_KEY_REQUIRED | 400 | Faltou o cabeçalho Idempotency-Key. |
IDEMPOTENCY_KEY_REUSED | 409 | A Idempotency-Key já foi usada com outro corpo. Use uma chave nova por pedido. |
EXTERNAL_ID_CONFLICT | 409 | Já existe uma cobrança com este externalId e dados diferentes. |
API_KEY_INVALID | 401 | Chave de API inválida, revogada ou vencida. |
API_KEY_SCOPE | 403 | A chave não tem o escopo (none, read, write) do recurso. |
IP_NOT_ALLOWED | 403 | O IP da requisição não está na lista da chave. |
MERCHANT_SUSPENDED | 403 | A empresa está suspensa: a API recusa as chamadas. |
AMOUNT_TOO_LOW | 422 | O valor não cobre a tarifa. |
RISK_DECLINED | 422 | Recusada pela análise de risco. A resposta não diz o motivo. |
PROVIDER_UNAVAILABLE | 503 | Nenhum provedor disponível para o método agora. Pode tentar de novo com a mesma Idempotency-Key. |
HTTP/1.1 422 Unprocessable Entity
{
"success": false,
"message": "Dados inválidos",
"statusCode": 422,
"error": {
"code": "VALIDATION_ERROR",
"details": [
{ "path": "/amount", "message": "Use uma string decimal com ponto, ex.: \"150.00\"" }
]
}
}Webhooks desta cobrança
charge.createdcharge.paidcharge.expiredcharge.canceledcharge.failedcharge.refundedcharge.partially_refundeddispute.created
O que cada um traz está em Eventos.