Skip to main content
A beneficiary is a recipient you save for one corridor (country_code + currency_code). Instead of sending the full recipient details on every payout, you create the beneficiary once and then reference its beneficiary_id.
Beneficiaries belong to payouts. Every endpoint here requires the same JWT from /api/v1/user/login that sendPayoutRequest does, and an account without the payout product cannot reach them. This is the opposite of payins, which take no JWT at all.

​
Why use them

  • Validate early. Per-country requirements (account formats, KYC fields) are checked when you create the beneficiary, not at payout time.
  • Smaller payout calls. A payout in beneficiary mode only carries the amount.
  • Stable contract. The fields a corridor requires are defined by PontisGlobe and don’t change if we route through a different underlying provider.

​
Lifecycle

  1. Create — addBeneficiary with the corridor + per-country recipient_details. We validate the fields and return a beneficiary_id.
  2. Use — pass that beneficiary_id to sendPayoutRequest in beneficiary mode.
  3. Manage — fetch, list, update or archive them.
A payout always snapshots the recipient details at the moment it is created, so editing or archiving a beneficiary never affects payouts already in flight.

​
Corridor requirements

Every corridor requires recipient_details.name. The remaining fields fall into a few groups depending on the destination:
Field-level tables (types, formats, exact required flags) are returned by the validation errors on addBeneficiary and shown in the dashboard’s add-beneficiary form. Corridors marked “Mobile money” require a payment_network (e.g. VODACOM, MTN, AIRTEL).

​
Security

  • Beneficiaries are scoped to your account. A beneficiary_id from one account is never usable by another; lookups for an id you don’t own return 404.
  • Read responses mask sensitive values (e.g. last 4 of an account number).
  • Sandbox and live beneficiaries are isolated — a sandbox beneficiary cannot be used for a live payout.