Authorize & Capture

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. Authorization places a hold on funds without capturing them immediately. Use capture, void, or refund to complete the transaction lifecycle.

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

When to Use Authorize

Physical goods: Authorize at checkout, capture when shipped
Variable amounts: Authorize an estimate, capture the actual amount
Verification: Confirm a card is valid before providing a service
Hotels/rentals: Authorize a hold, capture the final bill. For deposits, balances and extras across a booking, see Booking Lifecycle

Authorize

The standard integration authorizes 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/authorize', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    amount: 50.00,
    currency: 'USD',
    paymentGatewayAccountName: 'stripeProduction',
    card: {
      cardNumber: '@YOUR_TOKEN',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027
    }
  })
});

const result = await response.json();
// Save the transaction ID for capture/void/refund

curl -X POST https://api.orchestrasolutions.com/PaymentGateway/authorize \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "amount": 50.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/authorize',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'amount': 50.00,
        'currency': 'USD',
        'paymentGatewayAccountName': 'stripeProduction',
        'card': {
            'cardNumber': '@YOUR_TOKEN',
            'cardHolderName': 'Jane Smith',
            'expirationMonth': 12,
            'expirationYear': 2027
        }
    }
)

Authorize API Reference

Complete parameter reference for authorize requests

Save the transaction ID from the response. You’ll need it for capture, void, or refund operations.

Authorize with Failover

Orchestra’s multi-gateway failover retries an authorization 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. On authorize, any result other than Success or Accepted moves to the next gateway:

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

When using failover with authorize, check which gateway processed the transaction in the response. Send the capture, void, or refund to the Payment Gateway Account that processed it, not to your primary account.

See Multi-Gateway Failover for how Orchestra’s failover mechanism works.

Capture

Capture an existing authorization to complete the transaction. Uses PUT method.

Capture requires re-sending the currency, card, and other details from the original authorization.

Capture typically reuses the same token referenced at authorize time.

const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/capture', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    refTransId: 'original-transaction-id',
    amount: 45.00,
    currency: 'USD',
    paymentGatewayAccountName: 'stripeProduction',
    card: {
      cardNumber: '@YOUR_TOKEN',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027
    }
  })
});

curl -X PUT https://api.orchestrasolutions.com/PaymentGateway/capture \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "refTransId": "original-transaction-id",
    "amount": 45.00,
    "currency": "USD",
    "paymentGatewayAccountName": "stripeProduction",
    "card": {
      "cardNumber": "@YOUR_TOKEN",
      "cardHolderName": "Jane Smith",
      "expirationMonth": 12,
      "expirationYear": 2027
    }
  }'

response = requests.put(
    'https://api.orchestrasolutions.com/PaymentGateway/capture',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'refTransId': 'original-transaction-id',
        'amount': 45.00,
        'currency': 'USD',
        'paymentGatewayAccountName': 'stripeProduction',
        'card': {
            'cardNumber': '@YOUR_TOKEN',
            'cardHolderName': 'Jane Smith',
            'expirationMonth': 12,
            'expirationYear': 2027
        }
    }
)

Capture API Reference

Complete parameter reference for capture requests

Completing the Transaction

After authorizing, you have three options:

Action	When to Use
Capture	Ready to fulfill - collect the funds
Void	Cancel before capture - release the hold
Refund	Return funds after capture

For void and refund operations, see Refunds & Voids.

Authorization Expiration

Authorizations do not last forever. How long a hold stays valid depends on your payment processor and the card, so check with your processor. After it expires, the hold is released and you need a new authorization.

Don’t rely on authorization expiration to release holds. If you’re not going to capture, void the authorization explicitly.

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 Authorize and Capture above.

Authorize

const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/authorize', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    amount: 50.00,
    currency: 'USD',
    paymentGatewayAccountName: 'stripeProduction',
    card: {
      cardNumber: '4111111111111111',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});

const result = await response.json();
// Save the transaction ID for capture/void/refund

curl -X POST https://api.orchestrasolutions.com/PaymentGateway/authorize \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "amount": 50.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/authorize',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'amount': 50.00,
        'currency': 'USD',
        'paymentGatewayAccountName': 'stripeProduction',
        'card': {
            'cardNumber': '4111111111111111',
            'cardHolderName': 'Jane Smith',
            'expirationMonth': 12,
            'expirationYear': 2027,
            'cvv': '123'
        }
    }
)

Capture

const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/capture', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    refTransId: 'original-transaction-id',
    amount: 45.00,
    currency: 'USD',
    paymentGatewayAccountName: 'stripeProduction',
    card: {
      cardNumber: '4111111111111111',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});

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

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

Refunds & Voids

Cancel or reverse transactions

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

When to Use Authorize

Authorize

Authorize API Reference

Authorize with Failover

Capture

Capture API Reference

Completing the Transaction

Authorization Expiration

Sending Raw Card Details (Non-Standard)

Authorize

Capture

Refunds & Voids

​When to Use Authorize

​Authorize

Authorize API Reference

​Authorize with Failover

​Capture

Capture API Reference

​Completing the Transaction

​Authorization Expiration

​Sending Raw Card Details (Non-Standard)

​Authorize

​Capture

​Related

Refunds & Voids

When to Use Authorize

Authorize

Authorize with Failover

Capture

Completing the Transaction

Authorization Expiration

Sending Raw Card Details (Non-Standard)

Authorize

Capture

Related