Overview

A Chargeback Request can 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 a list of chargeback transactions as a JSON response.

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.chargeback+json`

URL Format

https://<payments_url>/api/pay1st/transactions/chargebacks?<queryparameters>

Chargeback Status Query Parameters

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

Param	Format	Mandatory	Description
transactionReference	String	N	The Pay1st Identifier that was obtained in the response of Create Payment Request
chargebackReference	Decimal	N	The chargeback reference.
status	String	N	The chargeback status. Possible values are `OPEN, UNDER_REVIEW, WON, LOST, CANCELLED`
dateFrom	String	N	The start date to filter for chargeback statuses
dateTo	String	N	The end date to filter for chargeback statuses
page	String	N	Used for pagination to indicate the page number
size	String	N	Used for pagination to indicate the size of the page

### Example JSON Request

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

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	An invalid `AccessToken`might be used

HTTP Response Body:

{
  "chargebacks": [
    {
      "chargebackReference": "CB-11111",
      "transactionReference": "C-12345-T",
      "chargebackAmount": 100.00,
      "currencyCode": "ZAR",
      "reasonCode": "FRAUDULENT",
      "reasonDescription": "Fraudulent transaction",
      "status": "OPEN",
      "responseDeadline": "2026-03-11T04:00:00Z",
      "createdDate": "2026-03-10T12:00:00Z",
      "lastModifiedDate": "2026-03-10T12:00:00Z"
    }
  ],
  "currentPage": 1,
  "totalPages": 1,
  "totalResults": 1,
  "hasNext": false
}

HTTP Response Fields

Name	Type	Description
chargebacks	List[Chargeback]	The unique identifier of the Refund Request
currentPage	Number	The current page of this list
totalPages	Number	The total number of pages for the result
totalResults	Number	The total number of results
hasNext	Boolean	Indicates whether the current page is the last page

Chargeback Response

Name	Type	Description
chargebackReference	String	A unique identifier that identifies the chargeback transaction
transactionReference	String	The original Pay1st transaction reference for the request
chargebackAmount	Number	The amount of the chargeback
currencyCode	String	The currency code used for the chargeback
reasonCode	String	Indicates the reason code for the chargeback. Possible values are `FRAUDULENT, DUPLICATE, PRODUCT_NOT_RECEIVED, PRODUCT_UNACCEPTABLE, CREDIT_NOT_PROCESSED, SUBSCRIPTION_CANCELLED, AUTHORIZATION_ERROR, GENERAL, OTHER`
reasonDescription	String	Describes the chargeback in more detail
status	String	The status of the chargeback. Valid statuses are `OPEN, UNDER_REVIEW, WON, LOST, CANCELLED`
responseDeadline	String	The date at which to respond for the chargeback
createdDate	String	The date when the chargeback has been created
lastModifiedDate	String	The date when the chargeback has been last modified

Error Response

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