Autorizando um Pagamento com Cartão

Após tokenizar um cartão, envie o token para criar uma autorização de pagamento. Você pode escolher entre:

• Pré-autorização ("capture": false) — Reserva os fundos sem liquidar. Você captura depois, quando estiver pronto.
• Captura direta ("capture": true) — Autoriza e captura em uma única etapa. Os fundos são liquidados imediatamente.

Entendendo Pré-Autorização vs. Captura Direta

Este é um dos conceitos mais mal compreendidos em pagamentos com cartão. Acertar isso determina quanto controle você tem sobre o fluxo do seu dinheiro — e com que rapidez você pode reverter uma transação se algo der errado.

O que é pré-autorização?

Quando você define "capture": false, o gateway pede ao banco do portador do cartão que reserve os fundos no cartão — mas nenhum dinheiro se move ainda. O portador vê uma cobrança "pendente" no extrato, mas a liquidação (a transferência real dos fundos para a sua conta) não acontece até que você capture o pagamento explicitamente.

Pense nisso como colocar uma retenção (hold) sobre os fundos. O dinheiro ainda está na conta do portador do cartão, mas ele não pode gastá-lo em outro lugar.

Por que usar pré-autorização?

A pré-autorização lhe dá uma janela para realizar verificações adicionais antes de se comprometer com a liquidação financeira:

• Verificação AVS / CVC — Analise os resultados de endereço e código de segurança na resposta de autorização. Se indicarem risco de fraude, você pode cancelar imediatamente.
• Análise antifraude — Passe a transação pelo seu sistema de pontuação de fraude, filas de revisão manual ou ferramentas antifraude de terceiros.
• Verificações de estoque / fulfillment — Confirme que o item está em estoque, que o serviço está disponível ou que qualquer validação específica do negócio passa.
• Conformidade / KYC — Verifique se o cliente atende aos requisitos regulatórios antes de finalizar a transação.
• Ajustes no pedido — O valor final pode diferir da retenção inicial (ex.: envios parciais). Você pode capturar um valor menor do que o autorizado.

A vantagem principal: reversão rápida e limpa

Se você precisar cancelar uma transação pré-autorizada, você realiza um cancelamento (void). Um void libera instantaneamente a retenção sobre os fundos do portador — normalmente em minutos. O portador vê a cobrança pendente desaparecer do extrato. Nenhum dinheiro chegou a se mover, então não há nada a "devolver".

Compare isso com o que acontece após a captura: uma vez que a transação é capturada, a liquidação ocorreu. O dinheiro saiu da conta do portador e chegou na sua. A única maneira de devolver os fundos nesse ponto é um reembolso, que é uma transação financeira separada e pode levar de 3 a 10 dias úteis para aparecer no extrato do portador.

Comparação lado a lado

Quando usar cada um

Use pré-autorização (capture: false) quando:

• Você precisa de tempo para verificar sinais de fraude, resultados de AVS/CVC ou conformidade
• O valor final pode mudar (envios parciais, gorjetas, despesas extras de hotel)
• Você quer a possibilidade de cancelar de forma limpa sem que um reembolso apareça no extrato do portador
• Seu fulfillment tem qualquer atraso entre o pagamento e a entrega

Use captura direta (capture: true) quando:

• A transação é final e imediata (download digital, compra em loja física)
• Nenhuma revisão ou ajuste é necessário
• Você quer a integração mais simples com menos chamadas de API

O ciclo de vida em resumo

                 capture: false                    capture: true
                 ─────────────                     ─────────────
POST /v2/payment                          POST /v2/payment
       │                                         │
       ▼                                         ▼
   AUTHORIZED                                CAPTURED
   (funds held)                              (funds settled)
       │                                         │
   ┌───┴───┐                                     ▼
   │       │                                  REFUNDED
   ▼       ▼                               (3-10 days to
CAPTURED  VOIDED                            cardholder)
(settle)  (release hold,
   │       instant)
   ▼
REFUNDED
(3-10 days)

Resumindo: Se houver qualquer chance de você precisar cancelar a transação após a autorização, use pré-autorização. É mais rápido de reverter, mais limpo para o portador do cartão e lhe dá controle total sobre o momento da liquidação.

Endpoint

POST https://{FQDN}/v2/payment

Headers:

Corpo da Requisição

Objeto Raiz

Objeto amount

Objeto sender

Objeto sender.address

Objeto sender.paymentMethod (Cartão)

Exemplo de Requisição

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "order-12345",
    "ipAddress": "203.0.113.42",
    "paymentType": "PULL",
    "capture": false,
    "amount": {
      "total": 99.99,
      "currency": "USD"
    },
    "sender": {
      "firstName": "John",
      "lastName": "Smith",
      "address": {
        "countryCode": "US",
        "stateCode": "NY",
        "city": "New York",
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "zipCode": "10001"
      },
      "paymentMethod": {
        "type": "CARD",
        "cardTokenId": "ab5fc589-8b48-4531-94c0-68b0629c13fe"
      }
    }
  }'

Resposta

Autorização Bem-sucedida (200)

{
  "status": 200,
  "data": {
    "paymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
    "parentPaymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
    "externalPaymentId": "order-12345",
    "amount": 99.99,
    "created": "2025-03-31 03:49:05",
    "approved": true,
    "message": "Payment Approved",
    "automaticReversed": false,
    "status": "AUTHORIZED",
    "captured": false,
    "voided": false,
    "responseCode": "00",
    "issuerName": "BANK OF AMERICA",
    "issuerCountry": "UNITED STATES",
    "cvcResult": "APPROVED",
    "avsResult": "APPROVED",
    "avsCardholderNameResult": "N/A",
    "avsTelephoneResult": "N/A"
  }
}

Challenge 3DS Necessário (200)

Quando o banco emissor exige a verificação do portador do cartão, a resposta retorna status: "CHALLENGE" com um redirectAcsUrl:

{
  "status": 200,
  "data": {
    "paymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
    "externalPaymentId": "order-12345",
    "redirectAcsUrl": "https://{FQDN}/secure-code/start-challenge?token=dce568c6-...",
    "amount": 99.99,
    "approved": false,
    "message": "Payment awaiting 3DS challenge verification",
    "status": "CHALLENGE",
    "captured": false,
    "voided": false,
    "responseCode": "00",
    "cvcResult": "N/A",
    "avsResult": "N/A"
  }
}

Quando você receber CHALLENGE, redirecione o portador do cartão para o redirectAcsUrl. Veja Tratando o 3D Secure para o fluxo completo.

Recusado (400)

{
  "status": 400,
  "data": {
    "paymentId": "abc12345-...",
    "externalPaymentId": "order-12345",
    "amount": 99.99,
    "approved": false,
    "message": "Not sufficient funds",
    "status": "DECLINED",
    "responseCode": "PAY_084"
  }
}

Campos da Resposta

Usando um Token Recorrente

Se o cartão foi tokenizado com storeLaterUse: true, você pode reutilizar o token para cobranças futuras incluindo o previousPaymentId:

{
  "sender": {
    "paymentMethod": {
      "type": "CARD",
      "cardTokenId": "ab5fc589-8b48-4531-94c0-68b0629c13fe",
      "previousPaymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8"
    }
  }
}

O Que Vem a Seguir

• Autorizado? → Capture o pagamento quando estiver pronto para liquidar
• Precisa cancelar? → Cancele (void) a autorização antes da captura
• Challenge 3DS? → Trate o fluxo de redirecionamento do 3D Secure
• Conferir a verificação? → Resultados de AVS / CVC