You can reverse a pre-authorisation transaction that has not yet been captured. When you reverse a pre-authorisation, the gateway sends an authorisation reversal request to the card issuer to release the funds held for authorisation.

📘
Merchant transaction ID
To ensure you can track the whole transaction flow, we recommend that you use the merchant transaction ID to associate the pre-authorisation and the reversal. For example, using the same ID with a prefix or suffix for each transaction type.

Reversal request

To reverse a pre-authorisation, you will need its payment id from the pre-authorisation request made with the COPYandPAY API or SERVER-TO-SERVER API.

To reverse the full amount, you do not need to send the amount or currency. You may also perform a partial reversal if your acquirer supports it. For a partial reversal, you must send the amount and currency in your request.

To perform a reversal, send a POST request with the RVpayment type over HTTPS to the /payments/{id} endpoint.

Here is the format of the cURL request to reverse a pre-authorisation. Replace the {preauthorisationId} with the value of the id from the pre-authorisation request. Replace the {channelId} and the {auth_token} with your values.

curl https://test.oppwa.com/v1/payments/{preauthorisationId} \
-d "entityId={channelId}" \
-d "paymentType=RV" \
-d "testMode=EXTERNAL" \
-d "merchantTransactionId=P166" \
-H "Authorization: Bearer {auth_token}"

Reversal flow example

For example, here is the first part of the JSON response to a previous successful pre-authorisation request.

{
  "id":"8ac7a4a09136ba280191375f8bae0775",
  "processingEntityId":"{channelId}",
  "paymentType":"PA",
  "paymentBrand":"MASTER",
  "amount":"500.00",
  "currency":"EUR",
  "descriptor":"1454.0556.1631 ECOMChannel",
  "merchantTransactionId":"P165",
  "result":{
    "cvvResponse":"U",
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
  },
...

The pre-authorisation payment id is the first attribute in the response. You should add it as a parameter to the payments endpoint as shown in the example here.

curl https://test.oppwa.com/v1/payments/8ac7a4a09136ba280191375f8bae0775 \
-d "entityId={channelId}" \
-d "paymentType=RV" \
-d "testMode=EXTERNAL" \
-d "merchantTransactionId=P166" \
-H "Authorization: Bearer {auth_token}"

Response example

Here is an example of the JSON response to a successful cURL request to reverse a pre-authorisation.

{
  "id": "8ac7a49f9136ad8801913764d36f3fae",
  "referencedId": "8ac7a4a09136ba280191375f8bae0775",
  "paymentType": "RV",
  "amount": "500.00",
  "currency": "EUR",
  "descriptor": "8049.4738.1023 ECOMChannel",
  "merchantTransactionId": "P166",
  "result": {
    "code": "000.100.112",
    "description": "Request successfully processed in 'Merchant in Connector Test Mode'"
  },
  "resultDetails": {
    "ExtendedDescription": "Approved",
    "clearingInstituteName": "SecureTrading Omnipay Demo",
    "ConnectorTxID1": "893134||false|||0809|| ||RECURRING|80||false|false|false|812|",
    "ConnectorTxID3": "422201893134|00|||1||0809134720|||||||||||||Berlin|",
    "connectorId": "422201893134",
    "ConnectorTxID2": "566519|",
    "AcquirerResponse": "00",
    "reconciliationId": "8049.4738.1023",
    "merchantAccountId": "8ac7a4c890fc748b0190fe70998c0248",
    "SchemeResponseCode": "00"
  },
  "customer": {
    "merchantCustomerId": "CUST12"
  },
  "buildNumber": "174903ec91870d5654938dd40f55da3b35036b23@2024-08-08 12:50:27 +0000",
  "timestamp": "2024-08-09 13:47:20+0000",
  "ndc": "8ac7a4c890fc748b0190fe6ad56b0241_e0fd918ea7cd4a108228970ba98209af",
  "source": "OPP",
  "paymentMethod": "CC",
  "shortId": "8049.4738.1023"
}

For full details of how to interpret the payment response, see Transaction results.

For the gateway documentation of the Backoffice API, see Gateway Backoffice API documentation.

Test in the gateway playground

You can test a reversal transaction in the gateway playground at Gateway Backoffice refund payment using test data as follows.

entityId={channelId}
paymentType=RV
testMode=EXTERNAL
merchantTransactionId=P166

You can also perform these operations in the CardCorp Hub UI. See Capture or reverse a preauthorisation.