Overview

A Refund Request can to be created with the Pay1st gateway after a payment has been processed. This API is a POST request that takes Pay1st transaction reference as input, and returns the refund details as a JSON response.

Pre Requisites

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

Request Signature

A valid signature should be generated for this request. See Gateway - Generating Signatures for a detailed description on how this should be implemented.

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`
X-SIGNATURE	This is the header that will contain the signature of the request. Refer to the Request Signing section above
X-TIMESTAMP	This is the current time in ISO-8601 format. This should be the same timestamp as the one used to generate the Signature

URL Format

POST https://<payments_url>/api/pay1st/transactions/refunds/create

List of Refund Request POST fields

These are the list of POST fields that needs to be passed from the Pay1st Partner to the Pay1st Gateway.

Param	Format	Mandatory	Description
transactionReference	String	Y	The Pay1st Identifier that was obtained in the response of Create Payment Request
partnerRefundReference	String	N	Partner's unique refund identifier.
amount	Decimal	N	The amount to pay. If amount is not provided in the request, full refund will be processed.
reason	String	N	A documented reason for initiating the Refund Request
refundWebhookUrl	String	N	The URL that will receive the refund webhooks

Example JSON Request

The following JSON Request is an example of the correct construction of a Create Payment Request:

{
  "transactionReference": "C-12345-T",
  "partnerRefundReference": "P-12345",
  "amount": 50.00,
  "reason": "Customer requested refund",
	"refundWebhookUrl": "https://7ffe-209-203-45-5.ngrok-free.app/local/webhook"
}

Success Response

Valid HTTP Success Status Codes:

HTTP Status Code	Name	Description
201	Success	This indicates that the request has been successful.
400	Bad Request	The `X-SIGNATURE`HTTP header in the request might not be matching the server. The `X-TIMESTAMP` HTTP header in the request might not be within 5 minutes of creating the Access Token. The Request Body might be invalid.

HTTP Response Body:

{
  "refundReference": "R-67890",
  "transactionReference": "C-12345-T",
  "partnerReference": "48502830697945",
  "partnerRefundReference": "P-12345",
  "amount": 50.00,
  "currencyCode": "ZAR",
  "status": "PENDING",
  "handlingType": "PSP_API",
  "fullRefund": false,
  "reason": "Customer requested refund",
  "createdDate": "2026-03-10T12:00:00Z",
  "lastModifiedDate": "2026-03-10T12:00:00Z"
}

HTTP Response Fields

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
partnerReference	String	The original transaction's partnerReference 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` `PENDING`will be returned by the API Response. The other statuses are returned by the Refund Webhook
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
createdDate	String	The date that the refund was created
lastModifiedDate	String	The date that the refund was last updated

Error Response

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