Pull y Push en un Solo Paso

El tipo de pago PULLPUSH combina la recaudación y el desembolso de fondos en una sola llamada a la API. Los fondos se extraen (pull) de la tarjeta o cuenta bancaria del remitente y simultáneamente se envían (push) al destino del destinatario.

Esto reduce la latencia y simplifica los flujos de trabajo donde los fondos deben moverse entre dos partes en una sola transacción.

Endpoint

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

Encabezados:

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

Estructura de la Solicitud

Objeto Raíz

Campo	Tipo	Requerido	Descripción
`externalPaymentId`	string	Sí	Su identificador único del pago
`ipAddress`	string	Sí	Dirección IPv4 o IPv6 del originador
`paymentType`	string	Sí	`"PULLPUSH"`
`amount`	object	Sí	Monto del pull (lado del remitente, en USD)
`recipientAmount`	object	Sí	Monto del push (lado del destinatario, cualquier moneda)
`exchangeRate`	number	Sí	Tasa de cambio (FX) entre la moneda de origen y la de destino
`sender`	object	Sí	Datos del remitente y fuente del pago
`recipient`	object	Sí	Datos del destinatario y destino del payout

Sender

La estructura del remitente es idéntica a la de un pago Pull — incluye customer, customerAddress y source:

`sender.source` — Tarjeta

Campo	Tipo	Requerido	Descripción
`type`	string	Sí	`"CARD"`
`card.token`	string	Sí	UUID del token de tarjeta obtenido del tokenizador

`sender.source` — Cuenta Bancaria

Campo	Tipo	Requerido	Descripción
`type`	string	Sí	`"BANK_ACCOUNT"`
`accountType`	string	Sí	`"savings"`, `"checking"`, etc.
`accountNumber`	string	Sí	Número de cuenta bancaria
`routingNumber`	string	Sí	Número de ruta ABA
`accountHolder`	object	Sí	`{ type, firstName, lastName }`

Recipient

La estructura del destinatario es idéntica a la de un pago Push — incluye customer, customerAddress y destination.

Ejemplo — PULLPUSH (Tarjeta → Wallet)

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "pullpush-001",
    "ipAddress": "203.0.113.42",
    "paymentType": "PULLPUSH",
    "amount": {
      "total": 100.00,
      "currency": "USD"
    },
    "recipientAmount": {
      "total": 497.50,
      "currency": "BRL"
    },
    "exchangeRate": 4.975,
    "sender": {
      "customer": {
        "firstName": "Lucas",
        "lastName": "Silva",
        "phoneNumber": "11999999999",
        "documentNumber": "12345678900",
        "documentType": "NATIONAL_ID",
        "email": "[email protected]",
        "countryCodeAlpha3": "USA"
      },
      "customerAddress": {
        "stateCode": "CA",
        "city": "San Francisco",
        "line1": "123 Mission St",
        "line2": "Suite 900",
        "state": "California",
        "zipCode": "94105"
      },
      "source": {
        "type": "CARD",
        "card": {
          "token": "ab5fc589-8b48-4531-94c0-68b0629c13fe"
        }
      }
    },
    "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]"
        }
      }
    }
  }'

Ejemplo — PULLPUSH (Cuenta Bancaria → PIX)

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "pullpush-002",
    "ipAddress": "203.0.113.42",
    "paymentType": "PULLPUSH",
    "amount": {
      "total": 200.00,
      "currency": "USD"
    },
    "recipientAmount": {
      "total": 995.00,
      "currency": "BRL"
    },
    "exchangeRate": 4.975,
    "sender": {
      "customer": {
        "firstName": "Maria",
        "lastName": "Johnson",
        "phoneNumber": "5551234567",
        "documentNumber": "987654321",
        "documentType": "DRIVER_LICENSE",
        "email": "[email protected]",
        "countryCodeAlpha3": "USA"
      },
      "customerAddress": {
        "stateCode": "TX",
        "city": "Austin",
        "line1": "789 Congress Ave",
        "state": "Texas",
        "zipCode": "78701"
      },
      "source": {
        "type": "BANK_ACCOUNT",
        "accountType": "checking",
        "accountNumber": "123456789",
        "routingNumber": "021000021",
        "accountHolder": {
          "type": "personal",
          "firstName": "Maria",
          "lastName": "Johnson"
        }
      }
    },
    "recipient": {
      "customer": {
        "firstName": "Pedro",
        "lastName": "Santos",
        "phoneNumber": "11987654321",
        "documentNumber": "98765432100",
        "documentType": "NATIONAL_ID",
        "email": "[email protected]",
        "countryCodeAlpha3": "BRA"
      },
      "customerAddress": {
        "stateCode": "SP",
        "city": "São Paulo",
        "line1": "Av Paulista 1000",
        "state": "São Paulo",
        "zipCode": "01311-100"
      },
      "destination": {
        "type": "PIX",
        "pix": {
          "keyType": "EMAIL",
          "key": "[email protected]"
        }
      }
    }
  }'

Diferencias Clave frente a Pull + Push por Separado

Aspecto	Llamadas separadas	PULLPUSH
Llamadas a la API	2 (un pull, un push)	1
Atomicidad	Independientes — el push puede fallar después de que el pull tenga éxito	Transacción única
Tasa de cambio (FX)	Debe gestionarse de forma independiente	Se especifica en la misma solicitud
Caso de uso	Flujos complejos con lógica intermedia	Remesa directa de extremo a extremo