Skip to main content
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: 'stripe-production',
    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

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

To automatically try backup gateways if the primary fails, add a fallbackUpgs array: 
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: 'stripe-production',
    fallbackUpgs: [
      { paymentGatewayAccountName: 'adyen-backup' }
    ],
    card: {
      cardNumber: '4111111111111111',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});
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 the full guide.

​
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: 'stripe-production',
    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:
ActionWhen to Use
CaptureReady to fulfill - collect the funds
VoidCancel before capture - release the hold
RefundReturn 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