Refunds

Refunds let you reverse a completed deposit back toward the customer who paid it. There is a single integration surface — one endpoint to start a refund, one endpoint to check its status, and one endpoint to list refund history.

How refunds work

You always call the same endpoint with the transaction_reference of the completed deposit you want to reverse. The API resolves that transaction, applies the eligibility rules for its currency, and processes the refund.

Important — use transaction_reference, not transaction_id

Pass the deposit's transaction_reference — the human-readable reference returned when the collection completed (for example TRGSS12345 or ORDER-12345). This applies to all refund types, including GBP and EUR collection refunds.

Do not pass the internal transaction_id (UUID). That identifier appears in transaction list/detail responses and refund history for your records, but it is not accepted by POST /client/payment/refund. Sending a UUID in transaction_reference returns 404 (payment not found).

There are two rule sets, summarized below:

Standard checkout refundsFull collection refunds
Applies toCard-funded checkout depositsCompleted GBP or EUR collection deposits (any funding method)
Refund amountPartial or full — any amount up to the remaining refundable balanceFull amount only — must exactly equal the net amount originally credited
Multiple refunds per depositYes, until the deposit is fully refundedNo — one accepted attempt per deposit
Retry after a failed attemptYesOnly if the previous attempt failed before being accepted; once accepted, it cannot be retried or resubmitted
Original deposit status requiredCOMPLETEDCOMPLETED

If your deposit doesn't meet the rules for its currency, POST /client/payment/refund returns 400 with a message describing why (see Common eligibility errors).

Note: Refunds are not currently pushed to you via webhook. Poll Check refund status or Refund history to track progress until you see a terminal status (COMPLETED, FAILED, or CANCELLED).

Initiate refund

POST /client/payment/refund

Request body

json
{  "transaction_reference": "TRGSS12345",  "refund_amount": "90.00",  "refund_reason": "Customer requested cancellation",  "business_code": "optional-business-code"}
ParameterTypeRequiredDescription
transaction_referencestringYesThe completed deposit's transaction_reference (not its internal transaction_id UUID). Use the same value returned at collection time or shown as transaction_reference / original_transaction_reference in transaction and refund records
refund_amountstringYesDecimal string. For GBP/EUR collections this must exactly equal the net amount credited for the deposit; for standard checkout refunds it can be partial, up to the remaining refundable balance
refund_reasonstringYesFree-text reason, stored for your records and shown in refund history
business_codestringNoOnly needed if your account manages multiple businesses and you must specify which business's linked credentials to use for this refund

Success response

json
{  "message": "refund initiated successfully",  "transaction_reference": "ORDER-12345",  "status": "PENDING",  "refund_reference": "RF-928183",  "refund_amount": "90.00"}
FieldDescription
transaction_referenceEchoes the original deposit's reference
statusAlways PENDING immediately after a successful call — the refund is now being processed
refund_referenceUnique identifier for this refund. Use it with Check refund status
refund_amountThe amount accepted for refund

Note: A successful 200 response means the refund request was accepted, not that funds have moved yet. Always confirm completion via Check refund status before treating the refund as final. A small number of responses may include additional informational fields beyond the ones documented here — only rely on the fields listed in this page.

Common eligibility errors

All eligibility failures return 400 with a message in error:

json
{ "error": "refund ineligible: deposit is not completed" }
ScenarioExample message
transaction_id UUID sent instead of transaction_reference404 — payment not found
Deposit not yet completeddeposit is not completed
Refund already in progress or completed for this deposita refund has already been initiated for this collection
Deposit already fully refundedthis deposit has already been fully reversed
Partial amount sent for a GBP/EUR collectionrefund_amount must equal the full collected amount (...); partial refunds are not supported for GBP/EUR collections
refund_amount exceeds what's left to refund (standard checkout)refund_amount exceeds remaining refundable balance for this deposit
Deposit type/funding method doesn't support refundsrefunds are only available for checkout card collections / refunds are only available for card-funded checkout deposits

Other possible responses:

StatusMeaning
404No transaction found for transaction_reference, or it does not belong to your authenticated user
400Missing/invalid request fields, or an eligibility failure (see table above)
502The refund could not be accepted upstream — safe to retry the request later
500Unexpected server error — safe to retry

Check refund status

GET /client/payment/refund/status/:refund_reference

Use the refund_reference returned from Initiate refund.

Optional query parameter business_code if you manage multiple businesses.

Response

json
{  "message": "refund status retrieved",  "refund_reference": "RF-928183",  "refund_status": "PROCESSING",  "original_transaction_reference": "ORDER-12345",  "refund_amount": "90.00"}
FieldDescription
refund_statusOne of the refund status values
original_transaction_referenceThe transaction_reference of the deposit being refunded
refund_amountThe amount requested for this refund

Refund history

GET /client/payment/refund/history

Lists refunds for the authenticated user, most recent first.

Query parameterRequiredDescription
pageNoPage number, defaults to 1
sizeNoPage size, defaults to 20, capped at 100
start_dateNoFilter refunds created on/after this date (YYYY-MM-DD)
end_dateNoFilter refunds created on/before this date (YYYY-MM-DD)

Response

json
{  "message": "refund history retrieved",  "refunds": [    {      "id": "5c6c1e2a-1c3a-4b8a-9c4e-6a7b8c9d0e1f",      "transaction_id": "6196e335-a293-4c9e-b292-1e1ab219ea20",      "refund_reference": "RF-928183",      "refund_status": "COMPLETED",      "original_transaction_reference": "ORDER-12345",      "refund_amount": "90.00",      "refund_reason": "Customer requested cancellation",      "business_code": "",      "internal_reversal_status": "posted",      "created_at": "2026-08-01T10:30:00Z",      "updated_at": "2026-08-01T10:35:00Z"    }  ],  "total": 1,  "page": 1,  "size": 20,  "total_pages": 1}
FieldDescription
idInternal refund identifier
transaction_idInternal UUID of the deposit being refunded — for your records only; use original_transaction_reference (not this field) when calling Initiate refund
refund_referenceSame identifier used with Check refund status
refund_statusOne of the refund status values
internal_reversal_statuspending until funds have been moved back internally, posted once the reversal has been applied to the customer's wallet balance
created_at / updated_atRFC3339 timestamps (UTC)

Refund status values

StatusMeaning
PENDINGRefund has been accepted and is queued
PROCESSINGRefund is being processed
COMPLETEDRefund has completed — funds have been returned
FAILEDRefund could not be completed
CANCELLEDRefund was cancelled

Notes for integrators

  1. Use transaction_reference, not transaction_id. The initiate-refund body field is transaction_reference. The transaction_id UUID in list/history responses is informational only — do not send it when starting a refund.
  2. One deposit, one refund reference at a time. You can't start a new refund for a deposit while a previous refund on it is still pending, processing, or already completed.
  3. Amounts are decimal strings. Always send refund_amount as a string (e.g. "90.00")
  4. No webhook for refunds today. Poll Check refund status or Refund history until you observe a terminal status.
  5. Deposit status after a full refund. Once a deposit has been refunded in full, it will show as reversed if you look it up via your transaction/deposit records.
  6. GBP/EUR collections are full-refund only. These currencies do not support partial refund.

Related pages