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. For what this integration means for your PCI DSS scope, see PCI Scope and Compliance. 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, in place of @YOUR_TOKEN below; cvv is optional and can be left out for a tokenized card. A token only works in the account that created it: a token from another account, including any shown in these docs, returns 400.

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: '@YOUR_TOKEN',
      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": "@YOUR_TOKEN",
      "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': '@YOUR_TOKEN',
            '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 you need to send raw card details 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: '@YOUR_TOKEN',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027
    }
  })
});

Adding Failover

Orchestra’s multi-gateway failover retries a charge on a backup gateway if the primary fails. Add a fallbackUpgs array to the request body. Each entry names a stored Payment Gateway Account in paymentGatewayAccountName, and Orchestra tries them in order:

{
  "amount": 25.00,
  "currency": "USD",
  "paymentGatewayAccountName": "stripeProduction",
  "fallbackUpgs": [
    { "paymentGatewayAccountName": "adyenBackup" }
  ],
  "card": {
    "cardNumber": "@YOUR_TOKEN",
    "cardHolderName": "Jane Smith",
    "expirationMonth": 12,
    "expirationYear": 2027
  }
}

The response is the result of the last attempt. See Multi-Gateway Failover for which failures trigger failover and how the response works.

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

Charge vs Authorize

Sending Raw Card Details (Non-Standard)

Refunds & Voids

Authorize & Capture

Tokenization

​Basic Charge

API Reference

​Using Inline Credentials

​Adding Failover

​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