Quickstart

This guide walks you through creating a sandbox account, setting up mock payment gateways, and making your first test charge. No external payment provider accounts required.

This quickstart uses Orchestra’s built-in mock payment gateways for immediate testing. When you’re ready for production, see Add a Payment Provider.

Setup

Create Orchestra Account

Create Your Mock Environment

On the portal home page, select Create your mock environment on the Payments Library card. It creates everything this guide uses: a mock payment gateway account named testSuccess and a CardPay eWallet account named testWallet.

Mock payment gateways return predictable responses without an external payment provider account. See Mock Payment Gateways.

Generate API Key

Create an API key to authenticate your requests:

Go to API Keys > Create
Enter a Name for the key (e.g., “Development”)
Ignore the User setting for now - when you’re ready, see Managing Users and Permissions
Click Save
Copy the key immediately - you won’t see it again

Copy the key now - you won’t be able to view it again.

Capture with the Library, Operate with the API

Payments Library

Start here. Capture your first payment in the frontend: pre-built UI, reduced PCI scope, supports digital wallets (Apple Pay, Google Pay).Demonstrates:

Session creation
Frontend integration with payment buttons
Result validation

REST API

Then drive backend operations on the payment the Library captured: charges on stored tokens, refunds, recurring billing, custom flows.Demonstrates:

Basic charges
Tokenization for PCI scope reduction

Capture a payment (Library)
Backend operations (REST API)

1. Install Library

npm install @orchestrasolutions/ewallet

2. Create Session (Backend)

curl --location 'https://api.orchestrasolutions.com/EWalletOperations' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "operation": "CHARGE_AND_TOKENIZE",
  "paymentGatewayAccountId": "testSuccess",
  "allowedeWalletAccountIds": ["testWallet"],
  "mode": "TEST",
  "currencyCode": "USD",
  "countryCode": "US",
  "amount": 2.56,
  "allowedBrands": ["Visa", "MasterCard"]
}'

3. Display Payment Button (Frontend)

<div id="card-button"></div>

import * as eWallet from '@orchestrasolutions/ewallet';

// Initialize with JWT from backend
const engine = new eWallet.Engine(jwt);

// Check available payment methods
const available = await engine.checkAvailability();

// Display card payment button
engine.payBy(
  [{ name: 'CardPay', domEntitySelector: '#card-button' }],
  handleResult,
  undefined
);

function handleResult(result) {
  // User cancelled
  if (!result) {
    console.log('Payment cancelled');
    return;
  }

  const [data] = engine.parseResultToken(result.token);
  console.log('Payment successful:', data);
  // The stored card token, for later charges through the REST API
  console.log('Card token:', data.tokenAndMaskedCardModel.token);
  // Send result.token to backend for validation
}

CHARGE_AND_TOKENIZE charges the card and stores it in one step. Keep the card token: the REST API tab uses it.

This is where credit card details are submitted on the frontend. The Payments Library handles card collection and tokenization, keeping sensitive data out of your backend code.

4. Validate Result (Backend)

Validate the result token received from Orchestra on the client side and passed to your server. This ensures the token wasn’t altered between the client and server. Always validate before you fulfil an order.

curl --location 'https://api.orchestrasolutions.com/EWalletOperations/validateResults' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '"RESULT_TOKEN_FROM_FRONTEND"'

You’re in

You just completed an Orchestra integration using the Payments Library with mock PSPs. These examples demonstrate Orchestra’s key capabilities without requiring external payment provider accounts.

Your compliance officer will ask what this means for your PCI DSS scope. Send them PCI Scope and Compliance: which SAQ applies to you, and the compliance documents you can request from us.

Ready for production? See Add a Payment Provider to configure real gateways. Your code stays the same - just swap the gateway account names.

What’s Next

Complete Example

Full server + client code you can clone and run

Library Setup

Full configuration and customization

Payment Methods

CardPay, ApplePay, GooglePay, PayPal, and more

Add Real Providers

Configure Stripe, Adyen, and more

The standard integration charges a token captured by the Payments Library instead of sending raw card details: pass the token as an @TOKEN reference in the cardNumber field. See Payments Library and REST API for the token pattern.

1. Basic Charge

Run the Payments Library tab first and use the card token it returns, with @ in front, in place of @YOUR_TOKEN below. A token only works in the account that created it: a token from another account, including any shown in these docs, returns 400. cvv is optional and can be left out for a tokenized card.

curl --location 'https://api.orchestrasolutions.com/PaymentGateway/charge' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "paymentGatewayAccountName": "testSuccess",
  "amount": 2.56,
  "currency": "USD",
  "myRef": "PaymentX11235",
  "card": {
    "cardType": "Visa",
    "cardHolderName": "Testing Tester",
    "cardNumber": "@YOUR_TOKEN",
    "expirationYear": 2027,
    "expirationMonth": 12
  }
}'

const response = await fetch(
  'https://api.orchestrasolutions.com/PaymentGateway/charge',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      paymentGatewayAccountName: 'testSuccess',
      amount: 2.56,
      currency: 'USD',
      myRef: 'PaymentX11235',
      card: {
        cardType: 'Visa',
        cardHolderName: 'Testing Tester',
        cardNumber: '@YOUR_TOKEN',
        expirationYear: 2027,
        expirationMonth: 12
      }
    })
  }
);

const result = await response.json();
console.log(result);

import requests

response = requests.post(
    'https://api.orchestrasolutions.com/PaymentGateway/charge',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'paymentGatewayAccountName': 'testSuccess',
        'amount': 2.56,
        'currency': 'USD',
        'myRef': 'PaymentX11235',
        'card': {
            'cardType': 'Visa',
            'cardHolderName': 'Testing Tester',
            'cardNumber': '@YOUR_TOKEN',
            'expirationYear': 2027,
            'expirationMonth': 12
        }
    }
)

print(response.json())

Send raw card details only if you are already PCI DSS compliant, or if the cards come from a PCI-compliant vault that sends them to Orchestra directly. Otherwise card data passes through your systems and puts them in PCI DSS scope.See Sending Raw Card Details (Non-Standard) in the Charge Payments guide for that pattern.

2. Expected Response

{
  "authorizationCode": "fbbb8b",
  "currency": "USD",
  "amount": 2.56,
  "operationType": "Charge",
  "operationResultCode": "Success",
  "operationResultDescription": "Successful operation",
  "gatewayName": "NULLSuccess",
  "gatewayReference": "b362db",
  "gatewayResultCode": "OK",
  "gatewayResultDescription": "Gateway says: Successful operation",
  "gatewayResultSubCode": null,
  "gatewayResultSubDescription": null
}

You’re in

You just completed an Orchestra REST API integration using mock PSPs. These examples demonstrate Orchestra’s key capabilities without requiring external payment provider accounts.

Your compliance officer will ask what this means for your PCI DSS scope. Send them PCI Scope and Compliance: which SAQ applies to you, and the compliance documents you can request from us.

Ready for production? See Add a Payment Provider to configure real gateways. Your code stays the same - just swap the gateway account names.

What’s Next

Multi-Gateway Failover

Automatic failover across providers

Authorize & Capture

Hold funds and capture later

Refunds & Voids

Reverse transactions

Add Real Providers

Configure Stripe, Adyen, and more

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

Setup

Capture with the Library, Operate with the API

Payments Library

REST API

1. Install Library

2. Create Session (Backend)

3. Display Payment Button (Frontend)

4. Validate Result (Backend)

You’re in

What’s Next

Complete Example

Library Setup

Payment Methods

Add Real Providers

1. Basic Charge

2. Expected Response

You’re in

What’s Next

Multi-Gateway Failover

Authorize & Capture

Refunds & Voids

Add Real Providers

​Setup

​Capture with the Library, Operate with the API

Payments Library

REST API

​1. Install Library

​2. Create Session (Backend)

​3. Display Payment Button (Frontend)

​4. Validate Result (Backend)

​You’re in

​What’s Next

Complete Example

Library Setup

Payment Methods

Add Real Providers

​1. Basic Charge

​2. Expected Response

​You’re in

​What’s Next

Multi-Gateway Failover

Authorize & Capture

Refunds & Voids

Add Real Providers

Setup

Capture with the Library, Operate with the API

1. Install Library

2. Create Session (Backend)

3. Display Payment Button (Frontend)

4. Validate Result (Backend)

You’re in

What’s Next

1. Basic Charge

2. Expected Response

You’re in

What’s Next