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 or pending (result not yet final).

void / credit: the system chooses

Whether a refund request becomes a void (cancel) or a credit (refund) is decided by Paytalya 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.

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 system resolves the authoritative outcome. Learn the final status via GET /v1/payments/{paymentCode}/refunds/{refundId}.

While a pending refund exists for a payment, a new refund request is rejected with refund_in_progress (single-flight rule); wait until the previous refund is finalized.

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.

Full list: Error Codes.