Void

Version: 3.0.0

Prerequisite: Void only works on transactions that are authorized but not yet fully captured. If the payment has already been captured, use Refund instead. Void must also be enabled on your MID (allowVoid).

When and Why to Use Void

Use Void to cancel an authorization before funds are settled:

Customer cancels before shipping.
Fraud or suspicious activity detected before capture.
Duplicate authorization created by mistake.
You will not capture and want to release the card hold.

Void vs Refund:

Void — Cancels an authorization before capture. No money moves.
Refund — Returns money after capture.

You cannot void a captured transaction.

Endpoint

Void, Capture, and Refund share the same Manage Payment endpoint — only action changes.

Method	URL
POST	`https://api.payorc.com/orders/v1/transaction`

Please use the test credentials for sandbox testing.

Headers

Field	Type	Required	Description
`merchant-key`	String	Yes	Your merchant API key
`merchant-secret`	String	Yes	Your merchant API secret
`Content-Type`	String	Yes	Must be `application/json`

Request Body

The request body is flat (not nested under data).

Field	Type	Required	Description
`action`	String	Yes	Must be `VOID`
`transaction_id`	String	Yes	PayOrc transaction ID to void
`amount`	Object	Yes	Amount object
`amount.currencyCode`	String	Yes	ISO currency code (e.g. `AED`)
`amount.value`	Number	Yes	Amount to void
`reason`	String	No	Merchant notes

Code Examples

Example 1 — Void cancelled order

curl --location 'https://api.payorc.com/orders/v1/transaction' \
--header 'merchant-key: {merchant-key}' \
--header 'merchant-secret: {merchant-secret}' \
--header 'Content-Type: application/json' \
--data '{
    "action": "VOID",
    "transaction_id": "1000010118",
    "amount": {
        "currencyCode": "AED",
        "value": 150.00
    },
    "reason": "Customer cancelled order before shipment"
}'

Example 2 — Node.js

const axios = require('axios');

const config = {
  method: 'post',
  url: 'https://api.payorc.com/orders/v1/transaction',
  headers: {
    'merchant-key': '{merchant-key}',
    'merchant-secret': '{merchant-secret}',
    'Content-Type': 'application/json'
  },
  data: {
    action: 'VOID',
    transaction_id: '1000010118',
    amount: {
      currencyCode: 'AED',
      value: 200.00
    },
    reason: 'Order cancelled by customer'
  }
};

axios(config)
  .then(response => console.log(JSON.stringify(response.data)))
  .catch(error => console.log(error.response?.data || error));

Example 3 — Python

import requests
import json

url = 'https://api.payorc.com/orders/v1/transaction'

payload = {
    "action": "VOID",
    "transaction_id": "1000010118",
    "amount": {
        "currencyCode": "AED",
        "value": 1.00
    },
    "reason": "Cleaning up test authorization"
}

headers = {
    'merchant-key': '{merchant-key}',
    'merchant-secret': '{merchant-secret}',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=2))

Response — Success (200)

{
    "data": {
        "status": "VOID",
        "m_order_id": "ORD-2024-001",
        "p_order_id": 1000010228,
        "transaction_id": 1000010223,
        "amount": "150.00",
        "currency": "AED",
        "date": "04/08/2023"
    },
    "message": "Transaction successfully void.",
    "status": "success",
    "code": "00"
}

Capture, Void, and Refund share the same data shape: status, m_order_id, p_order_id, transaction_id, amount, currency, date.

Response — Error

{
    "message": "Transaction can't be void, already voided or not in state of to be void",
    "status": "fail",
    "code": "E0044"
}

Void vs Refund — Decision Guide

Aspect	Void	Refund
When to use	Authorization not yet captured	Payment already captured
Money movement	Releases the hold	Returns money to customer
MID requirement	`allowVoid` enabled	`allowRefunds` enabled
Typical use case	Cancel / fraud before capture	Return after capture

Void

On this page