Skip to main content

​
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 (cli_* tokens) of the platforms you serve with your orchestrator.
  • Configure fees — set orchestrator fees (and per-client-ID overrides) that apply to payments made under those client IDs.
  • Apply branding — give the hosted Secure Payment experience your own 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.
“Orchestrator” here is the formal fee/branding partner account described on this page. It builds on — but is broader than — the lightweight “orchestrator pattern” of binding a single Client ID to a payee destination described in Client ID Management.

​
Getting provisioned

Orchestrator accounts and their API keys are provisioned by Request Network — they are not self-service. Get in touch 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: 
curl -X GET "https://api.request.network/v2/orchestrators/client-ids" \
  -H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY"
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.

​
The orchestrator API surface

All partner-facing orchestrator endpoints live under /v2/orchestrators and are authenticated with the x-orchestrator-key header:
EndpointPurpose
GET /v2/orchestrators/client-idsList the client IDs linked to your orchestrator
POST /v2/orchestrators/client-idsLink an existing cli_* client ID
DELETE /v2/orchestrators/client-ids/:clientIdUnlink a client ID
POST /v2/orchestrators/client-id-link-intentsCreate an onboarding link intent
POST /v2/orchestrators/fee-configsCreate an orchestrator fee or per-client-ID override
GET /v2/orchestrators/fee-configsList your fee configs (optionally ?clientId)
PATCH /v2/orchestrators/fee-configs/:idUpdate a fee config
DELETE /v2/orchestrators/fee-configs/:idDisable a fee config
See Client ID linking and Orchestrator 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: 
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.

Orchestrator fees

Configure orchestrator fees and per-client-ID overrides.

Client ID linking

Link client IDs directly or via onboarding link intents.

Whitelabel branding

Theme the Secure Payment page with your branding.