Use the query refund endpoint to pre-check whether a transaction is refundable and what details are required (e.g., whether you can refund back to the original payment source or must collect bank details for a payout). Run this before creating a refund.

Important: The path parameter is the pf_payment_id from the ITN callback (PayFast’s unique transaction ID), not the sandbox/dashboard paymentId.

Base URL https://api.payfast.co.za

Endpoint

GET /refunds/query/:id

{{pf_payment_id}} — pf_payment_id (unique transaction ID from ITN)

📘
You can use the Transaction History endpoints to GET the PayFast payment IDs.

Authentication & headers

Header	Type	Required	Description
`merchant-id`	integer (8 chars)	Yes	Your PayFast Merchant ID.
`version`	string	Yes	API version (e.g., `v1`).
`timestamp`	ISO-8601 datetime	Yes	`YYYY-MM-DDTHH:MM:SS[+HH:MM]`.
`signature`	string (MD5 hex)	Yes	MD5 of alphabetised submitted header/body vars + passphrase (lower-case).

Path parameter

Name	In	Type	Required	Description
`id`	path	string	Yes	The `pf_payment_id` from the ITN for the original payment.

Response

Content-Type: application/json

Example (from your test)

{
  "token": "dc4f13fa-74c3-4fc8-8654-e2504d1cd0f0",
  "funding_type": "Wallet Funds",
  "amount_original": 234500,
  "amount_available_for_refund": 234500,
  "status": "REFUNDABLE",
  "errors": [],
  "refund_full": {
    "method": "BANK_PAYOUT",
    "bank_account_holder": "",
    "bank_name": "",
    "bank_branch_code": "",
    "bank_account_number": "",
    "bank_account_type": ""
  },
  "refund_partial": {
    "method": "BANK_PAYOUT",
    "bank_account_holder": "",
    "bank_name": "",
    "bank_branch_code": "",
    "bank_account_number": "",
    "bank_account_type": ""
  },
  "bank_names": [
    { "bank_name": "ABSA", "label": "Absa" },
    { "bank_name": "STANDARD", "label": "Standard Bank" },
    { "bank_name": "FNB", "label": "FNB" },
    { "bank_name": "NEDBANK", "label": "Nedbank" },
    { "bank_name": "CAPITEC", "label": "Capitec Bank" }
    // …additional banks omitted for brevity
  ]
}

Try It

Field reference

Field	Type	Description
`token`	string	Refund token for subsequent refund operations.
`funding_type`	string	How the original transaction was funded (e.g., Debit Card, Credit Card, Wallet Funds).
`amount_original`	integer	Original purchase amount (typically minor units, e.g., cents).
`amount_available_for_refund`	integer	Remaining refundable amount (minor units).
`status`	string	One of: `REFUNDABLE`, `COMPLETED`, `NOT_AVAILABLE`.
`errors`	string[]	If `status = NOT_AVAILABLE`, human-readable reasons to show to users.
`refund_full`	object	Parameters required to process a full refund.
└── `method`	string	One of `PAYMENT_SOURCE`, `BANK_PAYOUT`, `NOT_AVAILABLE`.
`refund_partial`	object	Parameters required to process a partial refund.
└── `method`	string	One of `PAYMENT_SOURCE`, `BANK_PAYOUT`, `NOT_AVAILABLE`.
`bank_names`	array	If a bank payout is possible, list of supported banks for accurate `bank_name` selection.

How to interpret the result

status = REFUNDABLE → You can refund.
- If refund_* .method = PAYMENT_SOURCE, you can refund back to the original payment source (usually minimal extra data).
- If refund_* .method = BANK_PAYOUT, collect bank details shown in the object; use bank_names to present valid bank choices.
status = COMPLETED → Refund already completed; nothing further to do.
status = NOT_AVAILABLE → Refund isn’t allowed; surface the messages from errors[].

In your sample, status: "REFUNDABLE" and both refund_full/refund_partial show method: "BANK_PAYOUT", so you can refund, but must provide bank details when you create it.

cURL example

curl -X GET "https://api.payfast.co.za/refunds/query/{{pf_payment_id}}" \
  -H "merchant-id: {{merchant_id}}" \
  -H "version: v1" \
  -H "timestamp: {{timestamp}}" \
  -H "signature: {{signature}}"

Notes & gotchas

Use pf_payment_id from ITN for :id. Don’t pass the sandbox/dashboard paymentId—it won’t resolve here.
Amounts are commonly returned in minor units (e.g., cents). Convert for display as needed.
Always include the signed headers; signature must be lower-case MD5 of the alphabetised vars + passphrase.
For creating the refund, call POST /refunds/:id using the fields indicated by refund_full or refund_partial. (I can draft that page next.)