Overview

All refunds for a payment can be listed with the Pay1st gateway. This API is a GET request that returns every refund of one transaction, given the transaction's transactionReference or the partnerReference you sent when creating the payment. Use it to check the status of your refunds, for example before retrying a refund request.

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

GET https://<payments_url>/api/pay1st/transactions/refunds?transactionReference={transactionReference}
GET https://<payments_url>/api/pay1st/transactions/refunds?partnerReference={partnerReference}

List Refund URL Parameters

Send one of these query parameters. If both are sent, transactionReference is used.

Param	Format	Mandatory	Description
transactionReference	String	One of the two	The Pay1st transaction reference of the payment
partnerReference	String	One of the two	The `partnerReference` you sent when creating the payment

Success Response

Valid HTTP Status Codes:

HTTP Status Code	Name	Description
200	Success	The transaction was found. `refunds` lists its refunds, and is empty if it has none
400	Bad Request	Neither query parameter was sent, or the transaction belongs to another partner (error `4202`)
404	Not Found	No transaction was found for the reference (error `4201`)

HTTP Response Body:

{
  "refunds": [
    {
      "refundReference": "C-7MV6T02M8O88UCRCBYW-R",
      "transactionReference": "C-CA5CGGMV7QQG1HUY05Z-P",
      "partnerReference": "48502830697945",
      "partnerRefundReference": "refund-7f3c2a91",
      "amount": 50.00,
      "currencyCode": "NGN",
      "status": "SUCCESSFUL",
      "handlingType": "PSP_API",
      "fullRefund": false,
      "reason": "Customer requested refund",
      "createdDate": "2026-Mar-10 12:00:00",
      "lastModifiedDate": "2026-Mar-10 12:05:00"
    }
  ]
}

HTTP Response Fields

The response contains a list of refunds objects, described in the table below.

Name	Type	Description
refundReference	String	The unique identifier of the refund
transactionReference	String	The original Pay1st transaction reference
partnerReference	String	The `partnerReference` of the original payment
partnerRefundReference	String	Your refund identifier from the refund request. Left out if you did not send one
amount	Number	The amount that will be refunded
currencyCode	String	The currency code of the refund
status	String	The current status of the refund: `PENDING`, `PROCESSING`, `SUCCESSFUL`, `FAILED` or `REJECTED`
handlingType	String	How the refund is handled: `PSP_API` (refunded automatically through the payment provider) or `PSP_MANUAL` (processed manually by Carry1st)
fullRefund	Boolean	`true` if this refund is for the full amount paid
reason	String	The reason passed in the refund request
createdDate	String	The date and time the refund was created, in UTC, in the format `yyyy-MMM-dd HH:mm:ss` (e.g. `2026-Mar-10 12:00:00`)
lastModifiedDate	String	The date and time the refund was last updated, in UTC, in the format `yyyy-MMM-dd HH:mm:ss`

Error Response

Error Code	HTTP Status	Description
4201	404	No transaction was found for the reference
4202	400	The transaction does not belong to your account

See Handling Error Codes for the general error codes and how to handle error responses.