Este guia explica exatamente como cobrar cartão de crédito ou débito via API da Autra, chamada por chamada. Cobre dois fluxos:

Venda direta — você captura o valor imediatamente.
Pré-autorização + captura — você reserva o limite agora e captura depois (ex.: hotel, aluguel de carro, marketplace com confirmação posterior).

Provedor adquirente: Dock. Você não fala com o adquirente — só com a API da Autra.

Conceitos fundamentais

Termo	O que é
Merchant	Estabelecimento cadastrado no tenant (CPF/CNPJ que recebe o dinheiro).
`transactionalToken`	Token de sessão de adquirência, gerado por `/initialize` e usado nas chamadas de pagamento. Válido por poucos minutos.
Tokenização	Substituir os dados sensíveis do cartão (PAN, CVV) por um par `slugToken + slugStoredCard` para reutilizar em cobranças futuras sem PCI.
Pré-autorização	Reserva de limite no cartão sem capturar. Pode virar captura (cobra) ou void (libera o limite).
Split	Dividir o valor recebido entre múltiplos merchants do tenant — `PERCENTUAL` (porcentagem) ou `ABSOLUTE` (valor fixo em BRL).
`orderId`	Chave de idempotência opcional. Mesma `orderId` aprovada não cria 2º pagamento — retorna `409`.

Antes de começar — checklist

Você tem client_id + client_secret da Autra.
Você sabe gerar Bearer JWT via POST /v1/oauth/token.
O merchant (quem recebe) está cadastrado no tenant — documentId é o CPF/CNPJ dele.
Você decidiu o fluxo: venda direta ou pré-autorização.
Você decidiu como vai mandar os dados do cartão: cru (card.*) ou tokenizado (tokenData.*).
(Opcional) Se for parcelar, decidiu número de parcelas (1 = à vista).
(Opcional) Se for split, listou os destinatários — todos precisam ser merchants do tenant.

Resumo dos endpoints

#	O que faz	Endpoint	Quando usar
1	Iniciar sessão	`POST /v1/acquiring/payments/initialize`	Sempre antes de cobrar — gera o `transactionalToken`
2	Cobrar (venda direta)	`POST /v1/acquiring/payments`	Cobrança imediata — captura no mesmo momento
3	Pré-autorizar	`POST /v1/acquiring/payments/pre-authorization`	Reservar limite sem cobrar agora
4	Capturar pré-auth	`POST /v1/acquiring/payments/{paymentId}/capture`	Confirmar a cobrança de uma pré-autorização
5	Cancelar pagamento	`POST /v1/acquiring/payments/{paymentId}/void`	Estornar venda ou liberar pré-auth
6	Tokenizar cartão	`POST /v1/acquiring/tokenize-card`	Salvar o cartão pra cobrar de novo no futuro sem reapresentar os dados

Prefixo: https://api.autra.io. Headers: Authorization: Bearer <JWT>, Content-Type: application/json.

Status do pagamento

Status	Significado
`ACCEPTED`	Aprovado pelo adquirente. Para venda direta, é o status final feliz.
`CAPTURED`	Pré-autorização foi capturada. Status final feliz para o fluxo pré-auth.
`PRE_AUTHORIZED`	Limite reservado, ainda não capturado.
`DECLINED`	Recusado pelo adquirente (saldo, fraude, etc.).
`VOIDED`	Cancelado/estornado.

Quando o adquirente recusa, a resposta vem com errors: [{code, msg}] (ex.: INSUFFICIENT_FUNDS). Não confunda com 400 — 200 com errors[] é "transação processada e recusada", 400 é "request mal-formado".

🟦 Fluxo 1 — Venda direta com cartão cru

Use quando você quer cobrar agora com o cartão digitado no momento.

Passo 1: Inicializar a sessão

POST /v1/acquiring/payments/initialize
Authorization: Bearer <JWT>
Content-Type: application/json

{ "documentId": "12345678901" }

documentId aqui é o portador do cartão (o pagador).

Resposta 200:

{ "transactionalToken": "eyJhbGciOi..." }

✅ Guarde o transactionalToken. Ele vale para a próxima chamada de pagamento. Curta validade (alguns minutos) — não armazene em cache longo.

Passo 2: Criar o pagamento

POST /v1/acquiring/payments
Authorization: Bearer <JWT>

{
  "transactionalToken": "eyJhbGciOi...",
  "documentId":         "12345678000190",
  "transactionType":    "CREDIT",
  "amount":             150.00,
  "currency":           "BRL",
  "installments":       1,
  "orderId":            "pedido-abc-123",
  "card": {
    "number":         "4111111111111111",
    "expirationDate": "12/2027",
    "securityCode":   "123",
    "holderName":     "JOAO SILVA"
  }
}

documentId aqui é o merchant (quem recebe). card.holderName é o nome impresso no cartão.

Resposta 200 aprovada:

{
  "paymentID": "550e8400-e29b-41d4-a716-446655440000",
  "status":    "ACCEPTED",
  "amount":    150.00,
  "currency":  "BRL"
}

Resposta 200 recusada:

{
  "paymentID": "550e8400-...-446655440001",
  "errors": [
    { "code": "INSUFFICIENT_FUNDS", "msg": "insufficient funds" }
  ]
}

⚠️ Sempre cheque o campo status ou errors antes de declarar pago.

Campos importantes

Campo	Obrigatório	Detalhe
`transactionalToken`	sim	Do passo 1.
`documentId`	sim	CPF/CNPJ do merchant (quem recebe).
`transactionType`	sim	`CREDIT` ou `DEBIT`.
`amount`	sim	Em BRL, ex.: `150.00`.
`currency`	sim	Use `BRL`.
`installments`	sim	`1` = à vista. `2-12` = parcelado.
`orderId`	não	Recomendado — chave de idempotência.
`card`	um dos dois	Dados crus (PAN/CVV).
`tokenData`	um dos dois	Cartão tokenizado (slugs).

⚠️ Use card OU tokenData, nunca os dois. Se enviar os dois, o backend recusa.

🟩 Fluxo 2 — Venda com cartão tokenizado

Use quando o cartão já foi tokenizado anteriormente (passo 6 mais abaixo) e você quer cobrar de novo sem pedir os dados.

Passo 1: Inicializar (igual ao fluxo 1)

POST /v1/acquiring/payments/initialize
{ "documentId": "12345678901" }

→ pega o transactionalToken.

Passo 2: Criar pagamento usando `tokenData`

POST /v1/acquiring/payments

{
  "transactionalToken": "eyJhbGciOi...",
  "documentId":         "12345678000190",
  "transactionType":    "CREDIT",
  "amount":             150.00,
  "currency":           "BRL",
  "installments":       1,
  "tokenData": {
    "slugToken":       "slug-token-abc",
    "slugStoredCard":  "slug-stored-card-xyz"
  }
}

✅ Os dois slugs vêm: slugToken do /initialize, slugStoredCard do /tokenize-card (passo 6).

⚠️ Não envie card aqui.

🟨 Fluxo 3 — Pré-autorização + captura

Use quando você quer reservar o valor agora e cobrar depois (ex.: hotel, locadora, comanda de bar).

Passo 1: Pré-autorizar

POST /v1/acquiring/payments/pre-authorization
Authorization: Bearer <JWT>

{
  "documentId": "12345678901",
  "amount":     500.00,
  "currency":   "BRL"
}

Resposta 200:

{
  "paymentId": "550e8400-...-446655440000",
  "status":    "PRE_AUTHORIZED"
}

✅ Guarde o paymentId. O limite do cartão está reservado, mas o cliente ainda não foi cobrado.

Passo 2A: Capturar (cobrar de fato)

POST /v1/acquiring/payments/{paymentId}/capture
Authorization: Bearer <JWT>

{ "amount": 480.00 }

→ status: CAPTURED.

Você pode capturar valor menor que o pré-autorizado — o resto é liberado. Ex.: pré-autorizou R$ 500 (consumo médio do hotel), capturou R$ 480 (consumo real).

Passo 2B: Cancelar a pré-auth (liberar limite)

Se a venda não aconteceu (cliente cancelou, voucher recusado, etc.), libere o limite:

POST /v1/acquiring/payments/{paymentId}/void
Authorization: Bearer <JWT>

→ status: VOIDED. O limite volta para o cartão do cliente em alguns segundos.

🟧 Cancelamento de venda direta

Para estornar uma venda já capturada (ex.: cliente devolveu o produto):

POST /v1/acquiring/payments/{paymentId}/void
Authorization: Bearer <JWT>

→ status: VOIDED.

⚠️ Janela de void varia por bandeira/adquirente — geralmente mesmo dia para o estorno completo. Após esse prazo, vira chargeback/reembolso bancário (operação separada).

🟪 Tokenizar cartão para uso futuro

Se você quer guardar o cartão pra cobrar de novo sem reapresentar os dados:

POST /v1/acquiring/tokenize-card
Authorization: Bearer <JWT>

{ "documentId": "12345678901" }

⚠️ A tokenização real acontece no lado do cliente com o SDK Dock — esta rota da Autra prepara a sessão para a tokenização. Os slugs (slugToken e slugStoredCard) são entregues após o cliente preencher o cartão no SDK.

✅ Depois de tokenizar, use o Fluxo 2 (cartão tokenizado) para cobrar quantas vezes precisar sem pedir os dados de novo.

Split de pagamento

Para dividir o valor recebido entre múltiplos merchants, adicione paymentSplit no POST /payments:

Split percentual (mais comum)

"paymentSplit": {
  "splitType": "PERCENTUAL",
  "splits": [
    { "documentId": "12345678000190", "value": 70 },
    { "documentId": "98765432000111", "value": 30 }
  ]
}

Soma deve dar 100. Cada documentId precisa ser merchant cadastrado no tenant.

Split absoluto

"paymentSplit": {
  "splitType": "ABSOLUTE",
  "splits": [
    { "documentId": "12345678000190", "value": 105.00 },
    { "documentId": "98765432000111", "value":  45.00 }
  ]
}

Soma deve dar exatamente o amount.

⚠️ O merchant dono da venda (raiz do documentId) precisa estar na lista de splits. Se não estiver, recebe 422 SPLIT_MERCHANT_NOT_FOUND.

Idempotência — `orderId`

Sempre que você gerar um pedido, mande um orderId único:

{
  "orderId": "pedido-abc-123",
  ...
}

Se o request falhar com timeout/erro de rede e você reenviar com a mesma orderId, o backend detecta e retorna 409 ORDER_ALREADY_APPROVED (sem duplicar débito).
Se a orderId ainda não existir, processa normalmente.

✅ Recomendação: sempre use orderId em produção. Sem ela, retry de rede vira cobrança duplicada no cliente.

Erros comuns

Code	HTTP	O que fazer
`BAD_REQUEST`	400	Campo obrigatório faltando ou inválido. Cheque o JSON.
`INSUFFICIENT_FUNDS`	200*	Cartão sem saldo. Notificar cliente. *Vem em `errors[]` dentro de 200.
`CARD_DECLINED`	200*	Recusa genérica. Pode ser fraude, dados errados, banco bloqueando.
`ORDER_ALREADY_APPROVED`	409	`orderId` já foi aprovada antes. Não recobrar.
`MERCHANT_NOT_FOUND`	422	`documentId` (do merchant) não está cadastrado no tenant.
`SPLIT_MERCHANT_NOT_FOUND`	422	Algum `documentId` em `paymentSplit.splits[]` não é merchant do tenant.
`ACQUIRER_COMMUNICATION_ERROR`	500	Falha ao falar com o adquirente. Retry com backoff.
`PAYMENT_NOT_FOUND`	404	`paymentId` (em capture/void) não existe.

⚠️ Status 200 com errors[] ≠ erro de API. Significa "transação processada e recusada pelo adquirente". Trate diferente de 400/500.

Boas práticas

Sempre use orderId em produção — protege contra cobrança duplicada em retry de rede.
Cache JWT (do /oauth/token), não gere a cada request.
Não cache transactionalToken — é de curta validade. Gere um novo por venda.
Tokenize cartões recorrentes — evita PCI, melhora UX (cliente não digita de novo).
Pré-autorização para valores incertos — hotel, locadora, comanda de bar.
Trate 200 + errors[] como recusa, não como erro de servidor.
Para split, pré-valide os documentId listando merchants em GET /v1/acquiring/merchants (rota da categoria Payment Links).
Logs: nunca logar PAN, CVV ou securityCode. Mascare antes.

FAQ

Posso reaproveitar o transactionalToken em várias vendas? Não. Gere um novo a cada venda. É curto e barato.

Qual a diferença entre card e tokenData? card envia PAN/CVV (precisa de PCI no seu lado). tokenData envia slugs já tokenizados (sem dados sensíveis).

Quanto tempo dura uma pré-autorização? Padrão da bandeira — geralmente 5 a 7 dias. Após isso, expira automaticamente e o limite volta. Confirme com o banco emissor se for caso crítico.

Posso capturar mais que o pré-autorizado? Não. Apenas valor igual ou menor. Se precisar mais, faça uma nova venda direta pela diferença.

Posso fazer split em débito? Sim. Funciona em CREDIT e DEBIT igualmente.

Cancelei uma venda hoje. O cliente vê o estorno? Se feito no mesmo dia (antes do batch do adquirente), vira VOIDED e o débito nem aparece no extrato do cliente. Após o batch, vira reembolso (aparece como crédito no próximo ciclo).

Recebi 200 com status: ACCEPTED, mas o cliente reclama que não foi pago. Cheque se você não chamou /void depois. Em produção, monitore os webhooks do Dock e o histórico de eventos do paymentID.

Posso usar este fluxo para Pix ou Boleto? Não. Esta categoria cobre cartão. Para Pix avulso → Pix Checkout. Para Pix recorrente → Pix Automático. Para boleto → Banking. Para um link único que aceita os 3 → Payment Links.