Checkout on behalf of

Learn how platform merchants can create checkout sessions on behalf of their sub-entities using Checkout OBO.

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.

Relevant Links

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": "[e-mail]",
    "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

Field	Type	Required	Description
on_behalf_of	string	Optional*	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",
  ...
}

Relevant Links

• Create Checkout API
• Checkout Object Reference

---

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

Relevant Links

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:

Configuration	Description
Mandatory OBO information for checkout	When 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 checkout	When 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 Code	HTTP Status	Message
on_behalf_of_required	400	on_behalf_of field is required for this merchant account
entity_not_approved	400	The entity must be approved before creating a checkout on their behalf
entity_rejected	400	Checkout cannot be created for a rejected entity
entity_id_mismatch	400	The entity does not belong to the authenticated merchant account