menu

Payment API

What's on this page

API Reference / Reversal

Reversal

Depending on the payment method, the following can be accomplished using a reversal:

  • The funds reserved earlier using an authorise request, can be released.
  • A previous sale can be reversed making it appear as if the sale never occurred.

The following transactions can be reversed:

  • authorise transactions
    • For the following methods: applepay, card, googlepay, klarna and terminal.
    • That have not already been captured, and are not in progress of being captured.
  • sale and capture transactions
    • For the following methods: terminal.
    • That have not already been refunded, and are not in progress of being refunded.
  • In addition, only transactions that have not already been previously reversed, and are not in progress of being reversed, can be reversed.

Reversal object

Name Description
type Fixed value: reversal
amount Echo from the Payment
currency Echo from the Payment
status Possible values: Transaction Status
merchantOrderReference Echo from the Payment
description The description of the transaction
language Echo from the Payment
method Echo from the Payment
brand Echo from the Payment
metadata Echo from the Payment
reference A unique reference for the reversal transaction
originalReference The unique reference for the payment transaction this payment is attempting to reverse.
methodTransactionId A third party transaction ID which identifies the payment transaction in external systems. If empty no such id was available or no third party was employed
created The local server datetime the reversal was created, epoch timestamp
lastUpdate The local server datetime the reversal was updated, epoch timestamp
statusFinalDate The local server datetime the reversal reached a final status, epoch timestamp
failureCode An error code indication what caused the failure. Possible values: Failure Codes
payUrl To complete the payment the customer should be redirected to this unique URL. Only valid for Terminal
returnUrl After the payment is completed (successfully or otherwise) the customer is redirected to this URL. Only valid for Terminal

Reversal request

  • Resource: /api/v1/reversal
  • Method: POST
  • Content-Type: application/json
  • Authentication: basic auth
  • Supports idempotency
  • Parameters
Name Required Description Max Length
reference Yes The unique reference of the payment to reverse 255
description No The description of the reversal. If not provided we use the original payment description 255
notificationRequests No An object which is used to request Notifications for specific events related to this capture. n/a
webhookUrl No The webhook URL invoked for transaction changes. This overrides the merchant webhook if one is present. We do not validate this url 2000
details No An object which includes method specific details. Possible values: Method Reversal Details. n/a
merchantOrderReference No A reference, maximum of 255 characters, of the order associated with this reversal. If not provided we use the merchantOrderReference of the original payment 255

Example

{
  "reference": "C1505181754007360.1",
  "description": "API Reversal Description"
}

Method Reversal Details

Terminal Reversal Details

These details are possible when reversing an authorisation or sale which was made using the method terminal. Any details included in the original authorise or sale can be overwritten with these details.

Name Required Description Max Length
cardPresent No Specify whether the customer’s card has to be present to perform the reversal. Defaults to true.
terminalId No The terminal id as assigned by CCV 50
managementSystemId No The management system id of this terminal as assigned by CCV 50
accessProtocol No The communication protocol between the terminal and access server 20
ip No The browser accessible IP of the terminal for initiating the wake up 50
port No The browser accessible port of the terminal’s socket handling HTTP calls 5
operatingEnvironment Conditional Only ATTENDED terminal reversals are supported. Meaning it is required to include ATTENDED if the operatingEnvironment of the transaction being reversed was set to SEMI_UNATTENDED. 20
merchantLanguage No The language of the merchant, used to change the language in which the intermediate page is displayed in ATTENDED operatingEnvironments. Required when operatingEnvironment is ATTENDED, not required otherwise. 3

Reversal response

Example

{
  "type" : "reversal",
  "amount" : 316.35,
  "currency" : "eur",
  "status" : "PENDING",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Reversal Description",
  "language" : "eng",
  "method" : "card",
  "metadata" : "my custom metadata",
  "reference" : "C1505181613078800.1",
  "brand" : "visa",
  "created" : 1431958387914,
  "lastUpdate" : 1431958387914,
  "statusFinalDate" : 1431958387914
}