Refunds & Void

You can refund all or part of a successful payment. Refund and void use the same endpoint; the system chooses the method (void vs. refund), you do not.

Start a refund

POST /v1/payments/{paymentCode}/refunds
Authorization: Bearer ptk_live_…
Content-Type: application/json

Request body:

{
  "amount": 40000,
  "partnerRefundCode": "REF-2026-8841-1"
}

Field	Required	Description
amount	No	Amount to refund (kuruş). If omitted, the entire remaining balance is refunded.
partnerRefundCode	Yes	A unique refund code generated on your side (idempotency).

Response (201 Created):

{
  "refundId": "ref_5Tg8p",
  "method": "void",
  "status": "approved"
}

Field	Description
refundId	The refund’s identifier; used in the status query.
method	The method the system chose: void (cancel) or credit (refund). Returned transparently.
status	approved, pending (result not yet final), or declined (the bank rejected it synchronously).

void / credit: the system chooses

Whether a refund request becomes a void (cancel) or a credit (refund) is decided by Lydia Gate based on the timing of the sale. The partner cannot make this choice; it only sees the outcome transparently in the method field. The rule is:

Sale timing	Requested amount	Method	Result
Same day	Full (entire remaining balance)	void	The transaction is cancelled before it reaches the bank’s books.
Same day	Partial	(none)	Not yet possible → refund_not_yet_available. Retry after day-end, processed as credit.
A past day	Full or partial	credit	The refund is processed.

In practice: a same-day partial refund returns refund_not_yet_available; retrying after day-end processes it as a credit. A same-day full refund becomes a void immediately.

No credit refunds on direct-collection terminals

Some terminals operate in direct-collection (direct) mode; payments on these terminals cannot be refunded as a credit — only a same-day full void is available. A credit refund request on these terminals returns 422 direct_refund_not_allowed.

How a refund affects the payment

An approved refund updates the payment’s status:

Method and scope	New payment status
void (same-day full cancel)	voided
credit partial (cumulative refunds < sale)	partially_refunded
credit full, or cumulative refunds = sale	refunded

The status changes only when the refund is approved (status: "approved"); a pending refund does not change the payment status yet.

pending: inconclusive refund

A refund returning status: "pending" is not yet final; its status is updated once the result is resolved (approved or declined). Do not treat an inconclusive refund as failed on your own. The uncertainty usually comes from a delayed bank response; the refund stays pending until the result is finalized, and this resolution can be delayed. Track the final status via GET /v1/payments/{paymentCode}/refunds/{refundId}. If a refund stays pending for a long time, contact support.

The refund_in_progress (409) error has two distinct triggers:

1. Single-flight: you sent a new refund request while a pending refund still exists for the same payment. Wait until the previous refund is finalized.
2. Duplicate refund code (idempotency): you resent a partnerRefundCode you had already used for a non-declined refund. The request is not processed; query the status of that refund via GET /v1/payments/{paymentCode}/refunds/{refundId} (the code is already recorded).

Query refund status

GET /v1/payments/{paymentCode}/refunds/{refundId}
Authorization: Bearer ptk_live_…

Response (200 OK):

{
  "refundId": "ref_5Tg8p",
  "method": "void",
  "status": "approved",
  "amount": 40000,
  "procReturnCode": "00",
  "authCode": "123456",
  "errMsg": null,
  "bankReference": "240615091203",
  "createdAt": "2026-06-15T09:12:00Z",
  "updatedAt": "2026-06-15T09:12:03Z"
}

Field	Description
refundId	The refund’s identifier.
method	The method the system chose (void / credit).
status	Refund status (pending / approved / declined).
amount	Refund amount (kuruş).
procReturnCode	Bank result code for this refund (if any; otherwise null).
authCode	Bank authorization code for this refund (if any; otherwise null).
errMsg	Bank error message for this refund (if any; otherwise null).
bankReference	Bank reference for this refund (if any; otherwise null).
createdAt / updatedAt	Timestamps (UTC).

Bank result fields on the refund detail

The procReturnCode, authCode, errMsg, and bankReference fields returned by this endpoint may carry bank result codes for your own refund (for reconciliation/reporting; all may be null). These fields appear only on the refund detail query, not on the POST refund response. Even so, raw card/3D data (PAN/CVV/md/cavv) is never returned.

Use this endpoint to learn a refund’s final outcome; track the resolution of a pending refund here. You can also see the payment’s current refund breakdown (total/remaining) via GET /v1/payments.

Related error codes

Code	Reason
payment_not_refundable	The payment is not in a refundable state.
refund_amount_exceeds_remaining	The requested amount exceeds the remaining refundable balance.
refund_not_yet_available	Same-day partial refund; available after day-end.
refund_in_progress	A pending refund already exists for this payment (single-flight), or this partnerRefundCode was already used (duplicate code).
direct_refund_not_allowed	The payment was made on a direct-collection (direct) terminal; a credit refund is not possible, only a same-day full void is available.

Full list: Error Codes.