Refunds & Voids

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, Payment Gateway Account, and an existing transaction to refund or void. 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.

The standard integration voids 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/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: 'stripeProduction',
    card: {
      cardNumber: '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027
    }
  })
});

curl -X DELETE https://api.orchestrasolutions.com/PaymentGateway/void \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "refTransId": "original-transaction-id",
    "amount": 50.00,
    "currency": "USD",
    "paymentGatewayAccountName": "stripeProduction",
    "card": {
      "cardNumber": "@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO",
      "cardHolderName": "Jane Smith",
      "expirationMonth": 12,
      "expirationYear": 2027
    }
  }'

import requests

response = requests.delete(
    'https://api.orchestrasolutions.com/PaymentGateway/void',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'refTransId': 'original-transaction-id',
        'amount': 50.00,
        'currency': 'USD',
        'paymentGatewayAccountName': 'stripeProduction',
        'card': {
            'cardNumber': '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
            'cardHolderName': 'Jane Smith',
            'expirationMonth': 12,
            'expirationYear': 2027
        }
    }
)

Void API Reference

Complete parameter reference for void requests

Refund

Refund a captured transaction. Uses PUT method. The standard integration refunds a token captured by the Payments Library (for example with the library’s CHARGE_AND_TOKENIZE operation or via String Tokens). Pass it in card.cardNumber with an @ prefix; there is no dedicated token field on refund or void.

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: 'stripeProduction',
    card: {
      cardNumber: '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027
    }
  })
});

curl -X PUT https://api.orchestrasolutions.com/PaymentGateway/refund \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "refTransId": "original-transaction-id",
    "amount": 25.00,
    "currency": "USD",
    "paymentGatewayAccountName": "stripeProduction",
    "card": {
      "cardNumber": "@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO",
      "cardHolderName": "Jane Smith",
      "expirationMonth": 12,
      "expirationYear": 2027
    }
  }'

response = requests.put(
    'https://api.orchestrasolutions.com/PaymentGateway/refund',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'refTransId': 'original-transaction-id',
        'amount': 25.00,
        'currency': 'USD',
        'paymentGatewayAccountName': 'stripeProduction',
        'card': {
            'cardNumber': '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
            'cardHolderName': 'Jane Smith',
            'expirationMonth': 12,
            'expirationYear': 2027
        }
    }
)

Refund API Reference

Complete parameter reference for refund requests

The token replaces the card number only. You must still send cardHolderName, expirationMonth, and expirationYear. When tokenizing through the library, these are returned alongside the token in tokenAndMaskedCardModel.bankCard.

Gateway-native tokens (gatewayToken from Gateway Tokenization) are not accepted on refund or void. The userToken field exists only on charge and authorize. Use a String Token (@ prefix) here instead.

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: 'stripeProduction',
    card: {
      cardNumber: '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027
    }
  })
});

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 Void and Refund above.

Void

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: 'stripeProduction',
    card: {
      cardNumber: '4111111111111111',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});

curl -X DELETE https://api.orchestrasolutions.com/PaymentGateway/void \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "refTransId": "original-transaction-id",
    "amount": 50.00,
    "currency": "USD",
    "paymentGatewayAccountName": "stripeProduction",
    "card": {
      "cardNumber": "4111111111111111",
      "cardHolderName": "Jane Smith",
      "expirationMonth": 12,
      "expirationYear": 2027,
      "cvv": "123"
    }
  }'

import requests

response = requests.delete(
    'https://api.orchestrasolutions.com/PaymentGateway/void',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'refTransId': 'original-transaction-id',
        'amount': 50.00,
        'currency': 'USD',
        'paymentGatewayAccountName': 'stripeProduction',
        'card': {
            'cardNumber': '4111111111111111',
            'cardHolderName': 'Jane Smith',
            'expirationMonth': 12,
            'expirationYear': 2027,
            'cvv': '123'
        }
    }
)

Refund

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: 'stripeProduction',
    card: {
      cardNumber: '4111111111111111',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});

curl -X PUT https://api.orchestrasolutions.com/PaymentGateway/refund \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "refTransId": "original-transaction-id",
    "amount": 25.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/refund',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'refTransId': 'original-transaction-id',
        'amount': 25.00,
        'currency': 'USD',
        'paymentGatewayAccountName': 'stripeProduction',
        'card': {
            'cardNumber': '4111111111111111',
            'cardHolderName': 'Jane Smith',
            'expirationMonth': 12,
            'expirationYear': 2027,
            'cvv': '123'
        }
    }
)

Authorize & Capture

Full transaction lifecycle

Transaction Status

Check refund status

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

When to Use Each

Void

Void API Reference

Refund

Refund API Reference

Partial Refunds

Sending Raw Card Details (Non-Standard)

Void

Refund

Authorize & Capture

Transaction Status

​When to Use Each

​Void

Void API Reference

​Refund

Refund API Reference

​Partial Refunds

​Sending Raw Card Details (Non-Standard)

​Void

​Refund

​Related

Authorize & Capture

Transaction Status

When to Use Each

Void

Refund

Partial Refunds

Sending Raw Card Details (Non-Standard)

Void

Refund

Related