Cards

PCI — como o número do cartão chega até nós

O SDK/API pública nunca aceita um PAN (número do cartão) cru — todo pagamento de cartão recebe um cardToken, obtido antes via um passo de tokenização do seu lado cliente (hosted fields/Checkout SDK), nunca digitado direto no seu backend. Isso mantém seu servidor fora do escopo PCI-DSS de armazenamento de dados de cartão.

Em sandbox, um cardToken sintético (ex.: tok_test_1234) já funciona sem tokenização real — ver Sandbox.

Venda direta (authorize + capture em uma chamada)

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

const payment = await gateway.payments.create({
  amountInCents: 5000,
  method: 'credit_card',
  cardToken: 'tok_...',
  installments: 1,
});

method: "debit_card" segue exatamente a mesma forma (débito não tem installments relevante).

Autorizar e capturar depois

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

// mais tarde:
await gateway.payments.capture(authorized.id);
// ou:
await gateway.payments.cancel(authorized.id);

Útil quando você precisa confirmar disponibilidade/fraude antes de cobrar de fato — a autorização reserva o limite no cartão sem mover dinheiro.

Recusa (declined)

Uma recusa não é um erro HTTP — é um resultado de negócio normal, 200 OK com status: "failed" e o detalhe em card.status: "declined":

{ "id": "...", "status": "failed", "card": { "status": "declined" } }

Parcelamento

installments (inteiro ≥ 1) é repassado ao adquirente/provider configurado — juros e limite máximo de parcelas são política do seu provider de cartão, não da API.

3D Secure

threeDsSessionId (opcional) é aceito no corpo pra correlacionar uma sessão 3DS já iniciada no seu frontend — o fluxo de desafio em si (renderizar o iframe do emissor) acontece client-side, fora desta API.