Documentation

Your outbound webhooks

In addition to PSP callbacks hitting our platform, you can register your own HTTPS endpoint to receive normalized payment events for your merchant account. Configure this under Integrations → Webhooks.

• Events fire when payments are created via the REST API, when PSP status webhooks update the ledger, and when you refund.
• Each delivery is signed with HMAC-SHA256 (X-Webhook-Signature).
• Choose event patterns such as payment.* or payment.completed.

{
  "id": "evt_abc123",
  "type": "payment.completed",
  "created_at": "2026-06-01T12:00:00.000Z",
  "livemode": true,
  "data": {
    "transaction": {
      "id": "uuid",
      "reference": "ORDER-12345",
      "provider": "cyberpay",
      "status": "completed",
      "amount": 100,
      "currency": "USD"
    }
  }
}

Overview & authentication

All /api/v1/* endpoints are authenticated with a secret API key passed as a Bearer token. Keys are scoped to your merchant account and can be created and revoked from Integrations → API Keys.

https://payorchestrate.com/api/v1

Authorization: Bearer sk_live_<your-key>

curl https://payorchestrate.com/api/v1

GET /api/v1 — API discovery

Call this endpoint during integration to discover available routes programmatically. The response includes authentication instructions and the same endpoint list documented here.

curl https://payorchestrate.com/api/v1

POST /api/v1/checkout

Creates a hosted checkout session for the specified provider and returns a checkout_url to redirect your customer to.

POST https://payorchestrate.com/api/v1/checkout
Authorization: Bearer sk_live_YOUR_KEY
Content-Type: application/json

{
  "provider": "cyberpay",
  "amount": 100.00,
  "currency": "USD",
  "country": "US",
  "redirect_url": "https://yoursite.com/thank-you",
  "reference": "ORDER-12345",
  "customer": {
    "email": "user@example.com",
    "phone": "+1234567890",
    "first_name": "John",
    "last_name": "Doe"
  }
}

Request body reference

GET /api/v1/transactions

List ledger rows for your merchant account. Results are ordered newest first. Use filters to reconcile by status, provider, or your merchant reference.

GET https://payorchestrate.com/api/v1/transactions?limit=50&status=pending&provider=cyberpay
Authorization: Bearer sk_live_YOUR_KEY

{
  "ok": true,
  "count": 2,
  "transactions": [
    {
      "id": "uuid",
      "reference": "ORDER-12345",
      "provider": "cyberpay",
      "direction": "payin",
      "status": "completed",
      "amount": 100,
      "currency": "USD",
      "checkout_url": "https://cashier.cyberpay.link/...",
      "created_at": "2026-06-01T12:00:00.000Z"
    }
  ]
}

GET /api/v1/transactions/{id}

Fetch a single transaction by internal id (UUID) or your merchant reference (stored as external_id).

GET https://payorchestrate.com/api/v1/transactions/ORDER-12345?refresh=true
Authorization: Bearer sk_live_YOUR_KEY

• refresh=true — polls Cyberpay or PayAgency for the latest status and updates your ledger.
• include=raw — includes the PSP raw payload on the transaction object.

{
  "ok": true,
  "refreshed": true,
  "provider_status": "COMPLETED",
  "transaction": {
    "id": "uuid",
    "reference": "ORDER-12345",
    "status": "completed",
    "provider": "cyberpay"
  }
}

POST /api/v1/refunds

Refund a completed pay-in. The original transaction must belong to your account and match the provider. Refunds cannot be undone.

POST https://payorchestrate.com/api/v1/refunds
Authorization: Bearer sk_live_YOUR_KEY
Content-Type: application/json

{
  "provider": "cyberpay",
  "reference": "ORDER-12345",
  "reason": "Customer requested refund"
}

Supported providers: cyberpay (uses merchant reference), payagency (uses PSP transaction id when available).

POST /api/v1/payouts

Initiate a payout. Behaviour depends on the provider:

• Cyberpay — returns a hosted payout_url (cashier) for the beneficiary to complete.
• PayAgency — direct card payout; requires payout_details (wallet_id, card_number, expiry).
• Swipe — two-step: first call creates a quote_id; second call passes quote_id to execute.

// Cyberpay hosted payout
POST https://payorchestrate.com/api/v1/payouts
{
  "provider": "cyberpay",
  "amount": 50,
  "currency": "USD",
  "country": "US",
  "customer": { "email": "payee@example.com", "phone": "+12125551234" }
}

// Swipe — step 1: create quote
{ "provider": "swipe", "amount": 50, "currency": "USD",
  "destination_id": "swipe-beneficiary-id",
  "customer": { "email": "payee@example.com", "phone": "+12125551234" } }

// Swipe — step 2: execute
{ "provider": "swipe", "quote_id": "quote_abc123",
  "customer": { "email": "payee@example.com", "phone": "+12125551234" } }

Response & errors

{
  "ok": true,
  "checkout_url": "https://cashier.cyberpay.link/session/...",
  "reference": "ORDER-12345",
  "provider": "cyberpay",
  "amount": 100,
  "currency": "USD"
}

{
  "ok": false,
  "error": "Human-readable message",
  "code": "ERROR_CODE"
}

Outbound webhooks (to your server)

The REST API and PSP flows automatically trigger outbound webhooks when you configure a URL in Integrations → Webhooks. You do not call a separate API to enable this — save your endpoint once and events flow when the ledger changes.

Verify signatures on every request. Header format: X-Webhook-Signature: t=1690000000,v1=<hmac_hex> where v1 = HMAC-SHA256(secret, "{timestamp}.{body}").

Use Send test event in the dashboard to validate your handler before going live.

Inbound PSP webhooks & reconciliation

Pay-ins and payouts created via the API use the same webhook endpoints as the dashboard and embed flows. Configure your PSP dashboard to send notifications to:

• https://payorchestrate.com/api/webhooks/cyberpay
• https://payorchestrate.com/api/webhooks/payagency
• https://payorchestrate.com/api/webhooks/swipelux
• https://payorchestrate.com/api/webhooks/b2binpay

Use GET /api/v1/transactions/{reference}?refresh=true when you need an on-demand status poll before the webhook arrives. Your reference from checkout is stored as external_id and echoed in webhook payloads where the PSP supports it.

Code examples

curl -X POST https://payorchestrate.com/api/v1/checkout \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d ‘{
    "provider": "cyberpay",
    "amount": 100.00,
    "currency": "USD",
    "country": "US",
    "redirect_url": "https://yoursite.com/thank-you",
    "reference": "ORDER-12345",
    "customer": {
      "email": "user@example.com",
      "phone": "+12125551234",
      "first_name": "Jane",
      "last_name": "Smith"
    }
  }’

const res = await fetch("https://payorchestrate.com/api/v1/checkout", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    provider: "cyberpay",
    amount: 100.00,
    currency: "USD",
    country: "US",
    redirect_url: "https://yoursite.com/thank-you",
    reference: "ORDER-12345",
    customer: {
      email: "user@example.com",
      phone: "+12125551234",
      first_name: "Jane",
      last_name: "Smith",
    },
  }),
});

const { ok, checkout_url, error } = await res.json();
if (!ok) throw new Error(error);

// Redirect the customer
window.location.href = checkout_url;

import requests

response = requests.post(
    "https://payorchestrate.com/api/v1/checkout",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
    json={
        "provider": "cyberpay",
        "amount": 100.00,
        "currency": "USD",
        "country": "US",
        "redirect_url": "https://yoursite.com/thank-you",
        "reference": "ORDER-12345",
        "customer": {
            "email": "user@example.com",
            "phone": "+12125551234",
            "first_name": "Jane",
            "last_name": "Smith",
        },
    },
)

data = response.json()
if not data["ok"]:
    raise Exception(data["error"])

checkout_url = data["checkout_url"]
# Redirect the customer to checkout_url