Skip to main content
Tazapay’s Checkout On Behalf Of (OBO) capability allows platforms, marketplaces, and financial institutions to collect payments on behalf of their entities: sellers, businesses, or individuals registered under your merchant account. OBO is supported across both Tazapay payment acceptance products:
  • Checkout — a hosted payment link that produces a checkout object
  • Payin — whitelabelled payment methods embedded in your own UI that produce a payin object
In both cases, passing on_behalf_of ensures funds are correctly attributed and traceable to the intended recipient.

​
Use Cases

  • Marketplace Platform — A marketplace creates checkout sessions on behalf of individual sellers, ensuring payments are correctly attributed to each seller’s entity.
  • Payment Aggregator — A licensed payment aggregator processes payments on behalf of multiple merchants under a single parent account.
  • Bill Payment Platform — A bill payment aggregator collects payments on behalf of utility companies, telecom providers, or other service entities.
  • Digital Wallet Recharge — A financial institution allows users to recharge prepaid wallets or accounts belonging to third-party entities.

​
How It Works

  1. Create and submit an entity — Register the seller, business, or individual under your merchant account and submit them for review.
  2. Wait for approval — The entity must reach submitted status (or approved, if mandatory approval is enabled on your account) before it can be used in OBO sessions.
  3. Create a Checkout or Payin — Pass the approved entity ID in the on_behalf_of field.
  4. Customer completes payment — Tazapay creates a checkout or payin object attributed to the entity.
  5. Handle webhooks — Listen for checkout.paid or payin.succeeded to confirm payment.
  6. Manage settlements / Create Payouts — Settled funds are received in aggregate to your account. You can either receive them as a bulk settlement to your bank account, or use the balance to fund onward payouts via Tazapay. See Settlement for details.

​
Step 1: Create an Entity

An entity represents the business or individual on whose behalf you’re collecting payment — a seller, agent, or service provider registered under your platform’s merchant account. Tazapay supports two entity types:
  • Business Entity — for registered companies and legal entities
  • Individual Entity — for sellers, agents, freelancers, or sole proprietors
Before an entity can be used in an OBO session, it must be in approved status.
Think of entities as the sub-accounts sitting under your platform. Every payment you collect on their behalf is fully attributed and traceable back to them.
  1. Business Entity Requirements — Full Onboarding
  2. Individual Entity Requirements — Full Onboarding
  3. Entity Requirements — Simplified Onboarding
  4. Create Entity API
  5. Submit Entity API

​
Step 2: Create a Checkout or Payin

Once you have an approved entity, include its ID in the on_behalf_of field when creating a Checkout or Payin. This is the only step needed to attribute the payment to the correct entity.

​
Request

POST /v3/checkout
{
  "invoice_currency": "USD",
  "amount": 100000,
  "on_behalf_of": "ent_d3inm6ami8u10oqfm",
  "customer_details": {
    "name": "Andrea Lark",
    "country": "SG",
    "email": "andrea@example.com",
    "phone": {
      "calling_code": "65",
      "number": "87654321"
    }
  },
  "success_url": "https://mystore.com/success_page",
  "cancel_url": "https://mystore.com/try_again",
  "webhook_url": "https://mystore.com/internal/webhook",
  "transaction_description": "Payment to seller",
  "reference_id": "mystore_order_00001"
}

​
Key fields

FieldTypeRequiredDescription
on_behalf_ofstringOptional*ID of the entity on whose behalf the checkout is created. Must be an entity belonging to your merchant account. Format: ent_*
*Required if your account has the Mandatory OBO information for checkout configuration enabled.

​
Response

The response includes the hosted checkout url and echoes back on_behalf_of: 
{
  "id": "chk_cirsp2sl4ar024j0akj0",
  "object": "checkout",
  "on_behalf_of": "ent_d3inm6ami8u10oqfm",
  "url": "https://checkout.tazapay.com/transaction=...",
  "payment_status": "pending",
  "status": "active",
  ...
}

​
Step 3: Handle the Resulting Payin

When the customer completes payment on the hosted checkout page, Tazapay creates a linked Payin. The Payin automatically inherits the on_behalf_of value from the checkout session — no additional steps are required. You can retrieve the Payin using the payin field in the Checkout response or via the Get Checkout API.

​
Step 4: Handle Checkout & Payin Events / Webhooks

Tazapay sends webhooks for all checkout and payin status changes. When OBO is used, all webhook payloads include on_behalf_of in the data object.

​
Example: checkout.paid webhook (OBO)

{
  "type": "checkout.paid",
  "created_at": 958793503,
  "data": {
    "id": "chk_ahfafooi7ibakbfahoan",
    "object": "checkout",
    "payin": "pay_bfiuafuiafianifnao",
    "payment_status": "paid",
    "on_behalf_of": "ent_d3inm6ami8u10oqfm",
    ...
  },
  "id": "evt_auigfianfoangohuehg",
  "object": "event"
}

​
Best Practices

  • Always verify webhook signatures
  • Rely on webhooks (not polling) for final payment outcomes
  • Store the on_behalf_of value from webhook payloads for reconciliation
  1. Checkout Webhook Events
  2. Payin Webhook Events
  3. Checkout States
  4. Payin States

​
Account Configurations

Two merchant-level configurations control Checkout OBO behaviour. These are set by Tazapay on your account:
ConfigurationDescription
Mandatory OBO information for checkoutWhen enabled, all checkout creation requests must include on_behalf_of. Requests without it will be rejected with on_behalf_of_required.
Mandatory entity approval for checkoutWhen enabled, the entity specified in on_behalf_of must have approval_status: approved. Submitted but unapproved entities will be rejected with entity_not_approved.
Contact your Tazapay account manager to enable these configurations.

​
Error Reference

Error CodeHTTP StatusMessage
on_behalf_of_required400on_behalf_of field is required for this merchant account
entity_not_approved400The entity must be approved before creating a checkout on their behalf
entity_rejected400Checkout cannot be created for a rejected entity
entity_id_mismatch400The entity does not belong to the authenticated merchant account