> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tazapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tip>
  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.
</Tip>

### Relevant Links

1. [Business Entity Requirements — Full Onboarding](/getting-started/overview/onboarding-requirements)
2. [Individual Entity Requirements — Full Onboarding](/getting-started/overview/onboarding-requirements)
3. [Entity Requirements — Simplified Onboarding](/Global-Money-Movement/connected-accounts/simplified-entity-creation)
4. [Create Entity API](/api-reference/tazapay-api/create-entity)
5. [Submit Entity API](/api-reference/tazapay-api/submit-entity-business)

***

## 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

```json theme={null}
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

| 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`:

```json theme={null}
{
  "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](/api-reference/tazapay-api/create-checkout)
* [Checkout Object Reference](/api-reference/tazapay-api/checkout)

***

## 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](/api-reference/tazapay-api/get-checkout-session).

***

## 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)

```json theme={null}
{
  "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](/api-reference/tazapay-api/checkout-webhooks)
2. [Payin Webhook Events](/api-reference/tazapay-api/payin-webhook)
3. [Checkout States](/api-reference/tazapay-api/checkout)
4. [Payin States](/api-reference/tazapay-api/payin)

***

## 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       |