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

	Pré-autorização (`capture: false`)	Captura direta (`capture: true`)
O que acontece	Os fundos são retidos (reservados) no cartão	Os fundos são retidos E liquidados imediatamente
Dinheiro se move?	Não Não — apenas uma retenção (hold)	Sim Sim — a liquidação começa
Para cancelar	Void — instantâneo, nenhum dinheiro se moveu	Reembolso — transação separada, 3–10 dias
O portador vê	Cobrança "pendente"	Cobrança concluída
Limite de tempo	Deve capturar em até 7 dias ou a retenção expira automaticamente	N/A — já capturado
Pode ajustar o valor?	Sim Capturar menos do que o autorizado	Não O valor é final
Melhor para	E-commerce, viagens, assinaturas, qualquer coisa que precise de revisão	Ponto de venda simples, bens digitais instantâneos

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:

Header	Valor
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Corpo da Requisição

Objeto Raiz

Campo	Tipo	Obrigatório	Descrição
`externalPaymentId`	string	Sim	Seu identificador único para este pagamento (chave de idempotência)
`ipAddress`	string	Sim	Endereço IPv4 ou IPv6 do pagador
`paymentType`	string	Sim	`"PULL"`
`capture`	boolean	Sim	`true` = captura automática; `false` = apenas pré-autorização
`amount`	object	Sim	Valor da transação
`sender`	object	Sim	Dados do pagador

Objeto `amount`

Campo	Tipo	Obrigatório	Descrição
`total`	number	Sim	Valor a cobrar (deve ser ≥ 1)
`currency`	string	Sim	Código de moeda ISO 4217 (ex.: `"USD"`)

Objeto `sender`

Campo	Tipo	Obrigatório	Descrição
`firstName`	string	Sim	Primeiro nome do pagador
`lastName`	string	Sim	Sobrenome do pagador
`address`	object	Sim	Endereço de cobrança (usado para verificação AVS)
`paymentMethod`	object	Sim	Detalhes do token do cartão

Objeto `sender.address`

Campo	Tipo	Obrigatório	Descrição
`countryCode`	string	Sim	Código de país ISO Alpha-3 (ex.: `"USA"`)
`stateCode`	string	Sim	Sigla do estado/província (ex.: `"NY"`)
`city`	string	Sim	Nome da cidade
`line1`	string	Sim	Linha 1 do endereço
`line2`	string	Não	Linha 2 do endereço
`zipCode`	string	Sim	Código postal/ZIP

Objeto `sender.paymentMethod` (Cartão)

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	`"CARD"`
`cardTokenId`	string	Sim	UUID do token do tokenizador

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)

{
  "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",
  "status": "AUTHORIZED",
  "captured": false,
  "voided": false,
  "automaticReversed": false,
  "authCode": "48213-BB33-4A6809C4FFF8-USD",
  "responseCode": "00",
  "acquirerMessage": "IN_PROCESS_AUTHORISED",
  "issuerName": "BANK OF AMERICA",
  "issuerCountry": "UNITED STATES",
  "cvcResult": "APPROVED",
  "avsResult": "APPROVED",
  "aniCalled": false,
  "aavAddressResult": "NOT_CHECKED",
  "aavPostcodeResult": "NOT_CHECKED",
  "aavTelephoneResult": "NOT_CHECKED",
  "aavCardholderNameResult": "NOT_CHECKED",
  "riskAssessment": {
    "score": 25,
    "riskLevel": "LOW",
    "recommendation": "PROCEED",
    "signals": [
      {
        "rule": "profile_trust",
        "score": -50,
        "detail": "Established profile email:j***@example.com: 5 captures, 0 challenges, 1 cards"
      },
      {
        "rule": "fingerprint_signals",
        "score": 55,
        "detail": "VPN connection"
      }
    ]
  }
}

O objeto riskAssessment só é retornado quando o produto antifraude da Inyo está habilitado na sua conta. Sem ele, o campo não aparece na resposta — não dependa da sua presenç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:

{
  "paymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
  "parentPaymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
  "externalPaymentId": "order-12345",
  "redirectAcsUrl": "https://{FQDN}/secure-code/start-challenge?token=dce568c6-98ec-456c-bb33-4a6809c4fff8",
  "amount": 99.99,
  "created": "2025-03-31 03:49:05",
  "approved": false,
  "message": "Payment awaiting 3DS challenge verification",
  "status": "CHALLENGE",
  "captured": false,
  "voided": false,
  "automaticReversed": false,
  "authCode": "48213-BB33-4A6809C4FFF8-USD",
  "responseCode": "00",
  "acquirerMessage": "Payment awaiting 3DS challenge verification",
  "issuerName": "BANK OF AMERICA",
  "issuerCountry": "UNITED STATES",
  "cvcResult": "N/A",
  "avsResult": "N/A",
  "aniCalled": false,
  "aavAddressResult": "N/A",
  "aavPostcodeResult": "N/A",
  "aavTelephoneResult": "N/A",
  "aavCardholderNameResult": "N/A",
  "riskAssessment": {
    "score": 30,
    "riskLevel": "MEDIUM",
    "recommendation": "REVIEW",
    "signals": [
      {
        "rule": "new_sender_risk",
        "score": 30,
        "detail": "No sender profile found — first-time customer"
      }
    ]
  }
}

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

Recusado (400)

{
  "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": false,
  "message": "Declined by issuer",
  "status": "DECLINED",
  "captured": false,
  "voided": false,
  "automaticReversed": false,
  "authCode": "48213-BB33-4A6809C4FFF8-USD",
  "responseCode": "PAY_680",
  "issuerName": "BANK OF AMERICA",
  "issuerCountry": "UNITED STATES",
  "cvcResult": "N/A",
  "avsResult": "N/A",
  "aniCalled": false,
  "aavAddressResult": "N/A",
  "aavPostcodeResult": "N/A",
  "aavTelephoneResult": "N/A",
  "aavCardholderNameResult": "N/A",
  "riskAssessment": {
    "score": 0,
    "riskLevel": "LOW",
    "recommendation": "PROCEED",
    "signals": [
      {
        "rule": "bureau_trusted",
        "score": 0,
        "detail": "Known trusted client (3DS-verified) — consistent identity"
      }
    ]
  }
}

Campos da Resposta

Campo	Tipo	Descrição
`paymentId`	string	Identificador único de pagamento da Inyo
`parentPaymentId`	string	ID do pagamento pai (igual ao `paymentId` em autorizações iniciais)
`externalPaymentId`	string	Seu ID externo original
`redirectAcsUrl`	string	URL do challenge 3DS (presente apenas quando `status` = `CHALLENGE`)
`amount`	number	Valor da transação
`created`	string	Timestamp (EST)
`approved`	boolean	`true` se autorizado com sucesso
`message`	string	Mensagem de status legível
`automaticReversed`	boolean	`true` se o pagamento foi revertido automaticamente por regras de fraude
`status`	string	`AUTHORIZED`, `CHALLENGE` ou `DECLINED`
`captured`	boolean	`true` se capturado automaticamente (`"capture": true` na requisição)
`voided`	boolean	`true` se cancelado (voided)
`responseCode`	string	Código de resposta do emissor/gateway (veja Códigos de Resposta)
`authCode`	string	Código de autorização da transação
`acquirerMessage`	string	Mensagem de status bruta do adquirente — apenas informativa; tome decisões com base em `status` e `responseCode` e não a exiba ao usuário final
`issuerName`	string	Nome do banco emissor
`issuerCountry`	string	País do emissor
`cvcResult`	string	`APPROVED`, `FAILED`, `NOT_SENT` ou `N/A`
`avsResult`	string	`APPROVED`, `FAILED`, `NOT_SENT` ou `N/A`
`aniCalled`	boolean	`true` se uma Account Name Inquiry (verificação do nome do titular) foi enviada à bandeira
`aavAddressResult`	string	Resultado da verificação de endereço (ex.: `APPROVED`, `PARTIAL_MATCH`, `FAILED`, `NOT_CHECKED`)
`aavPostcodeResult`	string	Resultado da verificação do código postal (mesmos valores de `aavAddressResult`)
`aavTelephoneResult`	string	Resultado da verificação do telefone (mesmos valores de `aavAddressResult`)
`aavCardholderNameResult`	string	Resultado da verificação do nome do titular (mesmos valores de `aavAddressResult`)
`riskAssessment`	object	Avaliação antifraude do pagamento. Presente apenas quando o produto antifraude da Inyo está habilitado na sua conta

Objeto `riskAssessment`

Retornado apenas quando o produto antifraude da Inyo está habilitado na sua conta. Fale com seu representante Inyo para habilitá-lo.

Campo	Tipo	Descrição
`score`	integer	Score de risco geral do pagamento — quanto maior, mais arriscado
`riskLevel`	string	Faixa de risco derivada do score (ex.: `LOW`, `MEDIUM`)
`recommendation`	string	Ação sugerida para o pagamento (ex.: `PROCEED`, `REVIEW`)
`signals`	array	Regras que contribuíram para o score
`signals[].rule`	string	Identificador da regra acionada (ex.: `profile_trust`, `fingerprint_signals`, `new_sender_risk`, `bureau_trusted`)
`signals[].score`	integer	Contribuição da regra para o score — valores negativos reduzem o risco
`signals[].detail`	string	Explicação legível de por que a regra foi acionada

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