Get the available refund balance and a history of refund-related transactions for a payment.

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

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

Endpoint

GET /refunds/{{pf_payment_id}}

{{pf_payment_id}} — pf_payment_id (from the ITN for the original payment)

Authentication & headers

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

Path parameter

Name	In	Type	Req	Description
`id`	path	string	✓	The ITN `pf_payment_id` for the original payment.

Response

Content-Type: application/json

Example

{
  "code": 200,
  "status": "success",
  "data": {
    "response": {
      "available_balance": 6800,
      "transactions": [
        { "amount": 9800,  "date": "2020-05-14 12:11:05", "type": "Funds Received" },
        { "amount": "-1000","date": "2020-05-14 14:59:59", "type": "Funds Received (Refund)" },
        { "amount": "-2000","date": "2020-05-15 09:59:59", "type": "Funds Received (Refund)" }
      ]
    },
    "message": "success"
  }
}

Field reference

Field	Type	Description
`available_balance`	integer	Minor units (cents) remaining that can still be refunded for this payment.
`transactions[]`	array	Chronological list of original receipt and refund movements.
└ `amount`	integer or string	Movement in cents. Positive for funds received; negative for refunds (some environments return negatives as strings like `"-1000"` — coerce to a number).
└ `date`	string	Timestamp (`YYYY-MM-DD HH:mm:ss`).
└ `type`	string	E.g., `Funds Received`, `Funds Received (Refund)`.

cURL example

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

Notes & gotchas

Amounts are in cents. For display, divide by 100 (ZAR).
Negative lines = refunds. Subtract from available_balance.
Type mix: Some responses send amount as a string when negative; always parse to a number before math.
Right identifier: If you get “not found,” double-check you’re using the ITN pf_payment_id for {{pf_payment_id}}.