Orchestr Merchant API
The Orchestr Merchant API lets you accept payments through hosted checkout sessions and reconcile the resulting orders and transactions — across every payment provider Orchestr orchestrates on your behalf, behind a single, stable interface.
This reference covers the public, server-to-server Merchant API. It is organised as:
- Getting started — make your first signed call.
- Direct payments — create a payment in a single merchant-initiated call.
- Authentication — how API keys identify your account.
- Signing — how every request, response, and webhook is signed with HMAC-SHA256.
- Errors — the error envelope and the full error-code catalogue.
- Webhooks — asynchronous payment and checkout events.
- Credential rotation — rotate keys and signing secrets with zero downtime.
- API Reference — the interactive, endpoint-by-endpoint reference.
Base URLs
The API is available in two environments. They are fully isolated: credentials, data, and webhook endpoints created in one environment do not exist in the other.
| Environment | Base URL | Use for |
|---|---|---|
| Sandbox | https://api.sandbox.upprove.com | Integration and testing with test providers. |
| Live | https://api.upprove.com | Real money movement. |
All endpoints are versioned and live under the /v1 path — for example
https://api.sandbox.upprove.com/v1/checkout/sessions.
The base URLs above are placeholders pending confirmation of the production hostnames. They are
defined in one place (the OpenAPI servers block and this page) so they are trivial to update.
Core concepts
| Concept | What it is |
|---|---|
| Checkout session | A hosted payment flow you create for a customer. It produces a URL you redirect the customer to, and resolves to a completed, expired, cancelled, or failed state. |
| Order | The merchant-level record of an intended money movement (payment, refund, or payout). One order may involve several transactions. |
| Transaction | A single attempt at the payment network/provider level (payment, refund, authorization, capture) with its own status and provider references. |
See the Glossary for the full vocabulary.
What you need to know up front
- The API speaks JSON in
snake_casefor every request and response field. - Every request must be authenticated with an API key and signed with your signing secret.
- Orchestr signs its responses and webhooks so you can verify they genuinely came from Orchestr.
- Amounts are decimal values in the transaction currency; see Conventions.
Start with the Getting started guide.