Skip to main content
POST
Criar nova transação

Idempotência

Timeouts e falhas de rede deixam a dúvida: a cobrança foi criada ou não? Envie um identificador único por pedido no header Idempotency-Key.
O escopo da chave é o seu projeto. Use até 256 caracteres. Um UUID ou o ID do pedido são boas escolhas. Ao repetir após timeout, use a mesma chave da tentativa original.

HTTP 202

202 não é erro. O PIX foi gerado, mas a persistência ainda está em reconciliação:
  • data.id pode vir null. Use data.externalId como referência.
  • O pixCode é válido e pagável. Entregue ao comprador normalmente.
  • A transação aparece na listagem em alguns minutos.
A criação pode levar até 30 segundos. Configure o timeout do cliente HTTP acima disso.

Erros

Toda resposta 4xx/5xx segue o RFC 7807:
Trate erros pelo status + type. As mensagens podem mudar; os códigos não. Não use o retorno da criação como confirmação financeira. Libere o pedido só depois de transaction.paid. Veja como validar o webhook.

Authorizations

Authorization
string
header
required

Autenticação por API Key usando token SK (sk_live_xxx ou sk_test_xxx). Envie como: Authorization: Bearer sk_live_xxx

Body

application/json
customer
object
required
originDomain
string
required

Domínio da loja/site que originou a transação (ex: loja.exemplo.com.br). Obrigatório para rastreio de múltiplas lojas. Use apenas o hostname, sem protocolo ou caminho.

Required string length: 1 - 253
payment
object
required
customerIp

IP do usuário final que originou a requisição (IPv4 ou IPv6). Quando informado, é usado para detecção de fraude e bloqueio de IPs.

Pattern: ^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$
paymentMethod
enum<string>
default:pix

Método de pagamento da transação. Use "pix" ou omita o campo para aplicar o default.

Available options:
pix

Response

Default Response

data
object
required
success
boolean
default:true
required
billingWarning
string
message
string