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

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.

Create Mock Payment Gateway Accounts

Mock PSPs are test gateways that return predictable success or failure responses regardless of input. They let you test both code paths without external payment provider accounts. See the Mock Payment Gateways guide for details on limitations and capabilities.

Set up test gateways in the Portal:Success Gateway:

Go to Resources > Payment Gateway Account > Create
Name: testSuccess
Gateway: NULLSuccess
Click Save

Failure Gateway (for testing):

Name: testFailure
Gateway: NULLFailure

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. Create eWallet Account

Create an eWallet Account in the Portal:

Go to Resources > eWallet Accounts > Add Account
Name it testWallet
Select the eWallet Type to be “CardPay”
Set Merchant Identifier to be [your_company_name].com.orchestrasolutions
Set Merchant Display Name to be your company name
Disregard for now all other fields - when you’re ready to set up real use case processes, see Creating eWallet Accounts
Click Save

2. Install Library

npm install @orchestrasolutions/ewallet

3. 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",
  "paymentGatewayAccountId": "testSuccess",
  "allowedeWalletAccountIds": ["testWallet"],
  "mode": "TEST",
  "currencyCode": "USD",
  "countryCode": "US",
  "amount": 2.56,
  "allowedBrands": ["Visa", "MasterCard"]
}'

4. 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);
  // Send result.token to backend for validation
}

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.

5. Validate Result (Backend) - Optional

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.

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.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

A production capture uses the Library’s CHARGE_AND_TOKENIZE operation (or a separate String Token) to produce the token below. 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": "@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO",
    "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: '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
        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': '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
            'expirationYear': 2027,
            'expirationMonth': 12
        }
    }
)

print(response.json())

Sending raw card details directly is only appropriate if your backend already lawfully holds card data, and it puts you 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.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. Create eWallet Account

2. Install Library

3. Create Session (Backend)

4. Display Payment Button (Frontend)

5. Validate Result (Backend) - Optional

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. Create eWallet Account

​2. Install Library

​3. Create Session (Backend)

​4. Display Payment Button (Frontend)

​5. Validate Result (Backend) - Optional

​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. Create eWallet Account

2. Install Library

3. Create Session (Backend)

4. Display Payment Button (Frontend)

5. Validate Result (Backend) - Optional

You’re in

What’s Next

1. Basic Charge

2. Expected Response

You’re in

What’s Next