Overview

A Refund's details can be viewed with the Pay1st gateway after a payment has been processed. This API is a GET request that returns the details of the refund given a refund reference.

Pre Requisites

An access token needs to be generated in order to use this API (see Authentication - Generate Access Token)

API Description

HTTP Headers

Header Name	Description
AccessToken	This is the `Access Token` field returned from the Authentication - Generate Access Token response. This should be in the format `Bearer <AccessToken>`
Content-Type	`application/vnd.carry1st.payments.refund+json`

URL Format

https://<payments_url>/api/pay1st/transactions/refunds?transactionReference={transactionReference}&partnerRefundReference={partnerRefundReference}

List Refund URL Parameters

These are the query parameters that can be passed from the Pay1st Partner to the Pay1st Gateway.

Param	Format	Mandatory	Description
transactionReference	String	N	The transaction reference.
partnerRefundReference	String	N	The partner refund reference value provided in the refund request.

Success Response

Valid HTTP Success Status Codes:

HTTP Status Code	Name	Description
200	Success	This indicates that the request has been successful.
400	Bad Request	An invalid `AccessToken`might be used

HTTP Response Body:

{
  "refunds": [
    {
      "refundReference": "P-67890-R",
      "transactionReference": "C-12345-P",
      "partnerRefundReference": "P-12345",
      "amount": 50.00,
      "currencyCode": "ZAR",
      "status": "SUCCESSFUL",
      "handlingType": "PSP_API",
      "fullRefund": false,
      "reason": "Customer requested refund",
      "createdDate": "2026-03-10T12:00:00Z",
      "lastModifiedDate": "2026-03-10T12:05:00Z"
    }
  ]
}

HTTP Response Fields

The response will contain a list of refunds Objects. These are described in the table below

Name	Type	Description
refundReference	String	The unique identifier of the Refund Request
transactionReference	String	The original transaction's identifier that was passed in the request
partnerRefundReference	String	Partner's unique refund identifier if passed in refund request
amount	Number	The amount that will be refunded
currencyCode	String	The currency code of the refund
status	String	Indicates the status of the refund. Possible values are `PENDING, PROCESSING, SUCCESSFUL, FAILED, REJECTED`
handlingType	String	This indicates how the refund will be handled. Possible values are `PSP_API, PSP_MANUAL, NO_REFUND`
fullRefund	String	Indicates whether this is a full refund
reason	String	A detailed description of the refund
createdDate	String	The timestamp that the refund was created
lastModifiedDate	String	The timestamp that the refund was last updated

Error Response

See Handling Error Codes for more details on handling error responses.