Payments

/v1/payments cria e gerencia pagamentos de qualquer método (pix, credit_card, debit_card, boleto) através de um único corpo — method decide o resto. Pra uma resposta já formatada especificamente pra PIX (com qrCode/copyPaste) ou boleto (com barcode/digitableLine), veja as páginas PIX e Boleto — internamente é o mesmo pagamento, só a projeção da resposta muda.

Criar um pagamento

cURL

curl -X POST https://api.gateway.example/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amountInCents": 5000,
    "method": "credit_card",
    "cardToken": "tok_..."
  }'

TypeScript

const payment = await gateway.payments.create(
  { amountInCents: 5000, method: 'credit_card', cardToken: 'tok_...' },
  { idempotencyKey: 'order-1042' },
);

{
  "id": "9f34270f-04c9-4fd5-90ad-9e4179cdb230",
  "object": "payment",
  "status": "paid",
  "method": "credit_card",
  "amountInCents": 5000,
  "currency": "BRL",
  "merchantId": "merchant_...",
  "customerId": null,
  "description": null,
  "metadata": null,
  "createdAt": "2026-08-25T19:44:24.674Z",
  "updatedAt": "2026-08-25T19:44:24.797Z",
  "card": { "status": "captured", "last4": "1234", "cardBrand": "..." }
}

Autorizar sem capturar

Passe capture: false pra reservar o valor no cartão sem cobrar de verdade — útil pra confirmar estoque/fraude antes de capturar de fato:

const authorized = await gateway.payments.create({
  amountInCents: 5000,
  method: 'credit_card',
  cardToken: 'tok_...',
  capture: false,
});
// authorized.status === 'authorized'

const captured = await gateway.payments.capture(authorized.id);
// ou, pra desistir sem cobrar:
await gateway.payments.cancel(authorized.id);

Uma autorização não capturada nunca posta nada no ledger — o dinheiro só "sai" de verdade na captura.

Consultar

const payment = await gateway.payments.get('pay_123');

Status possíveis

`status`	Significado
`created`	Sessão criada, pagamento ainda não submetido.
`processing`	Submissão em andamento.
`authorized`	Cartão autorizado, não capturado ainda.
`paid`	Aprovado — dinheiro reservado/movido.
`failed`	Recusado ou erro.
`pending_payment`	PIX/boleto emitido, aguardando pagamento assíncrono.
`canceled`	Autorização cancelada antes de capturar.
`refunded`	Estornado (ver nota abaixo).

Nota

refunded aqui é conceitual — o campo status da resposta reflete o status da sessão de checkout (que permanece paid), não do ledger. Pra saber se um pagamento foi estornado, confira o histórico via Backoffice ou trate o webhook payment.refunded.

Estornar

await gateway.payments.refund('pay_123');

Estorno é sempre total nesta entrega — refund parcial não está implementado (amountInCents opcional no corpo é ignorado se enviado). Só funciona em pagamentos paid.

Split

/v1/payments não tem um campo de split direto no corpo — split é uma regra do merchant (quem recebe o quê de cada venda), configurada uma vez e aplicada automaticamente em toda cobrança que casar com ela. Ver Splits.