Overview

The API endpoints for the live and sandbox servers are:

Live: https://api.peachpayments.com/v1/checkout/refund
Sandbox: https://testapi.peachpayments.com/v1/checkout/refund

Perform a refund against a successful payment by referencing the unique payment ID provided in the payment status request or in the successful payment webhook.

Perform the refund by sending a POST request over HTTPS to the API endpoint. The POST request must contain the authentication parameters, the initial payment ID, the payment type (RF), refund amount, and currency.

📘
The content-type header must be application/x-www-form-urlencoded or application/json.

Parameters

Parameter	Description	Format	Condition
`authentication.entityId`	The entity for the request. By default this is the channel's ID.	AN32 `[a-f0-9]{32}`	Required
`amount`	The amount of the payment request. The dot is the decimal separator.	N10.N2 `[0-9]{1,10}`(.`[0-9]{2}`)?	Required
`paymentType`	The payment type for the request. The `RF` type is supported.	A2	Required
`currency`	The currency code of the payment request amount.	A3 `[A-Z]{3}`	Required
`id`	The unique identifier of the initial payment that is being refunded.	AN32 `[a-f0-9]{32}`	Required
`signature`	The signature for the request.	AN64 `[a-f0-9]{64}`	Required

📘
All refund requests require a signature and the API signs all responses with a signature using the secret token as the key.

Example request

curl --location 'https://testapi.peachpayments.com/v1/checkout/refund' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'amount=5' \
--data-urlencode 'authentication.entityId=8ac7a4ca7802ed8e0178176ca52222dz' \
--data-urlencode 'id=8ac7a4a284c684140184c7a8f19a553z' \
--data-urlencode 'currency=ZAR' \
--data-urlencode 'paymentType=RF' \
--data-urlencode 'signature=714187e25b25052701ad05cd28ef2be17707868197124595ab5747b3573b7e0z'

Example concatenated string: amount5.00authentication.entityId8ac7a4ca7802ed8e0178176ca52222dzcurrencyZARid8ac7a4a284c684140184c7a8f19a553zpaymentTypeRF

Example responses

{
  "id": "8ac7a49f8af08e94018af09246760e3z",
  "referencedId": "8ac7a4a284c684140184c7a8f19a553z",
  "paymentType": "RF",
  "amount": "5.00",
  "currency": "ZAR",
  "descriptor": " Checkout - All Methods 2700.8920.1608",
  "merchantTransactionId": "021023152z",
  "result": {
    "code": "000.100.110",
    "description": "Request successfully processed in 'Merchant in Integrator Test Mode'"
  },
  "resultDetails": {
    "ConnectorTxID1": "{E5516170-7BE4-4B99-91A2-A38D7E3E442Z}",
    "ConnectorTxID2": "{ADE5D9F2-7CD0-431E-BA4E-2DA4EAC67D9Z}|1757.3833.312Z",
    "AuthorisationCode": "952700",
    "AcquirerReference": "28383:04488500",
    "AcquirerResponse": "0"
  },
  "buildNumber": "1d15c0c7fcf47edcb2d03ab60a7499d6e0b2fdaz@2023-10-02 10:06:28 +0000",
  "timestamp": "2023-10-02 13:27:12+0000",
  "ndc": "8ac7a4c9791c31ee01791f27b739110z_f6f65c64bbe643858a7ed8258bab1e2z"
}

{
  "id": "9307b175ca864c7fa26fa664e55d0204",
  "paymentType": "RF",
  "result": {
    "code": "000.100.110",
    "description": "Request successfully processed in 'Merchant in Integrator Test Mode'"
  },
  "timestamp": "2023-10-03T09:43:04.337734Z",
  "amount": "5.00",
  "currency": "ZAR"
}

{
  "id": "9330a6737db943f29d58a80eeb9bda6z",
  "paymentType": "RF",
  "result": {
    "code": "100.550.701",
    "description": "amounts not matched"
  },
  "timestamp": "2023-10-02T13:33:23.152141Z",
  "amount": "1.00",
  "currency": "ZAR"
}

{
  "id": "ec6dcc1b9ac241ada0cb3da43fef73e1",
  "paymentType": "RF",
  "result": {
    "code": "700.400.200",
    "description": "cannot refund (refund volume exceeded or tx reversed or invalid workflow?)"
  },
  "timestamp": "2023-10-03T09:43:57.955323Z",
  "amount": "6.00",
  "currency": "ZAR"
}

{
  "result": {
    "code": "700.300.100",
    "description": "referenced tx can not be refunded, captured or reversed (invalid type)"
  }
}