Criar cobrança

POST/v1/charges

Cria 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ódigos de erro
CódigoHTTPQuando acontece
VALIDATION_ERROR422Campo ausente, com formato errado, desconhecido ou fora do permitido.
IDEMPOTENCY_KEY_REQUIRED400Faltou o cabeçalho Idempotency-Key.
IDEMPOTENCY_KEY_REUSED409A Idempotency-Key já foi usada com outro corpo. Use uma chave nova por pedido.
EXTERNAL_ID_CONFLICT409Já existe uma cobrança com este externalId e dados diferentes.
API_KEY_INVALID401Chave de API inválida, revogada ou vencida.
API_KEY_SCOPE403A chave não tem o escopo (none, read, write) do recurso.
IP_NOT_ALLOWED403O IP da requisição não está na lista da chave.
MERCHANT_SUSPENDED403A empresa está suspensa: a API recusa as chamadas.
AMOUNT_TOO_LOW422O valor não cobre a tarifa.
RISK_DECLINED422Recusada pela análise de risco. A resposta não diz o motivo.
PROVIDER_UNAVAILABLE503Nenhum provedor disponível para o método agora. Pode tentar de novo com a mesma Idempotency-Key.
Exemplo de erro
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.created
  • charge.paid
  • charge.expired
  • charge.canceled
  • charge.failed
  • charge.refunded
  • charge.partially_refunded
  • dispute.created

O que cada um traz está em Eventos.