Push Transaction

Push (payout) transactions transfer funds to a recipient. The Inyo Gateway supports multiple destination methods:

Cards — Visa Direct / Mastercard Send (domestic and cross-border)
Bank Accounts — Cross-border account payouts
PIX — Brazilian instant payments
Wallets — Digital wallet payouts

Endpoint

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

Headers:

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

Request Structure

The sender and recipient objects use the same flat structure as a pull transaction — firstName, lastName, and address. The recipient additionally carries a paymentMethod describing the payout destination.

Root Object

Field	Type	Required	Description
`externalPaymentId`	string	Yes	Your unique payment identifier (idempotency key)
`fxId`	string	Yes	FX quote identifier from the Foreign Exchange endpoint
`ipAddress`	string	Yes	Originator's IPv4 or IPv6 address
`paymentType`	string	Yes	`"PUSH"`
`amount`	object	Yes	Source amount (what you're sending)
`recipientAmount`	object	Yes	Destination amount (what recipient receives)
`sender`	object	Yes	Sender details and address
`recipient`	object	Yes	Recipient details, address, and payout method
`capture`	boolean	No	Cards only — `false` for pre-auth, `true` to capture immediately
`additionalData`	object	No	Optional key/value metadata attached to the payment

`amount` Object (Source)

Field	Type	Required	Description
`total`	number	Yes	Amount to send (must be ≥ 1)
`currency`	string	Yes	Source currency (ISO 4217, e.g., `"USD"`)

`recipientAmount` Object (Destination)

Field	Type	Required	Description
`total`	number	Yes	Amount recipient receives
`currency`	string	Yes	Destination currency (ISO 4217, e.g., `"BDT"`)

`sender` Object

Field	Type	Required	Description
`firstName`	string	Yes	Sender's first name
`lastName`	string	Yes	Sender's last name
`address`	object	Yes	Sender's address

`sender.address` Object

Field	Type	Required	Description
`countryCode`	string	Yes	ISO Alpha-3 country code (e.g., `"USA"`)
`stateCode`	string	Yes	State abbreviation (e.g., `"MA"`)
`city`	string	Yes	City name
`line1`	string	Yes	Street address line 1
`line2`	string	No	Street address line 2
`zipCode`	string	Yes	Postal/ZIP code

`recipient` Object

Field	Type	Required	Description
`firstName`	string	Yes	Recipient's first name
`lastName`	string	Yes	Recipient's last name
`address`	object	Yes	Recipient's address
`paymentMethod`	object	Yes	Payout method and details

`recipient.address` Object

Same fields as sender.address.

The recipient identity and address fields vary by destination country. Which fields are required and their validation rules are not fixed — they change per corridor. For example, the Philippines requires a stateCode from a fixed enum of province codes, Brazil requires a CPF via a documents array (11 digits, check-digit validated), and most EU corridors make the address optional. Always query the Person Schema (GET /schema/person?countryCode=<ISO3>) for the destination country and build the recipient from the returned schema rather than hardcoding the fields above.

`recipient.paymentMethod` — Card

Field	Type	Required	Description
`type`	string	Yes	`"CARD"`
`cardTokenId`	string	Yes	Tokenized card identifier

`recipient.paymentMethod` — Bank Account

Field	Type	Required	Description
`type`	string	Yes	`"BANK_DEPOSIT"`
`countryCode`	string	Yes	ISO Alpha-3 country code of the destination bank (e.g., `"BGD"`)
`bankCode`	string	Yes	Destination bank/branch code
`accountNumber`	string	Yes	Recipient's bank account number
`walletType`	string	No	Account identifier type (e.g., `"PHONENUMBER"`)

The bank-account fields vary by destination country. The set of fields, which are required, and their validation rules are not fixed — they change per corridor. For example, Brazil requires a branch code (routingNumber / agência) and a CPF document, while Mexico omits routingNumber entirely because the CLABE (accountNumber) already encodes the bank. Always query the Account Schema (GET /schema/account?countryCode=<ISO3>) for the destination country and build paymentMethod from the returned schema rather than hardcoding the fields above. The table above is one concrete example (Bangladesh), not the canonical shape for every country.

`recipient.paymentMethod` — PIX

Field	Type	Required	Description
`type`	string	Yes	`"PIX"`
`pix.keyType`	string	Yes	`"EMAIL"`, `"PHONE"`, `"DOCUMENT"` (CPF/CNPJ), or `"EVP"` (random key)
`pix.key`	string	Yes	The PIX key value

`recipient.paymentMethod` — Wallet

Field	Type	Required	Description
`type`	string	Yes	`"WALLET"`
`wallet.walletId`	string	Yes	Wallet identifier (email or ID)

Example — Push to Card

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"
      }
    }
  }'

Example — Push to Bank Account

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": {}
  }'

Example — Push to 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"
        }
      }
    }
  }'

Example — Push to Wallet

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

For cross-currency push payments, fetch an FX rate before submitting. Pass the returned fxId in your payment request — the gateway applies the quoted rate associated with that fxId.

See the full Foreign Exchange documentation for detailed request/response schemas, including the v2 endpoint with payment-method-specific rates.

Quick example (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"
}

Note: FX quotes have a limited validity period. Check quoteIdExpiryDateTime and refresh if expired.

Push Transaction

Endpoint

Request Structure

Root Object

amount Object (Source)

recipientAmount Object (Destination)

sender Object

sender.address Object

recipient Object

recipient.address Object

recipient.paymentMethod — Card

recipient.paymentMethod — Bank Account

recipient.paymentMethod — PIX

recipient.paymentMethod — Wallet