> ## Documentation Index
> Fetch the complete documentation index at: https://requestnetwork-fix-req-350-remove-unused-webhook-events.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestrators overview

> Orchestrators are fee and branding partners in Request Network: link client IDs, configure fees, and apply whitelabel branding across your platform.

## What is an orchestrator?

An **orchestrator** is a fee and branding partner in Request Network. It is a first-class account that can:

* **Link client IDs** — associate the developer [Client IDs](/api-features/client-id-management) (`cli_*` tokens) of the platforms you serve with your orchestrator.
* **Create payment links** — use your key with a linked client ID to create incoming payment links and outgoing payout links for a platform.
* **Receive webhooks** — receive signed `client_id.linked` notifications after a platform completes hosted onboarding and `kyt.screening.completed` notifications after a definitive screening result.
* **Configure fees** — set [orchestrator fees](/orchestrators/fees) (and per-client-ID overrides) that apply to payments made under those client IDs.
* **Apply branding** — give the hosted [Secure Payment](/tools/secure-payments) experience your own [whitelabel branding](/orchestrators/whitelabel-branding).

This is aimed at platforms, PSPs, and partners who orchestrate payments on behalf of multiple downstream merchants and want consistent fees and branding across them.

<Note>
  "Orchestrator" here is the formal fee/branding partner account described on this page. It is different from using a Client ID with a payment destination, described in [Client ID Management](/api-features/client-id-management#using-a-client-id-with-a-payment-destination).
</Note>

## Roles in an orchestrated flow

* **Platform** — a merchant, business, or service whose `cli_*` client ID is linked to an orchestrator. It is the payee for incoming payments and the payer for outgoing payouts.
* **Orchestrator** — a partner that manages Request Network payment flows for a platform.
* **End user** — a customer of the platform: payer of an incoming payment and payee of an outgoing payout.

## Getting provisioned

Orchestrator accounts and their API keys are provisioned by Request Network — they are not self-service. [Get in touch](https://request.network) to have an orchestrator created for you.

Once provisioned, you authenticate to the orchestrator endpoints with a secret key sent in the `x-orchestrator-key` header:

```bash theme={null}
curl -X GET "https://api.request.network/v2/orchestrators/client-ids" \
  -H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY"
```

<Warning>
  Your orchestrator key (prefixed `orc_`) is a server-side secret. The full key value is shown only once, at creation time. Store it in a secret manager, never expose it in client-side code, and contact Request Network to rotate it if it is compromised.
</Warning>

## The orchestrator API surface

All partner-facing orchestrator endpoints live under `/v2/orchestrators` and are authenticated with the `x-orchestrator-key` header:

| Endpoint                                        | Purpose                                              |
| ----------------------------------------------- | ---------------------------------------------------- |
| `GET /v2/orchestrators/client-ids`              | List the client IDs linked to your orchestrator      |
| `POST /v2/orchestrators/client-ids`             | Link an existing `cli_*` client ID                   |
| `DELETE /v2/orchestrators/client-ids/:clientId` | Unlink a client ID                                   |
| `POST /v2/orchestrators/client-id-link-intents` | Create an onboarding link intent                     |
| `POST /v2/orchestrators/branding`               | Create default or per-client-ID branding             |
| `GET /v2/orchestrators/branding`                | Get effective branding                               |
| `PATCH /v2/orchestrators/branding`              | Update branding                                      |
| `DELETE /v2/orchestrators/branding`             | Remove branding                                      |
| `POST /v2/orchestrators/webhooks`               | Register a webhook endpoint                          |
| `GET /v2/orchestrators/webhooks`                | List registered webhook endpoints                    |
| `PATCH /v2/orchestrators/webhooks/:id`          | Reactivate a webhook endpoint                        |
| `DELETE /v2/orchestrators/webhooks/:id`         | Deactivate a webhook endpoint                        |
| `POST /v2/orchestrators/webhooks/test`          | Send a test event to active webhook endpoints        |
| `POST /v2/orchestrators/fee-configs`            | Create an orchestrator fee or per-client-ID override |
| `GET /v2/orchestrators/fee-configs`             | List your fee configs (optionally `?clientId`)       |
| `PATCH /v2/orchestrators/fee-configs/:id`       | Update a fee config                                  |
| `DELETE /v2/orchestrators/fee-configs/:id`      | Disable a fee config                                 |

See [Client ID linking](/orchestrators/client-id-linking), [Whitelabel branding](/orchestrators/whitelabel-branding), [Orchestrator webhooks](/orchestrators/webhooks), and [Orchestrator fees](/orchestrators/fees) for details.

## How orchestrators apply at payment time

**Fees** are applied only when the secure payment is created with **paired authentication** — both your `x-orchestrator-key` and the platform's `x-client-id` headers. A client-ID-only call cannot carry an orchestrator key (it is rejected), so it receives no orchestrator fee. The orchestrator's active fee configuration is resolved and baked into the payment at creation time:

```bash theme={null}
curl -X POST "https://api.request.network/v2/secure-payments" \
  -H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY" \
  -H "x-client-id: cli_PLATFORM_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "requests": [ { "destinationId": "...", "amount": "100" } ] }'
```

**Branding** is resolved from the active client-ID → orchestrator link when the hosted Secure Payment page loads, so your branding applies to a linked client ID's payments even without paired authentication.

## Related

<CardGroup cols={2}>
  <Card title="Orchestrator fees" href="/orchestrators/fees" icon="percent">
    Configure orchestrator fees and per-client-ID overrides.
  </Card>

  <Card title="Client ID linking" href="/orchestrators/client-id-linking" icon="link">
    Link client IDs directly or via onboarding link intents.
  </Card>

  <Card title="Orchestrator webhooks" href="/orchestrators/webhooks" icon="webhook">
    Receive signed onboarding and KYT screening notifications.
  </Card>

  <Card title="Whitelabel branding" href="/orchestrators/whitelabel-branding" icon="palette">
    Theme the Secure Payment page with your branding.
  </Card>
</CardGroup>