Las transacciones pull (cobro) retiran fondos del método de pago de un cliente. El Inyo Gateway admite:
- Tarjetas de Crédito/Débito — Mediante datos de tarjeta tokenizados (vea Tokenización de Tarjetas)
- Transferencias Bancarias ACH — Mediante número de cuenta bancaria y número de ruta
Todas las transacciones pull usan el mismo endpoint:
POST https://{FQDN}/v2/payment
Estructura de la Solicitud
Objeto Raíz
| Campo | Tipo | Requerido | Descripción |
|---|
externalPaymentId | string | Sí | Su identificador único del pago (clave de idempotencia) |
ipAddress | string | Sí | Dirección IPv4 o IPv6 del pagador |
paymentType | string | Sí | "PULL" |
capture | boolean | Sí | true = captura automática; false = solo preautorización (solo tarjetas) |
amount | object | Sí | Monto de la transacción |
sender | object | Sí | Información del pagador, dirección y método de pago |
Objeto amount
| Campo | Tipo | Requerido | Descripción |
|---|
total | number | Sí | Monto del pago (debe ser ≥ 1) |
currency | string | Sí | Código de moneda ISO 4217 (p. ej., "USD") |
Objeto sender
| Campo | Tipo | Requerido | Descripción |
|---|
firstName | string | Sí | Nombre del pagador |
lastName | string | Sí | Apellido del pagador |
address | object | Sí | Dirección de facturación |
paymentMethod | object | Sí | Detalles de la tarjeta o cuenta bancaria |
Objeto sender.address
| Campo | Tipo | Requerido | Descripción |
|---|
countryCode | string | Sí | Código de país ISO Alpha-2 (p. ej., "US") |
stateCode | string | Sí | Abreviatura del estado (p. ej., "NY") |
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 |
sender.paymentMethod — Tarjeta
| Campo | Tipo | Requerido | Descripción |
|---|
type | string | Sí | "CARD" |
cardTokenId | string | Sí | UUID del token del tokenizador |
previousPaymentId | string | No | Para tokens recurrentes: paymentId de la autorización inicial |
sender.paymentMethod — Cuenta Bancaria (ACH)
| Campo | Tipo | Requerido | Descripción |
|---|
type | string | Sí | "BANK_DEPOSIT" |
accountNumber | string | Sí | Número de cuenta bancaria (6–20 dígitos) |
routingNumber | string | Sí | Número de ruta ABA (9 dígitos) |
accountType | string | Sí | "CHECKING", "SAVINGS", "BUSINESS_CHECKING" o "BUSINESS_SAVINGS" |
Ciclo de Vida del Pago con Tarjeta
Tokenize → Authorize → (3DS Challenge?) → Capture → (Refund?)
↘ Void
Para pagos con tarjeta:
- Autorizar — Cree el pago (
"capture": false para preautorización) - Manejar 3DS — Si
status = CHALLENGE, redirija a redirectAcsUrl - Capturar — Liquide el pago autorizado (dentro de 7 días)
- Anular (void) — Cancele antes de la captura
- Reembolsar — Devuelva los fondos después de la captura (total o parcial)
Pagos ACH
Los pagos ACH siempre se capturan de inmediato ("capture": true). El ciclo de vida de preautorización/captura no aplica.
Vea ACH (Cuenta Bancaria) para un ejemplo completo.
Qué Sigue
