Getting Started

You can go from zero to a live payment in 4 steps:

1. Get your API Keys: from our Dashboard, store it in your secrets.
2. Create a Payment Intent: from your back-end to our API.
3. Collect the payment: redirect the user to our hosted payment page or embed a customizable Payment Form.
4. Handle success: listen for webhooks that confirm a payment succeeded or failed.

You only ever talk to the Orchestrapay API. We handle every underlying gateway, so the same integration works whether you process with one gateway or orchestrate across hundreds.

Before you start

You will need at least 1 connector to start testing. Add "Sandbox Gateway" to your connectors on a sandbox tenant.

Step 1 - Get your API Keys

You can create & access your API keys in your Settings.

• a secret key (orch_sk_live_eu1_...) used on your server, never expose it in the browser
• a public key (orch_pk_live_eu1_...) safe to use in the browser.

API Keys are tied to a tenant, you will need to create a Sandbox Tenant to access the Sandbox Gateway connector and sandbox gateway endpoints. Keys are also scoped to the Region you selected on sign-up.

Step 2 - Create a payment intent

A payment intent represents a single payment promise. Always create it on your server so your secret key stays private. All you need is an amount and a currency.

Typescript

Add our package to your dependency tree:

Terminal

npm install @orchestrapay/sdk

Generate a payment intent:

server.ts

import Orchestrapay from "@orchestrapay/sdk";

const orchestrapay = new Orchestrapay("orch_sk_live_eu1_...");

const { payment_intent } = await orchestrapay.paymentIntents.create({
  amount: 4999, // amounts in cents ($49.99)
  currency: "usd",
});

// payment_intent = pi_eu1_b8b5be0f481f42b4b7f5972118777c5f

cURL

The API is region-specific: swap {region} in api-{region}.orchestrapay.com for your account's region host (for example api-europe or api-egypt). See Environments for the full list. The SDKs derive this from your key automatically.

Terminal

curl -X POST https://api-{region}.orchestrapay.com/v202606/payment-intents \
  -H "Authorization: Bearer orch_sk_live_eu1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4999,
    "currency": "usd",
    "final_success_url": "https://yoursite.com/order/success",
    "final_failure_url": "https://yoursite.com/order/cancelled",
    "webhook_urls": ["https://yoursite.com/webhooks/orchestrapay"],
    "webhook_secret": "your_webhook_secret"
  }'

Response:

Response

{
  "payment_intent": "pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
  "payment_intent_created": true
}

You can customize your Payment Intents with many useful properties, such as indempotency keys, custom timeouts, webhook URLs, success/failure redirections, customer ID, etc. Check out the Payment Intents API.

Step 3 - Collect the payment

You can either redirect the user to an Orchestrapay hosted payment page, where they will be redirected back to your target URL on success/failure, or you can embed the pamyent form directly into your website/application.

Link

With the payment_intent in hand, redirect the customer to the Orchestrapay hosted page:

Hosted checkout URL

https://pay.orchestrapay.com/pay/pi_eu1_b8b5be0f481f42b4b7f5972118777c5f

This page runs the full payment flow for every gateway you connected, with no extra frontend work. When the payment finishes, the customer is sent to the final_success_url / final_failure_url you set in Step 2.

Embedded

Prefer to keep customers on your site? Embed the form with the React SDK instead of redirecting:

Terminal

npm install @orchestrapay/react

CheckoutPage.tsx

import { PaymentForm } from "@orchestrapay/react";

export function CheckoutPage({ paymentIntent }: { paymentIntent: string }) {
  return (
    <PaymentForm
      publicKey="orch_pk_live_eu1_..."
      paymentIntent={paymentIntent}
      onPaymentSuccess={() => console.log("Payment succeeded")}
      onPaymentFailure={(err) => console.error("Payment failed", err)}
    />
  );
}

You can style the embedded form to match your brand. See UI Styling.

Step 4 - Handling webhooks

If you've provided 1 or multiple webhook URLs when creating your Payment Intent, we will send you webhook requests for each events that you've subscribed to. In Orchestrapay, you set the webhook subscriptions on a per-payment intent basis, which is very handy when you're doing end-to-end testing.

webhooks.ts

import { verifyWebhookSecret, WEBHOOK_SECRET_HEADER } from "@orchestrapay/sdk";

app.post("/webhooks/orchestrapay", express.json(), (req, res) => {
  const received = req.headers[WEBHOOK_SECRET_HEADER] as string | undefined;
  if (!verifyWebhookSecret(received, process.env.ORCHESTRAPAY_WEBHOOK_SECRET!)) {
    return res.status(401).send("Invalid webhook secret");
  }

  const event = req.body; // { status, sub_status, ... }
  // handle event.status: "pending" | "success" | "canceled"

  res.sendStatus(200);
});

See Webhooks for the full payload reference.