GuidesAPI Reference
Guides
Guides
Guides

Payment On Behalf Of (POBO)

Payment On Behalf Of (POBO) lets one beneficiary — the sponsor — fund a payment that is executed through another beneficiary's account. This is useful when a single funding entity backs payments for many downstream accounts, such as corporate spend management, marketplace settlements, or paying vendors on a customer's behalf.

A POBO payment involves three parties:

  • Sponsor (payor): Your integrator's main beneficiary — the account that funds POBO payments. It is established when your integrator is onboarded, and there is one per integrator. You reference it with the payorId field on the simulation.
  • Beneficiary: The beneficiary the payment runs through, identified by beneficiaryId, exactly as in a standard payment.
  • Recipient: The external destination that receives the funds, identified by recipientId.

You turn any payment into a POBO payment by setting payorId to your main beneficiary on the simulation. When payorId is present and differs from the beneficiary the payment runs through, Caliza treats the payment as POBO and funds it from your main beneficiary — there is no separate endpoint.

How it works

Under the hood, Caliza processes a POBO payment in two legs:

  1. Internal transfer — Caliza moves the funds from the sponsor to the beneficiary.
  2. External payout — Caliza executes the payment from the beneficiary to the recipient, just like a standard payment.

You only make the API calls described below; both legs are handled automatically once you execute the payment.

📘

The external payout starts once the internal transfer between the sponsor and the beneficiary has settled. As a result, immediately after you execute a POBO payment its status may briefly reflect the internal transfer before the external payout begins. Track the payment status as you would for any payment (see Track the payment status).

Simulate a POBO payment

To simulate a POBO payment, send a standard simulation request and add the payorId field set to your main beneficiary's ID. Make sure to replace:

  • YOUR_TOKEN with your actual API token.
  • beneficiaryId with the ID of the beneficiary the payment runs through.
  • payorId with the ID of your main beneficiary (the sponsor funding the payment).

See an example request below:

curl -s --location --request POST 'https://api.sandbox.caliza.com/core-api/v2/simulations' \
--header "Authorization: Bearer YOUR_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "from": {
        "currencyCode": "USDC",
        "value": 500
    },
    "to": {
        "currencyCode": "USD"
    },
    "beneficiaryId": "69261109adcc7b2db705a123",
    "payorId": "69261109adcc7b2db705a999",
    "recipientId": "12ace467-8189-42ec-8b21-0a5bf7cd7f5e",
    "payout": "WIRE"
}'

Where:

  • from: An object containing details about the source of funds, including currency code and value.
  • to: An object containing details about the destination of funds, including currency code.
  • beneficiaryId: The ID of the beneficiary the payment runs through.
  • payorId: Your integrator's main beneficiary ID — the sponsor account that funds the payment. Setting this field to a value that differs from beneficiaryId is what makes the payment a POBO payment.
  • recipientId: The ID of the recipient where the funds will be sent.
  • payout: The payout rail used for the transaction (e.g., "WIRE").

Execute the POBO payment

Once you have a POBO simulation, execute it exactly as you would a standard payment — pass the simulationId to POST /v1/payments. The payorId carried by the simulation is applied automatically, so the execution request is unchanged.

Make sure to replace YOUR_TOKEN with your actual API token and simulationId with the ID of the POBO simulation you want to execute:

curl 'https://api.sandbox.caliza.com/core-api/v1/payments' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"simulationId": "{{simulationId}}",
"beneficiaryIp": "{{beneficiaryIp}}"
}'

Where:

  • simulationId: The ID of the POBO simulation you want to execute.
  • beneficiaryIp: The IP address of the beneficiary initiating the payment.
📘

POBO payments support the same supporting-document workflow as standard payments. You can attach documents at execution time with POST /v1/payments/:withDocuments. See Payments for details.

Track the payment status

Check the status of a POBO payment the same way you check any payment, using its ID.

See the example request below:

curl --location --globoff 'https://api.sandbox.caliza.com/core-api/v1/payments/{{payment_id}}' \
--header 'Authorization: Bearer YOUR_TOKEN'

Where payment_id is the ID of the payment you want to check.

📘

Because a POBO payment is processed as an internal transfer followed by an external payout, the payment reaches a completed state only after the external payout settles. If you poll or receive webhooks shortly after execution, allow for the brief internal-transfer step before the external payout begins.

Webhook events for POBO payments

POBO payments emit the same webhook events as standard payments — most notably TRANSACTION_COMPLETED when the payment finishes. See Webhook events for payments for the event structure and field descriptions.

Related Articles

Payments

The standard payment flow.

Internal Transfers

Move funds between beneficiaries.

Beneficiaries

Manage your beneficiaries.

Updated about 1 month ago

Did this page help you?