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)
ACH — US domestic bank transfers
PIX — Brazilian instant payments
Wallets — Digital wallet payouts
Bank Accounts — Cross-border account payouts

Endpoint

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

Headers:

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

Request Structure

Root Object

Field	Type	Required	Description
`externalPaymentId`	string	✅	Your unique payment identifier
`ipAddress`	string	✅	Originator's IPv4 or IPv6 address
`paymentType`	string	✅	`"PUSH"`
`amount`	object	✅	Source amount (what you're sending)
`recipientAmount`	object	✅	Destination amount (what recipient receives)
`exchangeRate`	number	✅	FX rate applied between currencies
`sender`	object	✅	Sender details
`recipient`	object	✅	Recipient details and destination

`amount` Object (Source)

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

`recipientAmount` Object (Destination)

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

`sender` Object

Field	Type	Required	Description
`customer`	object	✅	Sender's personal information
`customerAddress`	object	✅	Sender's address

`sender.customer`

Field	Type	Required	Description
`firstName`	string	✅	Sender's first name
`lastName`	string	✅	Sender's last name
`phoneNumber`	string	✅	Phone (7–15 digits)
`documentNumber`	string	✅	ID document number (5–20 digits)
`documentType`	string	✅	`NATIONAL_ID`, `PASSPORT`, or `DRIVER_LICENSE`
`email`	string	✅	Email address
`countryCodeAlpha3`	string	✅	ISO Alpha-3 country code (e.g., `"USA"`)

`sender.customerAddress`

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

`recipient` Object

Field	Type	Required	Description
`customer`	object	✅	Recipient's personal information
`customerAddress`	object	✅	Recipient's address
`destination`	object	✅	Payout method and details

`recipient.customer`

Same fields as sender.customer.

`recipient.customerAddress`

Same fields as sender.customerAddress.

`recipient.destination` — Card

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

`recipient.destination` — PIX

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

`recipient.destination` — Wallet

Field	Type	Required	Description
`type`	string	✅	`"WALLET"`
`wallet.walletId`	string	✅	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",
    "ipAddress": "203.0.113.42",
    "paymentType": "PUSH",
    "amount": {
      "total": 250.00,
      "currency": "USD"
    },
    "recipientAmount": {
      "total": 250.00,
      "currency": "USD"
    },
    "sender": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "[email protected]",
      "address": {
        "countryCode": "USA",
        "stateCode": "CA",
        "city": "Mountain View",
        "line1": "1600 Amphitheatre Pkwy",
        "line2": "",
        "zipCode": "94043"
      }
    },
    "recipient": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "[email protected]",
      "dateOfBirth": "1990-05-15",
      "contactNumber": "12125551234",
      "address": {
        "countryCode": "USA",
        "stateCode": "NY",
        "city": "New York",
        "line1": "20 W 34th St",
        "line2": "",
        "zipCode": "10001"
      },
      "paymentMethod": {
        "type": "CARD",
        "cardTokenId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }'

Example — Push to PIX

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "push-001",
    "ipAddress": "203.0.113.42",
    "paymentType": "PUSH",
    "amount": {
      "total": 55.00,
      "currency": "USD"
    },
    "recipientAmount": {
      "total": 273.63,
      "currency": "BRL"
    },
    "exchangeRate": 4.975,
    "sender": {
      "customer": {
        "firstName": "John",
        "lastName": "Smith",
        "phoneNumber": "5551234567",
        "documentNumber": "050482156",
        "documentType": "NATIONAL_ID",
        "email": "[email protected]",
        "countryCodeAlpha3": "USA"
      },
      "customerAddress": {
        "stateCode": "CA",
        "city": "Los Angeles",
        "line1": "4429 Candlewood St",
        "zipCode": "90712",
        "countryCode": "US"
      }
    },
    "recipient": {
      "customer": {
        "firstName": "Carlos",
        "lastName": "Silva",
        "phoneNumber": "1122334455",
        "documentNumber": "12345678900",
        "documentType": "PASSPORT",
        "email": "[email protected]",
        "countryCodeAlpha3": "BRA"
      },
      "customerAddress": {
        "stateCode": "RJ",
        "city": "Rio de Janeiro",
        "line1": "Rua das Laranjeiras 321",
        "state": "Rio de Janeiro",
        "zipCode": "22240-005"
      },
      "destination": {
        "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-002",
    "ipAddress": "203.0.113.42",
    "paymentType": "PUSH",
    "amount": {
      "total": 100.00,
      "currency": "USD"
    },
    "recipientAmount": {
      "total": 497.50,
      "currency": "BRL"
    },
    "exchangeRate": 4.975,
    "sender": {
      "customer": {
        "firstName": "Jane",
        "lastName": "Doe",
        "phoneNumber": "5559876543",
        "documentNumber": "123456789",
        "documentType": "NATIONAL_ID",
        "email": "[email protected]",
        "countryCodeAlpha3": "USA"
      },
      "customerAddress": {
        "stateCode": "NY",
        "city": "New York",
        "line1": "456 Park Avenue",
        "zipCode": "10022",
        "countryCode": "US"
      }
    },
    "recipient": {
      "customer": {
        "firstName": "Ana",
        "lastName": "Souza",
        "phoneNumber": "21987654321",
        "documentNumber": "10987654321",
        "documentType": "PASSPORT",
        "email": "[email protected]",
        "countryCodeAlpha3": "BRA"
      },
      "customerAddress": {
        "stateCode": "RJ",
        "city": "Rio de Janeiro",
        "line1": "Rua da Alfândega 45",
        "state": "Rio de Janeiro",
        "zipCode": "20010-030"
      },
      "destination": {
        "type": "WALLET",
        "wallet": {
          "walletId": "[email protected]"
        }
      }
    }
  }'

Foreign Exchange

For cross-currency push payments, you can fetch real-time FX rates before submitting:

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

Response:

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

Use the conversionRate as the exchangeRate in your push payment, and optionally pass fxId to lock in the quoted rate.

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.customer

sender.customerAddress

recipient Object

recipient.customer

recipient.customerAddress

recipient.destination — Card

recipient.destination — PIX

recipient.destination — Wallet