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 Parameters
Same parameters as Charge: amount, currency, card, paymentGatewayAccountName, paymentGatewayAccount, myRef, payerDetails, isDigital, orderDesc, certificateName, networkTokenBrand.
Save the transaction ID from the response. You’ll need it for capture, void, or refund operations.
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 Parameters
| Parameter | Type | Required | Description |
|---|
refTransId | string | Yes | Transaction ID from the authorization |
amount | number | Yes | Amount to capture (can be less than authorized) |
currency | string | Yes | ISO 4217 currency code |
card | object | Yes | Card details (same as authorization) |
paymentGatewayAccountName | string | Conditional | Stored gateway account name |
paymentGatewayAccount | object | Conditional | Inline gateway credentials |
myRef | string | No | Your custom reference |
certificateName | string | No | Client certificate name if required by gateway |
networkTokenBrand | string | No | For network tokens: Visa, MasterCard, or Amex |
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 |
Response Codes
| Code | Description |
|---|
202 | Accepted - sent to payment gateway |
400 | Bad request - invalid parameters |
401 | Not authenticated - invalid API key |
409 | Conflict - rejected by payment gateway |
500 | Error with payment gateway |
503 | Temporary failure with payment gateway |
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.
