Getting started

This guide takes you from zero to your first signed API call — creating a checkout session — and verifying the signed response.

1. Get your credentials

From the Orchestr Dashboard, in the environment you want to use (Sandbox or Live), create:

1. A secret API key (sk_test_… in Sandbox). Shown once — store it securely.
2. A signing secret. Also shown once.

Export them so the examples below can read them:

export ORCHESTR_SECRET_KEY="sk_test_..."
export ORCHESTR_SIGNING_SECRET="your-signing-secret"

2. Know the basics

• Base URL (Sandbox): https://api.sandbox.upprove.com
• All requests are JSON in snake_case.
• Every request needs two headers: Authorization: Bearer <key> and a signed X-Signature (see Signing).

3. Create your first checkout session

This POST /v1/checkout/sessions call creates a hosted checkout and returns a url to redirect your customer to. The examples reuse the buildSignatureHeader helper from the Signing guide.

Card payments are offered on the hosted page automatically — no extra integration. The card result (including the card token, and saving cards for later) arrives on your webhooks; see Cards on hosted checkout.

cURL

REQ_PATH="/v1/checkout/sessions"
BODY='{"amount":"42.00","currency":"GBP","merchant_reference":"order-1001","success_url":"https://shop.example.com/ok","cancel_url":"https://shop.example.com/cancel","customer":{"email":"jane@example.com"}}'
TS=$(date +%s)
SIG=$(printf '%s' "${TS}${REQ_PATH}${BODY}" \
  | openssl dgst -sha256 -hmac "$ORCHESTR_SIGNING_SECRET" | sed 's/^.*= //')

curl -sS -X POST "https://api.sandbox.upprove.com${REQ_PATH}" \
  -H "Authorization: Bearer $ORCHESTR_SECRET_KEY" \
  -H "X-Signature: t=${TS}, v1=${SIG}" \
  -H "Content-Type: application/json" \
  --data-raw "$BODY"

Node.js

const path = '/v1/checkout/sessions';
const body = JSON.stringify({
  amount: '42.00',
  currency: 'GBP',
  merchant_reference: 'order-1001',
  success_url: 'https://shop.example.com/ok',
  cancel_url: 'https://shop.example.com/cancel',
  customer: {email: 'jane@example.com'},
});

const res = await fetch(`https://api.sandbox.upprove.com${path}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORCHESTR_SECRET_KEY}`,
    'X-Signature': buildSignatureHeader(process.env.ORCHESTR_SIGNING_SECRET, path, body),
    'Content-Type': 'application/json',
  },
  body,
});
const session = await res.json();
console.log(session.id, session.url);

Python

import json
import requests

path = "/v1/checkout/sessions"
body = json.dumps(
    {
        "amount": "42.00",
        "currency": "GBP",
        "merchant_reference": "order-1001",
        "success_url": "https://shop.example.com/ok",
        "cancel_url": "https://shop.example.com/cancel",
        "customer": {"email": "jane@example.com"},
    },
    separators=(",", ":"),
)

resp = requests.post(
    f"https://api.sandbox.upprove.com{path}",
    data=body,
    headers={
        "Authorization": f"Bearer {ORCHESTR_SECRET_KEY}",
        "X-Signature": build_signature_header(ORCHESTR_SIGNING_SECRET, path, body),
        "Content-Type": "application/json",
    },
)
session = resp.json()
print(session["id"], session["url"])

PHP

<?php
$path = '/v1/checkout/sessions';
$body = json_encode([
    'amount' => '42.00',
    'currency' => 'GBP',
    'merchant_reference' => 'order-1001',
    'success_url' => 'https://shop.example.com/ok',
    'cancel_url' => 'https://shop.example.com/cancel',
    'customer' => ['email' => 'jane@example.com'],
], JSON_UNESCAPED_SLASHES);

$ch = curl_init("https://api.sandbox.upprove.com{$path}");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ORCHESTR_SECRET_KEY'),
        'X-Signature: ' . build_signature_header(getenv('ORCHESTR_SIGNING_SECRET'), $path, $body),
        'Content-Type: application/json',
    ],
]);
$session = json_decode(curl_exec($ch), true);
echo $session['id'], ' ', $session['url'];

Java

String path = "/v1/checkout/sessions";
String body = """
    {"amount":"42.00","currency":"GBP","merchant_reference":"order-1001",\
"success_url":"https://shop.example.com/ok","cancel_url":"https://shop.example.com/cancel",\
"customer":{"email":"jane@example.com"}}""";

HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.sandbox.upprove.com" + path))
    .header("Authorization", "Bearer " + System.getenv("ORCHESTR_SECRET_KEY"))
    .header("X-Signature", buildSignatureHeader(System.getenv("ORCHESTR_SIGNING_SECRET"), path, body))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

C#

var path = "/v1/checkout/sessions";
var body = "{\"amount\":\"42.00\",\"currency\":\"GBP\",\"merchant_reference\":\"order-1001\"," +
           "\"success_url\":\"https://shop.example.com/ok\",\"cancel_url\":\"https://shop.example.com/cancel\"," +
           "\"customer\":{\"email\":\"jane@example.com\"}}";

using var http = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, $"https://api.sandbox.upprove.com{path}")
{
    Content = new StringContent(body, Encoding.UTF8, "application/json"),
};
request.Headers.Add("Authorization", $"Bearer {Environment.GetEnvironmentVariable("ORCHESTR_SECRET_KEY")}");
request.Headers.Add("X-Signature",
    BuildSignatureHeader(Environment.GetEnvironmentVariable("ORCHESTR_SIGNING_SECRET"), path, body));
var response = await http.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

4. Read the response

A 201 Created is returned with the checkout session. Redirect the customer to url:

{
  "id": "cs_7e6d5c4b",
  "url": "https://checkout.sandbox.upprove.com/cs_7e6d5c4b",
  "status": "open",
  "merchant_reference": "order-1001",
  "order_id": "ord_5b4a3c2d",
  "amount": 42.00,
  "currency": "GBP",
  "success_url": "https://shop.example.com/checkout/success",
  "cancel_url": "https://shop.example.com/checkout/cancel",
  "created_at": "2024-06-22T10:00:00Z"
}

The response carries an X-Signature header. Verify it before trusting the body — use the verification helper from Signing (the signed string for responses is timestamp + body).

5. Get notified of the outcome

When the customer finishes paying, Orchestr sends a checkout.session.completed webhook. Register an endpoint in the Dashboard, verify the signature, and fulfil the order. You can also fetch the session any time:

GET https://api.sandbox.upprove.com/v1/checkout/sessions/cs_7e6d5c4b

Next steps

• Authentication and Signing in depth.
• Direct payments — create a payment in one call, without a hosted session.
• Webhooks to handle events.
• The full API Reference.