Reversals via API
Overview
In cases where the outcome of a transaction is unclear due to a disconnection or timeout, you can perform a reversal. This allows you to attempt another transaction and avoid duplicating the amount authorized against the cardholder.
Cases where initiating a reversal is advised:
-
You receive a 504 HTTP Gateway timeout response.
-
You don’t receive a response within an expected window of time and wish to cancel the request.
Availability
Reversal is available to all merchants.
How it works
Step 1: Include the reversal ID in your initial payment request
To perform a reversal at a later stage, the initial payment request must include a unique identifier generated by you, so that Verifone can identify the payment you wish to reverse later.
Verifone accepts this unique identifier in a UUID format, as a header in your payment request with the key name: x-vfi-api-idempotencykey
Example
API Reference: https://verifone.cloud/api-catalog/verifone-ecommerce-api#tag/Ecom-Payments/operation/saleTransaction
Request Method: POST
Header: x-vfi-api-idempotencykey: a38b85b2-b835-4c37-adec-4b91c3ed0dfb
Request body
{
"entity_id": "{{entity_id}}",
"currency_code": "{{currency}}",
"amount": 1000,
"merchant_reference": "Payment 123",
"payment_provider_contract": "{{ppc}}",
"stored_credential": {
"stored_credential_type": "CHARGE",
"reference": "e03c516d-3ef2-4646-8533-de23575be882",
"processing_model_details": {
"processing_model": "UNSCHEDULED_CREDENTIAL_ON_FILE"
}
}
} Step 2: Perform a Reversal
Now, in case you were not able to retrieve the result from the transaction in step one, the x-vfi-api-idempotencykey can be used again to reverse it.
Example
API Reference: https://verifone.cloud/api-catalog/verifone-ecommerce-api#tag/Payment-Modifications/operation/reverseTransaction
Request Method: POST
URL: https://cst.test-gsc.vfims.com/oidc/api/v2/transactions/reverse
Header: x-vfi-api-idempotencykey: a38b85b2-b835-4c37-adec-4b91c3ed0dfb
Body:
N/A
Response:
{
"id": "6c6564dd-1b53-4c60-82f8-3c0cb8cc36aa",
"payment_provider_contract": "{{ppc}}",
"amount": 1000,
"merchant_reference": "Payment 123",
"status": "AUTHORIZED",
"status_reason": "Approved",
"arn": "SIMULATORN54NC6B2IGGCRH71KJDY",
"cvv_result": "0",
"details": {
"auto_capture": false
},
"reason_code": "0000",
"shopper_interaction": "ECOMMERCE",
"stan": "123456",
"threed_authentication": {
"reversal_status": "NONE",
"additional_data": {
"initiator_trace_id": "123456"
},
"balance_amount": 0
} From the transaction response, you can see that the reversal attempt was AUTHORISED, the initial payment has now been successfully canceled.
Additional Steps
Query the transaction result
Use the Read Transaction endpoint to check the initial transaction ID and observe the reversal being applied.
API Reference: https://verifone.cloud/api-catalog/verifone-ecommerce-api#tag/Transaction/operation/readTransaction
Request Method: GET
Header:
N/A
Body:
N/A
Response:
{
……..
"merchant_reference": "Payment 123",
"payment_product": "CARD",
"payment_product_type": "VISA",
"status": "CANCEL AUTHORISED",
……….
}
