Create a new refund for a completed payment.

Run GET /refunds/query/:id first. It tells you if the payment is refundable, how much is available, and which method to use:

PAYMENT_SOURCE – refund back to the original payment method (no bank details needed)

BANK_PAYOUT – refund via EFT payout (bank details required)

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

Endpoint

POST /refunds/:id

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

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).
`Content-Type`	`application/json`	✓

Path parameter

Name	In	Type	Req	Description
`{{pf_payment_id}}`	path	string	✓	`pf_payment_id` from ITN (unique PayFast transaction ID).

Refund Request Parameters

Parameter	Type & Length	Location	Required	Description
`id`	`string`	Path	✅ Yes	The `pf_payment_id` – unique transaction ID on Payfast.
`merchant-id`	`integer`, 8 characters	Header	✅ Yes	Merchant ID assigned by Payfast.
`version`	`string`	Header	✅ Yes	Payfast API version (e.g., `v1`).
`timestamp`	`ISO-8601 datetime`	Header	✅ Yes	Current timestamp in format `YYYY-MM-DDTHH:MM:SS[+HH:MM]`.
`signature`	`string`	Header	✅ Yes	MD5 hash of alphabetized header and body variables + passphrase. All characters must be lowercase.
`amount`	`integer` (in cents)	Body	✅ Yes	Refund amount in ZAR cents. Supports partial and full refunds.
`reason`	`string`, 3–255 characters	Body	✅ Yes	Reason for the refund.
`notify_merchant`	`boolean`, 1 character	Body	❌ Optional	Notify merchant of refund: `1 = true`, `0 = false`. Default is `0`.
`notify_buyer`	`boolean`, 1 character	Body	✅ Yes	Notify buyer of refund: `1 = true`, `0 = false`.

Bank Payout Only Parameters

Parameter	Type & Length	Location	Required	Description
`acc_holder` / `bank_account_holder`	`string`, max 255 characters	Body	✅ Yes	Name of the bank account holder.
`bank_name`	`string`, max 255 characters	Body	✅ Yes	Name of the bank. Available via the refund query endpoint.
`bank_branch_code`	`integer`, max 6 characters	Body	✅ Yes	Bank branch code.
`bank_account_number`	`integer`, max 12 characters	Body	✅ Yes	Bank account number.
`acc_type` / `bank_account_type`	`string`, 5–10 characters	Body	✅ Yes	Type of account: `current` or `savings`.

Would you like me to generate a downloadable Markdown file for this table so you can drop it straight into ReadMe?

Choose the body based on the query result

If refund_* .method = PAYMENT_SOURCE (no bank fields required)

curl -X POST "https://api.payfast.co.za/refunds/{{pf_payment_id}}" \
  -H "merchant-id: {{merchant_id}}" \
  -H "version: v1" \
  -H "timestamp: {{timestamp}}" \
  -H "signature: {{signature}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1000",
    "notify_buyer": 1,
    "notify_merchant": false,
    "reason": "Product out of stock"
  }'

If refund_* .method = BANK_PAYOUT (use a bank from bank_names list returned by Query)

curl -X POST "https://api.payfast.co.za/refunds/{{pf_payment_id}}" \
  -H "merchant-id: {{merchant_id}}" \
  -H "version: v1" \
  -H "timestamp: {{timestamp}}" \
  -H "signature: {{signature}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1000",
    "notify_buyer": 1,
    "notify_merchant": false,
    "reason": "Product out of stock",
    "bank_account_holder": "Test Buyer",
    "bank_name": "FNB",
    "bank_branch_code": "111111",
    "bank_account_number": "100000000000",
    "bank_account_type": "current"
  }'

Sandbox note: Some environments don’t complete BANK_PAYOUT flows. You can still set up and validate request formation (headers, signature, schema). Use the bank_names from your Query refund response and clearly label the request as non-settling in Postman.

Success response (example)

{
  "code": 200,
  "status": "success",
  "data": {
    "response": true,
    "message": "Success"
  }
}

Troubleshooting & guardrails

Refundability first: GET /refunds/query/{{pf_payment_id}} must show status: "REFUNDABLE" and sufficient amount_available_for_refund.
Method mismatch: If you submit a PAYMENT_SOURCE body when BANK_PAYOUT is required (or vice-versa), expect a validation error.
Amounts: Send cents. A “1000” body equals ZAR 10.00.
Id source: {{pf_payment_id}} is the ITN pf_payment_id, not the dashboard “paymentId”.
Idempotency: Avoid duplicate refunds—check your response and consider storing the refund token/receipt you get back.