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

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: '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
      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": "@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO",
      "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': '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
            '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 automatically retries an authorization on a backup gateway if the primary fails. For authorize 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 authorize requests.

When using failover with authorize, check which gateway processed the transaction in the response. Use the same gateway for the subsequent capture, void, or refund.

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

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: '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
      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": "@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO",
      "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': '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
            '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 expire if not captured (typically 7-30 days depending on card network). After expiration, the hold is released and you’ll 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

Contact Support

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

Contact Support

​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