Reverse a transaction

The Distributor may need to reverse an already executed transaction due to technical reasons (e.g. network connectivity).

The following original/reversal transaction types are supported:

Original Transaction Type	Reversal Transaction Type
CustomerToMerchantTransfer	CustomerToMerchantTransferReversal
MerchantToCustomerTransfer	MerchantToCustomerTransferReversal
PassthroughDeposit	PassthroughDepositReversal
PassthroughWithdrawal	PassthroughWithdrawalReversal

note

The new transaction has an automatically calculated (based on the original transaction) type ending with suffix Reversal. Additionally, the reversal is always a wallet to wallet transfer, i.e. the funds are only transferred back between the involved wallets (without generating triggering a customer deposit/withdrawal transaction with a QR Code).

The diagram below illustrates the basic flow of a refund:

Steps:

1. The Distributor System calls the corresponding Zastrpay API, and the latter creates and executes the reversal transaction.

The following API call generates a new reversal transaction¹:

http

PUT https://host.com/transaction-service/v1/transactions/{transactionId}/reversals/{reversalTransactionId}
Content-Type: application/json
x-request-id: $requestId
x-api-key: $apiKey
x-triggered-by-shop-id: 5d4d122c-889d-4033-b9c1-58b3a661923a
x-triggered-by-shop-external-reference: Aaa-Bbb-Ccc-123

{
    "description": "Some description",
    "externalReference": "ABC12345"
}

curl

curl -0 -v -k -X PUT https://host.com/transaction-service/v1/transactions/d9dbd4d0-6654-41a3-bc12-dab6963d8011/reversals/da98759f-8dd7-49b4-9281-6ac5ba913147 \
   -H 'Content-Type: application/json; charset=utf-8' \
   -H "x-request-id: $requestId" \
   -H "x-api-key: $apiKey" \
   -H "x-triggered-by-shop-id: 5d4d122c-889d-4033-b9c1-58b3a661923a" \
   -H "x-triggered-by-shop-external-reference: Aaa-Bbb-Ccc-123" \   
   --data-binary @- << EOF
{
    "description": "Some description",
    "externalReference": "ABC12345"
}
EOF

Original Transaction Id (in the path)

d9dbd4d0-6654-41a3-bc12-dab6963d8011 is the original transactionId of an existing transaction, triggered previously by the same Distributor, see Create Transaction from Intent for more information.

Reversal Transaction Id (in the path)

da98759f-8dd7-49b4-9281-6ac5ba913147 is the reversalTransactionId and must be a newly clientside-generated UUID v4

x-triggered-by-shop headers

To identify the source of the API call, the following headers are used:

• x-triggered-by-shop-id - a UUID/GUID generated by Zastrpay upon initial shop registration
• x-triggered-by-shop-external-reference – An alphanumeric reference (including dot, hyphen and space, up to 48 characters long) which should be unique within all shops of a distributor Exactly one of the above headers be provided.

Business Rules

The following restrictions apply:

1. Only full reversals are supported (amount equal to the one of the original transaction)
2. The state of the original transaction must be Completed
3. There should be no other successful reversal for the same transaction (there can be several unsuccessful reversals)
4. Reversals should be executed on the same business day (CET) as the original transaction

Zastrpay Backend will create a new reversal transaction referencing the original transaction, and answer with the following response:

200 OK
Location: v1/transactions/da98759f-8dd7-49b4-9281-6ac5ba913147

{
  "id": "da98759f-8dd7-49b4-9281-6ac5ba913147",
  "type": "CustomerToMerchantTransferReversal",
  "amount": 100,
  "currency": "EUR",
  "customerId": "111abc22-33de-4444-5555-111111111111",
  "state": "Completed",
  "status": "Succeeded",
  "createdOn": "2019-01-31T11:50:59Z",
  "distributorId": "222abc22-33de-4444-5555-222222222222",
  "description": "Some description",
  "externalReference": "ABC12345",
  "referenceTransactionId": "d9dbd4d0-6654-41a3-bc12-dab6963d8011"
}

note

Note that the new transaction has a type CustomerToMerchantTransferReversal, id da98759f-8dd7-49b4-9281-6ac5ba913147 and referenceTransactionId attribute equal to d9dbd4d0-6654-41a3-bc12-dab6963d8011 which is the original transaction id.

See Creates a new reversal transaction API Reference for more information.

Footnotes

1. and does not change the original transaction ↩