Overview

The API endpoint for the live server is https://api.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.

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 --head '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)"
    }
}