Coletando Fundos (Pull)
Transações pull (cobrança) retiram fundos do método de pagamento de um cliente. O Inyo Gateway suporta:
- Cartões de Crédito/Débito — Via dados de cartão tokenizados (veja Tokenizando Cartões)
- Transferências Bancárias ACH — Via número de conta bancária e routing number
Todas as transações pull usam o mesmo endpoint:
POST https://{FQDN}/v2/payment
Estrutura da Requisição
Objeto Raiz
| Campo | Tipo | Obrigatório | Descrição |
|---|
externalPaymentId | string | Sim | Seu identificador único de 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 (somente cartões) |
amount | object | Sim | Valor da transação |
sender | object | Sim | Informações do pagador, endereço e método de pagamento |
Objeto amount
| Campo | Tipo | Obrigatório | Descrição |
|---|
total | number | Sim | Valor do pagamento (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 |
paymentMethod | object | Sim | Detalhes do cartão ou da conta bancária |
Objeto sender.address
| Campo | Tipo | Obrigatório | Descrição |
|---|
countryCode | string | Sim | Código de país ISO Alpha-2 (ex.: "US") |
stateCode | string | Sim | Sigla do estado (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 |
sender.paymentMethod — Cartão
| Campo | Tipo | Obrigatório | Descrição |
|---|
type | string | Sim | "CARD" |
cardTokenId | string | Sim | UUID do token do tokenizador |
previousPaymentId | string | Não | Para tokens recorrentes: o paymentId da autorização inicial |
sender.paymentMethod — Conta Bancária (ACH)
| Campo | Tipo | Obrigatório | Descrição |
|---|
type | string | Sim | "BANK_DEPOSIT" |
accountNumber | string | Sim | Número da conta bancária (6–20 dígitos) |
routingNumber | string | Sim | Routing number ABA (9 dígitos) |
accountType | string | Sim | "CHECKING", "SAVINGS", "BUSINESS_CHECKING" ou "BUSINESS_SAVINGS" |
Tokenize → Authorize → (3DS Challenge?) → Capture → (Refund?)
↘ Void
Para pagamentos com cartão:
- Autorizar — Crie o pagamento (
"capture": false para pré-autorização) - Tratar o 3DS — Se
status = CHALLENGE, redirecione para redirectAcsUrl - Capturar — Liquide o pagamento autorizado (em até 7 dias)
- Cancelar (void) — Cancele antes da captura
- Reembolsar — Devolva fundos após a captura (total ou parcial)
Pagamentos ACH
Pagamentos ACH são sempre capturados imediatamente ("capture": true). O ciclo de vida pré-autorização/captura não se aplica.
Veja ACH (Conta Bancária) para um exemplo completo.
O Que Vem a Seguir
