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": "jane.doe@example.com",
      "address": {
        "countryCode": "USA",
        "stateCode": "CA",
        "city": "Mountain View",
        "line1": "1600 Amphitheatre Pkwy",
        "line2": "",
        "zipCode": "94043"
      }
    },
    "recipient": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "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": "john.smith@example.com",
        "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": "carlos.silva@example.com",
        "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": "jane.doe@example.com",
        "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": "ana.souza@example.com",
        "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": "ana.souza@wallet.com"
        }
      }
    }
  }'

Foreign Exchange

For cross-currency push payments, fetch an FX rate before submitting. Pass the returned fxId and conversionRate as the fxId and exchangeRate in your payment request.

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

sender.customerAddress

recipient Object

recipient.customer

recipient.customerAddress

recipient.destination — Card

recipient.destination — PIX

recipient.destination — Wallet