Pull and Push in One Step

The PULLPUSH payment type combines fund collection and disbursement into a single API call. Funds are pulled from the sender's card or bank account and simultaneously pushed to the recipient's destination.

This reduces latency and simplifies workflows where funds need to move between two parties in a single transaction.

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	✅	`"PULLPUSH"`
`amount`	object	✅	Pull amount (sender side, in USD)
`recipientAmount`	object	✅	Push amount (recipient side, any currency)
`exchangeRate`	number	✅	FX rate between source and destination currencies
`sender`	object	✅	Sender details and payment source
`recipient`	object	✅	Recipient details and payout destination

Sender

The sender structure is identical to a Pull payment — includes customer, customerAddress, and source:

`sender.source` — Card

Field	Type	Required	Description
`type`	string	✅	`"CARD"`
`card.token`	string	✅	Card token UUID from tokenizer

`sender.source` — Bank Account

Field	Type	Required	Description
`type`	string	✅	`"BANK_ACCOUNT"`
`accountType`	string	✅	`"savings"`, `"checking"`, etc.
`accountNumber`	string	✅	Bank account number
`routingNumber`	string	✅	ABA routing number
`accountHolder`	object	✅	`{ type, firstName, lastName }`

Recipient

The recipient structure is identical to a Push payment — includes customer, customerAddress, and destination.

Example — PULLPUSH (Card → 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]"
        }
      }
    }
  }'

Example — PULLPUSH (Bank Account → 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]"
        }
      }
    }
  }'

Key Differences from Separate Pull + Push

Aspect	Separate calls	PULLPUSH
API calls	2 (one pull, one push)	1
Atomicity	Independent — push can fail after pull succeeds	Single transaction
FX rate	Must manage independently	Specified in same request
Use case	Complex flows with intermediate logic	Straight-through remittance