Push Transaction

Las transacciones push (payout) transfieren fondos a un destinatario. El Inyo Gateway soporta múltiples métodos de destino:

Tarjetas — Visa Direct / Mastercard Send (nacional y transfronterizo)
Cuentas Bancarias — Payouts transfronterizos a cuentas
PIX — Pagos instantáneos brasileños
Billeteras — Payouts a billeteras digitales

Endpoint

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

Encabezados:

Encabezado	Valor
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Estructura de la Solicitud

Los objetos sender y recipient usan la misma estructura plana que una transacción pull — firstName, lastName y address. El recipient lleva adicionalmente un paymentMethod que describe el destino del payout.

Objeto Raíz

Campo	Tipo	Requerido	Descripción
`externalPaymentId`	string	Sí	Tu identificador único del pago (clave de idempotencia)
`fxId`	string	Sí	Identificador de la cotización FX del endpoint Foreign Exchange
`ipAddress`	string	Sí	Dirección IPv4 o IPv6 del originador
`paymentType`	string	Sí	`"PUSH"`
`amount`	object	Sí	Monto de origen (lo que envías)
`recipientAmount`	object	Sí	Monto de destino (lo que recibe el destinatario)
`sender`	object	Sí	Datos y dirección del remitente
`recipient`	object	Sí	Datos, dirección y método de payout del destinatario
`capture`	boolean	No	Solo tarjetas — `false` para preautorización, `true` para capturar inmediatamente
`additionalData`	object	No	Metadatos opcionales clave/valor adjuntos al pago

Objeto `amount` (Origen)

Campo	Tipo	Requerido	Descripción
`total`	number	Sí	Monto a enviar (debe ser ≥ 1)
`currency`	string	Sí	Divisa de origen (ISO 4217, p. ej., `"USD"`)

Objeto `recipientAmount` (Destino)

Campo	Tipo	Requerido	Descripción
`total`	number	Sí	Monto que recibe el destinatario
`currency`	string	Sí	Divisa de destino (ISO 4217, p. ej., `"BDT"`)

Objeto `sender`

Campo	Tipo	Requerido	Descripción
`firstName`	string	Sí	Primer nombre del remitente
`lastName`	string	Sí	Apellido del remitente
`address`	object	Sí	Dirección del remitente

Objeto `sender.address`

Campo	Tipo	Requerido	Descripción
`countryCode`	string	Sí	Código de país ISO Alpha-3 (p. ej., `"USA"`)
`stateCode`	string	Sí	Abreviatura de estado (p. ej., `"MA"`)
`city`	string	Sí	Nombre de la ciudad
`line1`	string	Sí	Línea 1 de la dirección
`line2`	string	No	Línea 2 de la dirección
`zipCode`	string	Sí	Código postal/ZIP

Objeto `recipient`

Campo	Tipo	Requerido	Descripción
`firstName`	string	Sí	Primer nombre del destinatario
`lastName`	string	Sí	Apellido del destinatario
`address`	object	Sí	Dirección del destinatario
`paymentMethod`	object	Sí	Método y detalles del payout

Objeto `recipient.address`

Los mismos campos que sender.address.

Los campos de identidad y dirección del destinatario varían según el país de destino. Qué campos son requeridos y sus reglas de validación no son fijos — cambian por corredor. Por ejemplo, Filipinas requiere un stateCode de un enum fijo de códigos de provincia, Brasil requiere un CPF vía un array documents (11 dígitos, validado con dígito verificador), y la mayoría de los corredores de la UE hacen la dirección opcional. Consulta siempre el Person Schema (GET /schema/person?countryCode=<ISO3>) del país de destino y construye el recipient a partir del esquema devuelto en lugar de codificar los campos anteriores de forma fija.

`recipient.paymentMethod` — Tarjeta

Campo	Tipo	Requerido	Descripción
`type`	string	Sí	`"CARD"`
`cardTokenId`	string	Sí	Identificador de la tarjeta tokenizada

`recipient.paymentMethod` — Cuenta Bancaria

Campo	Tipo	Requerido	Descripción
`type`	string	Sí	`"BANK_DEPOSIT"`
`countryCode`	string	Sí	Código de país ISO Alpha-3 del banco de destino (p. ej., `"BGD"`)
`bankCode`	string	Sí	Código del banco/sucursal de destino
`accountNumber`	string	Sí	Número de cuenta bancaria del destinatario
`walletType`	string	No	Tipo de identificador de cuenta (p. ej., `"PHONENUMBER"`)

Los campos de cuenta bancaria varían según el país de destino. El conjunto de campos, cuáles son requeridos y sus reglas de validación no son fijos — cambian por corredor. Por ejemplo, Brasil requiere un código de sucursal (routingNumber / agência) y un documento CPF, mientras que México omite routingNumber por completo porque la CLABE (accountNumber) ya codifica el banco. Consulta siempre el Account Schema (GET /schema/account?countryCode=<ISO3>) del país de destino y construye paymentMethod a partir del esquema devuelto en lugar de codificar los campos anteriores de forma fija. La tabla anterior es un ejemplo concreto (Bangladesh), no la forma canónica para todos los países.

`recipient.paymentMethod` — PIX

Campo	Tipo	Requerido	Descripción
`type`	string	Sí	`"PIX"`
`pix.keyType`	string	Sí	`"EMAIL"`, `"PHONE"`, `"DOCUMENT"` (CPF/CNPJ), o `"EVP"` (llave aleatoria)
`pix.key`	string	Sí	El valor de la llave PIX

`recipient.paymentMethod` — Billetera

Campo	Tipo	Requerido	Descripción
`type`	string	Sí	`"WALLET"`
`wallet.walletId`	string	Sí	Identificador de la billetera (email o ID)

Ejemplo — Push a Tarjeta

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

Ejemplo — Push a Cuenta Bancaria

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

Ejemplo — Push a 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"
        }
      }
    }
  }'

Ejemplo — Push a Billetera

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 pagos push entre divisas, obtén una tasa FX antes de enviar. Pasa el fxId devuelto en tu solicitud de pago — el gateway aplica la tasa cotizada asociada a ese fxId.

Consulta la documentación completa de Foreign Exchange para los esquemas detallados de solicitud/respuesta, incluido el endpoint v2 con tasas específicas por método de pago.

Ejemplo 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: Las cotizaciones FX tienen un período de validez limitado. Verifica quoteIdExpiryDateTime y renuévala si expiró.

Push Transaction

Endpoint

Estructura de la Solicitud

Objeto Raíz

Objeto amount (Origen)

Objeto recipientAmount (Destino)

Objeto sender

Objeto sender.address

Objeto recipient

Objeto recipient.address

recipient.paymentMethod — Tarjeta

recipient.paymentMethod — Cuenta Bancaria

recipient.paymentMethod — PIX

recipient.paymentMethod — Billetera