---
description: >-
  Push transactions send funds from your account to a recipient's card, bank
  account, PIX key, or wallet — domestically or internationally.
---

# 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://sandbox-gw.simpleps.com/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` — 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 PIX

```bash
curl -X POST https://sandbox-gw.simpleps.com/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

```bash
curl -X POST https://sandbox-gw.simpleps.com/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, you can fetch real-time FX rates before submitting:

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

**Response:**

```json
{
  "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.