Use void to cancel an authorization before capture, or refund to return funds after a transaction has been captured.
When to Use Each
| Operation | Use When |
|---|
| Void | Cancel an authorization before capturing funds |
| Refund | Return funds after a charge or capture has completed |
Voids release the hold on the customer’s card immediately. Refunds may take 5-10 business days to appear on the customer’s statement.
Void
Cancel an authorization before capturing. Uses DELETE method.
Void requires re-sending the currency, amount, card, and other details from the original authorization.
const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/void', {
method: 'DELETE',
headers: {
'Content-Type': 'application/json',
'X-Api-Key': 'YOUR_API_KEY'
},
body: JSON.stringify({
refTransId: 'original-transaction-id',
amount: 50.00,
currency: 'USD',
paymentGatewayAccountName: 'stripe-production',
card: {
cardNumber: '4111111111111111',
cardHolderName: 'Jane Smith',
expirationMonth: 12,
expirationYear: 2027,
cvv: '123'
}
})
});
Void Parameters
| Parameter | Type | Required | Description |
|---|
refTransId | string | Yes | Transaction ID to void |
amount | number | Yes | Original authorization amount |
currency | string | Yes | ISO 4217 currency code |
card | object | Yes | Card details from original 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 |
Refund
Refund a captured transaction. Uses PUT method.
const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/refund', {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'X-Api-Key': 'YOUR_API_KEY'
},
body: JSON.stringify({
refTransId: 'original-transaction-id',
amount: 25.00,
currency: 'USD',
paymentGatewayAccountName: 'stripe-production',
card: {
cardNumber: '4111111111111111',
cardHolderName: 'Jane Smith',
expirationMonth: 12,
expirationYear: 2027,
cvv: '123'
}
})
});
Refund Parameters
| Parameter | Type | Required | Description |
|---|
refTransId | string | Yes | Transaction ID to refund |
amount | number | Yes | Amount to refund (can be partial) |
currency | string | Yes | ISO 4217 currency code |
card | object | Yes | Card details |
paymentGatewayAccountName | string | Conditional | Stored gateway account name |
paymentGatewayAccount | object | Conditional | Inline gateway credentials |
payerDetails | object | No | Billing information |
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 |
Partial Refunds
You can refund less than the original amount:
// Original charge was $100.00
// Refund only $25.00
const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/refund', {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'X-Api-Key': 'YOUR_API_KEY'
},
body: JSON.stringify({
refTransId: 'original-transaction-id',
amount: 25.00, // Partial refund
currency: 'USD',
paymentGatewayAccountName: 'stripe-production',
card: {
cardNumber: '4111111111111111',
cardHolderName: 'Jane Smith',
expirationMonth: 12,
expirationYear: 2027,
cvv: '123'
}
})
});
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 |
