Quickstart
Welcome to the Orchestrate API quickstart guide. Here, you'll learn how to generate your API key, make your first API request, and discover where to find everything you need to unlock the full potential of our robust REST API.
Setting the server base URL
The Orchestrate API is hosted on a secure server. The base URL for the sandbox environment is https://sandbox.orchestrate.global while the production environment is https://orchestrate.global.
The following sections of this guide will assume that the ORCHESTRATE_BASE_URL environment variable is set appropriately for your environment (sandbox or production).
Generating your API key
Before you can make requests to the Orchestrate API, you will need to generate your API key from Developer » API Keys in your dashboard and store it in a secure place.
To authenticate your requests to access any of the endpoints in the Orchestrate API, you must include your API key as a bearer token in the Authorization header of your requests.
For more details on authentication, see our Authentication guide.
The following sections of this guide will assume that the ORCHESTRATE_API_KEY environment variable is set with the API key you generated in the previous step.
Supported Currencies
Orchestrate supports the following currencies for payments:
| Currency | Code |
|---|---|
| US Dollar | USD |
| Euro | EUR |
| British Pound | GBP |
| Canadian Dollar | CAD |
When creating payments, use the appropriate currency code in the currency field.
Creating your first Payment
To initiate a payment with Orchestrate, you first need to create a Payment, which serves as a unique reference for a specific transaction and represents your intent to collect funds from a customer.
By generating a payment, you establish the details of the transaction—such as the amount, currency, and customer information—which can then be shared with your customer to complete the payment process.
Creating a payment
curl -X POST "$ORCHESTRATE_BASE_URL/api/v1/payments" \
-H "Authorization: Bearer $ORCHESTRATE_API_KEY" \
-d '{
"amount": 100,
"currency": "USD",
"mcc": 6012,
"customer": {
"name": "John Doe",
"email": "john@example.com"
},
"description": "Payment for order #123",
"success_url": "https://example.com/orders/order-123/payment-success",
"cancel_url": "https://example.com/orders/order-123/payment-cancel",
"metadata": {
"order_id": "order-123",
"product_id": "prod-456"
"other": "metadata"
},
"expires_in": 3600
}'
Payment collection
After creating a payment, you'll receive an HTTP 201 Created response with a payment object.
The payment object contains a payment_link that you can use to redirect your customer to a secure and user-friendly interface that allows them to complete the payment process.
{
"id": "cbbbc264-1248-49aa-ae2d-1aa05cf79bc8",
"status": "pending",
"description": "Payment for services",
"metadata": {
"order_id": 212121212
},
"currency": "USD",
"amount": "500.0",
"updated_at": "2025-08-18T15:27:43Z",
"completed_at": null,
"expires_at": "2025-08-18T15:32:43Z",
"created_at": "2025-08-18T15:27:43Z",
"payment_link": "https://sandbox.orchestrate.global/payments/cbbbc264-1248-49aa-ae2d-1aa05cf79bc8/collection",
"payment_method": null,
"customer": {
"id": "698adc6c-bb99-44cb-9715-c3599d587148",
"name": "Foobar",
"email": "foobar@example.com"
},
"success_url": "https://example.com/orders/order-123/payment-success",
"cancel_url": "https://example.com/orders/order-123/payment-cancel"
}
In the sandbox environment, visiting the payment_link simulates the payment process and does not collect real funds.
You can use this link to test the payment flow end-to-end without any actual money being transferred.
For card payments, you can use the following test card details:
- Card number:
4242 4242 4242 4242 - Expiry date: Any valid future date (e.g.,
12/34) - CVC: Any 3 digits (e.g.,
123)
Success URL
After your customer completes the payment process, they will be redirected to the success_url you provided when creating the payment. Your application should handle this redirect and display a success or failure message to the customer based on the payment outcome.
Payment status
The payment status is a string that indicates the current state of the payment. It can be one of the following values:
pending: The payment is pending and has not been completed yet.completed: The payment has been completed successfully.expired: The payment has expired and was not completed.failed: The payment has failed and was not completed.
Retrieving payment details
To retrieve the details of a payment, you can make a GET request to the /api/v1/payments/:id endpoint.
Getting payment details
curl -X GET "$ORCHESTRATE_BASE_URL/api/v1/payments/cbbbc264-1248-49aa-ae2d-1aa05cf79bc8" \
-H "Authorization: Bearer $ORCHESTRATE_API_KEY"
Sample response:
{
"id": "cbbbc264-1248-49aa-ae2d-1aa05cf79bc8",
"status": "completed"
// Other payment details...
}
Webhooks
Webhooks enable your server to automatically receive updates about important payment events—such as when a payment is completed, expires, or fails—without needing to poll the API.
To set up webhooks, add your endpoint in the Orchestrate dashboard under Developer » Webhooks.
What's next?
Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the Orchestrate API: