Authorize & Capture

This page is part of the REST API Guides. Using the JavaScript library instead? See 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

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'
        }
    }
)

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.

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'
        }
    }
)

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.

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

Refunds & Voids

​When to Use Authorize

​Authorize

Authorize API Reference

​Authorize with Failover

Contact Support

​Capture

Capture API Reference

​Completing the Transaction

​Authorization Expiration

​Related

Refunds & Voids

When to Use Authorize

Authorize

Authorize with Failover

Capture

Completing the Transaction

Authorization Expiration

Related