Push Transaction

Transações push (payout) transferem fundos para um destinatário. O Inyo Gateway suporta múltiplos métodos de destino:

Cartões — Visa Direct / Mastercard Send (nacional e internacional)
Contas Bancárias — Payouts internacionais para conta
PIX — Pagamentos instantâneos brasileiros
Carteiras — Payouts para carteiras digitais

Endpoint

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

Cabeçalhos:

Cabeçalho	Valor
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Estrutura da Requisição

Os objetos sender e recipient usam a mesma estrutura plana de uma transação pull — firstName, lastName e address. O recipient adicionalmente contém um paymentMethod descrevendo o destino do payout.

Objeto Raiz

Campo	Tipo	Obrigatório	Descrição
`externalPaymentId`	string	Sim	Seu identificador único de pagamento (chave de idempotência)
`fxId`	string	Sim	Identificador da cotação de câmbio do endpoint Foreign Exchange
`ipAddress`	string	Sim	Endereço IPv4 ou IPv6 do originador
`paymentType`	string	Sim	`"PUSH"`
`amount`	object	Sim	Valor de origem (o que você está enviando)
`recipientAmount`	object	Sim	Valor de destino (o que o destinatário recebe)
`sender`	object	Sim	Dados e endereço do remetente
`recipient`	object	Sim	Dados, endereço e método de payout do destinatário
`capture`	boolean	Não	Somente cartões — `false` para pré-autorização, `true` para capturar imediatamente
`additionalData`	object	Não	Metadados chave/valor opcionais anexados ao pagamento

Objeto `amount` (Origem)

Campo	Tipo	Obrigatório	Descrição
`total`	number	Sim	Valor a enviar (deve ser ≥ 1)
`currency`	string	Sim	Moeda de origem (ISO 4217, ex.: `"USD"`)

Objeto `recipientAmount` (Destino)

Campo	Tipo	Obrigatório	Descrição
`total`	number	Sim	Valor que o destinatário recebe
`currency`	string	Sim	Moeda de destino (ISO 4217, ex.: `"BDT"`)

Objeto `sender`

Campo	Tipo	Obrigatório	Descrição
`firstName`	string	Sim	Primeiro nome do remetente
`lastName`	string	Sim	Sobrenome do remetente
`address`	object	Sim	Endereço do remetente

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	Abreviação do estado (ex.: `"MA"`)
`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 `recipient`

Campo	Tipo	Obrigatório	Descrição
`firstName`	string	Sim	Primeiro nome do destinatário
`lastName`	string	Sim	Sobrenome do destinatário
`address`	object	Sim	Endereço do destinatário
`paymentMethod`	object	Sim	Método e dados do payout

Objeto `recipient.address`

Mesmos campos de sender.address.

Os campos de identidade e endereço do destinatário variam por país de destino. Quais campos são obrigatórios e suas regras de validação não são fixos — eles mudam por corredor. Por exemplo, as Filipinas exigem um stateCode de um enum fixo de códigos de província, o Brasil exige um CPF via array documents (11 dígitos, com validação de dígito verificador) e a maioria dos corredores da UE torna o endereço opcional. Sempre consulte o Person Schema (GET /schema/person?countryCode=<ISO3>) do país de destino e construa o recipient a partir do schema retornado, em vez de codificar os campos acima de forma fixa.

`recipient.paymentMethod` — Cartão

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	`"CARD"`
`cardTokenId`	string	Sim	Identificador do cartão tokenizado

`recipient.paymentMethod` — Conta Bancária

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	`"BANK_DEPOSIT"`
`countryCode`	string	Sim	Código de país ISO Alpha-3 do banco de destino (ex.: `"BGD"`)
`bankCode`	string	Sim	Código do banco/agência de destino
`accountNumber`	string	Sim	Número da conta bancária do destinatário
`walletType`	string	Não	Tipo do identificador da conta (ex.: `"PHONENUMBER"`)

Os campos de conta bancária variam por país de destino. O conjunto de campos, quais são obrigatórios e suas regras de validação não são fixos — eles mudam por corredor. Por exemplo, o Brasil exige um código de agência (routingNumber / agência) e um documento CPF, enquanto o México omite routingNumber por completo porque a CLABE (accountNumber) já codifica o banco. Sempre consulte o Account Schema (GET /schema/account?countryCode=<ISO3>) do país de destino e construa o paymentMethod a partir do schema retornado, em vez de codificar os campos acima de forma fixa. A tabela acima é um exemplo concreto (Bangladesh), não o formato canônico para todos os países.

`recipient.paymentMethod` — PIX

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	`"PIX"`
`pix.keyType`	string	Sim	`"EMAIL"`, `"PHONE"`, `"DOCUMENT"` (CPF/CNPJ) ou `"EVP"` (chave aleatória)
`pix.key`	string	Sim	O valor da chave PIX

`recipient.paymentMethod` — Carteira

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	`"WALLET"`
`wallet.walletId`	string	Sim	Identificador da carteira (e-mail ou ID)

Exemplo — Push para Cartão

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "push-card-001",
    "fxId": "65a4d3b6-eb33-4614-a3f6-d2d6cc9fb047",
    "ipAddress": "203.0.113.42",
    "paymentType": "PUSH",
    "capture": false,
    "amount": {
      "total": 123,
      "currency": "USD"
    },
    "recipientAmount": {
      "total": 103.930818,
      "currency": "EUR"
    },
    "sender": {
      "firstName": "John",
      "lastName": "Smith",
      "address": {
        "countryCode": "USA",
        "stateCode": "NY",
        "city": "New York",
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "zipCode": "10001"
      }
    },
    "recipient": {
      "firstName": "Carlos",
      "lastName": "García",
      "address": {
        "countryCode": "ESP",
        "stateCode": "MD",
        "city": "Madrid",
        "line1": "Calle Gran Vía, 42",
        "line2": "Piso 3B",
        "zipCode": "28013"
      },
      "paymentMethod": {
        "type": "CARD",
        "cardTokenId": "778303bb-1441-4378-b923-77ecf414cffd"
      }
    }
  }'

Exemplo — Push para Conta Bancária

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "push-bank-001",
    "fxId": "65a4d3b6-eb33-4614-a3f6-d2d6cc9fb047",
    "ipAddress": "203.0.113.42",
    "paymentType": "PUSH",
    "amount": {
      "total": 5,
      "currency": "USD"
    },
    "recipientAmount": {
      "total": 610.25,
      "currency": "BDT"
    },
    "sender": {
      "firstName": "Samir",
      "lastName": "Filho",
      "address": {
        "countryCode": "USA",
        "stateCode": "MA",
        "city": "Somerville",
        "line1": "45 prospect st",
        "zipCode": "02143"
      }
    },
    "recipient": {
      "firstName": "Rana",
      "lastName": "Hossain",
      "address": {
        "countryCode": "BGD",
        "city": "Joypurhat",
        "line1": "Ansar Ali Complex, 110/1 Sadar Road",
        "zipCode": "5900"
      },
      "paymentMethod": {
        "type": "BANK_DEPOSIT",
        "countryCode": "BGD",
        "bankCode": "090120107",
        "accountNumber": "00002481510154436",
        "walletType": "PHONENUMBER"
      }
    },
    "additionalData": {}
  }'

Exemplo — Push para PIX

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "push-pix-001",
    "fxId": "a1b2c3d4-eb33-4614-a3f6-d2d6cc9fb047",
    "ipAddress": "203.0.113.42",
    "paymentType": "PUSH",
    "amount": {
      "total": 55,
      "currency": "USD"
    },
    "recipientAmount": {
      "total": 273.63,
      "currency": "BRL"
    },
    "sender": {
      "firstName": "John",
      "lastName": "Smith",
      "address": {
        "countryCode": "USA",
        "stateCode": "CA",
        "city": "Los Angeles",
        "line1": "4429 Candlewood St",
        "zipCode": "90712"
      }
    },
    "recipient": {
      "firstName": "Carlos",
      "lastName": "Silva",
      "address": {
        "countryCode": "BRA",
        "stateCode": "RJ",
        "city": "Rio de Janeiro",
        "line1": "Rua das Laranjeiras 321",
        "zipCode": "22240-005"
      },
      "paymentMethod": {
        "type": "PIX",
        "pix": {
          "keyType": "DOCUMENT",
          "key": "01034861788"
        }
      }
    }
  }'

Exemplo — Push para Carteira

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "push-wallet-001",
    "fxId": "a1b2c3d4-eb33-4614-a3f6-d2d6cc9fb047",
    "ipAddress": "203.0.113.42",
    "paymentType": "PUSH",
    "amount": {
      "total": 100,
      "currency": "USD"
    },
    "recipientAmount": {
      "total": 497.50,
      "currency": "BRL"
    },
    "sender": {
      "firstName": "Jane",
      "lastName": "Doe",
      "address": {
        "countryCode": "USA",
        "stateCode": "NY",
        "city": "New York",
        "line1": "456 Park Avenue",
        "zipCode": "10022"
      }
    },
    "recipient": {
      "firstName": "Ana",
      "lastName": "Souza",
      "address": {
        "countryCode": "BRA",
        "stateCode": "RJ",
        "city": "Rio de Janeiro",
        "line1": "Rua da Alfândega 45",
        "zipCode": "20010-030"
      },
      "paymentMethod": {
        "type": "WALLET",
        "wallet": {
          "walletId": "[email protected]"
        }
      }
    }
  }'

Foreign Exchange

Para pagamentos push entre moedas, obtenha uma taxa de câmbio antes de submeter. Passe o fxId retornado na sua requisição de pagamento — o gateway aplica a taxa cotada associada a esse fxId.

Consulte a documentação completa de Foreign Exchange para schemas detalhados de requisição/resposta, incluindo o endpoint v2 com taxas específicas por método de pagamento.

Exemplo rápido (v1):

curl -X POST https://{FQDN}/foreign-exchange \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceCurrencyCode": "USD",
    "destinationCurrencyCode": "BRL"
  }'

{
  "fxId": "a1b2c3d4-...",
  "conversionRate": 4.975,
  "quoteIdExpiryDateTime": "2025-03-31T15:30:00Z"
}

Nota: as cotações de câmbio têm um período de validade limitado. Verifique quoteIdExpiryDateTime e renove se estiver expirada.

Push Transaction

Endpoint

Estrutura da Requisição

Objeto Raiz

Objeto amount (Origem)

Objeto recipientAmount (Destino)

Objeto sender

Objeto sender.address

Objeto recipient

Objeto recipient.address

recipient.paymentMethod — Cartão

recipient.paymentMethod — Conta Bancária

recipient.paymentMethod — PIX

recipient.paymentMethod — Carteira