Charge Payments

This page is part of the REST API Guides. Card capture happens in the frontend through the Payments Library; see the Payments Library Guides.

Prerequisites: API key and Payment Gateway Account configured. The charge operation captures funds from a card immediately. Use this for standard purchases where you’re ready to fulfill the order.

Some payment processors require additional parameters. See the Additional Guidance section for processor-specific requirements.

Basic Charge

The standard integration charges a token captured by the Payments Library. Reference it in the cardNumber field with an @ prefix; cvv is optional and can be left out for a tokenized card.

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({
    amount: 25.00,
    currency: 'USD',
    paymentGatewayAccountName: 'stripeProduction',
    card: {
      cardNumber: '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027
    }
  })
});

const result = await response.json();

curl -X POST https://api.orchestrasolutions.com/PaymentGateway/charge \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "amount": 25.00,
    "currency": "USD",
    "paymentGatewayAccountName": "stripeProduction",
    "card": {
      "cardNumber": "@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO",
      "cardHolderName": "Jane Smith",
      "expirationMonth": 12,
      "expirationYear": 2027
    }
  }'

import requests

response = requests.post(
    'https://api.orchestrasolutions.com/PaymentGateway/charge',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'amount': 25.00,
        'currency': 'USD',
        'paymentGatewayAccountName': 'stripeProduction',
        'card': {
            'cardNumber': '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
            'cardHolderName': 'Jane Smith',
            'expirationMonth': 12,
            'expirationYear': 2027
        }
    }
)

API Reference

Complete parameter reference, response fields, and validation rules

The token replaces the card number only. You still send cardHolderName, expirationMonth, and expirationYear. When tokenizing through the library, these are returned alongside the token in tokenAndMaskedCardModel.bankCard. See Tokenization for creating tokens with StringTokens directly.

If your backend already lawfully holds card data and needs to send it directly, see Sending Raw Card Details (Non-Standard) below.

Using Inline Credentials

Instead of a stored Payment Gateway Account, you can provide credentials inline:

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({
    amount: 25.00,
    currency: 'USD',
    paymentGatewayAccount: {
      paymentGatewayName: 'Stripe',
      credentials: [
        { Key: 'SecretKey', Value: 'sk_live_...' }
      ]
    },
    card: {
      cardNumber: '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027
    }
  })
});

Adding Failover

Orchestra’s multi-gateway failover automatically retries a charge on a backup gateway if the primary fails. For charge requests, failover isn’t a field you pass in the request body: it’s configured on your Payment Gateway Account setup.

Contact Support

Email support@orchestrasolutions.com to enable multi-gateway failover for your charge requests.

See Multi-Gateway Failover for how Orchestra’s failover mechanism works, including a self-serve example on the eWallet checkout session endpoint.

Charge vs Authorize

Operation	When to Use
Charge	Immediate fulfillment, digital goods, services
Authorize	Delayed fulfillment, physical goods, variable amounts

If you need to hold funds without capturing immediately, use Authorize & Capture instead.

Sending Raw Card Details (Non-Standard)

These examples show raw card details for completeness. Sending raw card data means it passes through your systems and puts you in PCI DSS scope. The standard integration captures the card with the Payments Library and references it here as a token (an @TOKEN value in the cardNumber field); see Basic Charge above.

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({
    amount: 25.00,
    currency: 'USD',
    paymentGatewayAccountName: 'stripeProduction',
    card: {
      cardNumber: '4111111111111111',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});

const result = await response.json();

curl -X POST https://api.orchestrasolutions.com/PaymentGateway/charge \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "amount": 25.00,
    "currency": "USD",
    "paymentGatewayAccountName": "stripeProduction",
    "card": {
      "cardNumber": "4111111111111111",
      "cardHolderName": "Jane Smith",
      "expirationMonth": 12,
      "expirationYear": 2027,
      "cvv": "123"
    }
  }'

import requests

response = requests.post(
    'https://api.orchestrasolutions.com/PaymentGateway/charge',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'amount': 25.00,
        'currency': 'USD',
        'paymentGatewayAccountName': 'stripeProduction',
        'card': {
            'cardNumber': '4111111111111111',
            'cardHolderName': 'Jane Smith',
            'expirationMonth': 12,
            'expirationYear': 2027,
            'cvv': '123'
        }
    }
)

Refunds & Voids

Reverse or cancel this charge

Authorize & Capture

Hold funds and capture later

Tokenization

Store card numbers securely

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

Basic Charge

API Reference

Using Inline Credentials

Adding Failover

Contact Support

Charge vs Authorize

Sending Raw Card Details (Non-Standard)

Refunds & Voids

Authorize & Capture

Tokenization

​Basic Charge

API Reference

​Using Inline Credentials

​Adding Failover

Contact Support

​Charge vs Authorize

​Sending Raw Card Details (Non-Standard)

​Related

Refunds & Voids

Authorize & Capture

Tokenization

Basic Charge

Using Inline Credentials

Adding Failover

Charge vs Authorize

Sending Raw Card Details (Non-Standard)

Related