Void or Refund All Payments in a Group

POST /rest/merchants/{MID}/groups/{GroupID}/void-or-refund

Description: Attempts to void or refund every settled payment in the specified group in a single operation. Payments that have not been processed are automatically skipped. Returns per-payment results alongside aggregate counts.

Void vs. Refund: The system determines whether to void (same-day reversal) or refund (post-settlement credit) based on the current settlement state of each payment. You do not need to specify which operation to use.

Irreversible: Void and refund operations cannot be undone. Confirm the group ID and merchant ID before calling this endpoint in production.

Path Parameters

MID (required)

Type: string — 8 or 11 digits

Example: 32350000576

GroupID (required)

Type: string (UUID)

Example: 01234567-abcd-1234-9876-abcdef123456

No request body is required for this endpoint.

Example Request

POST /rest/merchants/32350000576/groups/01234567-abcd-1234-9876-abcdef123456/void-or-refund
Authorization: Bearer <token>

Responses

200 OK

The operation completed. Check results for per-payment outcomes — a 200 status does not mean every payment succeeded.

{
  "paymentGroupId": "01234567-abcd-1234-9876-abcdef123456",
  "processedCount": 3,
  "successfulCount": 2,
  "failedCount": 0,
  "skippedCount": 1,
  "results": [
    {
      "paymentId": "aaaaaaaa-1111-2222-3333-444444444444",
      "paymentGroupId": "01234567-abcd-1234-9876-abcdef123456",
      "success": true,
      "transactionResponse": {
        "retref": 987654321098,
        "respcode": "00",
        "respstat": "A",
        "resptext": "Approval",
        "amount": 125.00,
        "lastFour": "4242",
        "accountType": "VISA"
      }
    },
    {
      "paymentId": "bbbbbbbb-5555-6666-7777-888888888888",
      "paymentGroupId": "01234567-abcd-1234-9876-abcdef123456",
      "success": true,
      "transactionResponse": {
        "retref": 987654321099,
        "respcode": "00",
        "respstat": "A",
        "resptext": "Approval",
        "amount": 75.50
      }
    },
    {
      "paymentId": "cccccccc-9999-8888-7777-666666666666",
      "paymentGroupId": "01234567-abcd-1234-9876-abcdef123456",
      "success": false,
      "errorMessage": "Payment was not settled and cannot be voided or refunded."
    }
  ]
}

Error Responses

Status	Meaning
400	Invalid path parameter format.
401	Missing or expired bearer token.
404	Group not found or does not belong to this merchant.
500	Unexpected server error.

Response Fields

Field	Type	Description
`paymentGroupId`	string (UUID)	The group that was processed.
`processedCount`	integer	Number of payments that were attempted (excludes skipped).
`successfulCount`	integer	Number of successful void/refund operations.
`failedCount`	integer	Number of void/refund operations that failed at the gateway.
`skippedCount`	integer	Payments skipped because they were not eligible (unprocessed, already voided, etc.).
`results`	array	Per-payment result objects.
`results[].success`	boolean	Whether this individual operation succeeded.
`results[].errorMessage`	string	Error detail if `success` is false.
`results[].transactionResponse`	object	Gateway response for the operation.