Refund a transaction

warning

This functionality is not yet implemented. A manual workaround is currently available, in case a customer refund needs to be processed.

The Merchant may need to refund an already executed transaction, e.g. due to the customer making use of the 14-day return policy.

note

The refund may be with the same amount as the original transaction (aka full refund), or it can be with an amount lower (aka partial refund) or even higher (e.g. in case of higher shipping costs) than the one of the original transaction.

The following original/refund transaction types are supported:

Original Transaction Type	Refund Transaction Type
`CustomerToMerchantTransfer`	`MerchantToCustomerRefund`

note

The new transaction has an automatically calculated (based on the original transaction) type ending with suffix Refund. Additionally, the refund 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:

Refund

Steps:

Customer requests a refund (full or partial) in the merchant app or website. The request is stored in the merchant system, and a merchant operator is notified about it
A merchant operator approves the refund request, upon which the Merchant System calls the corresponding Zastrpay API, and the latter creates and executes the refund transaction.

A full refund can be triggered with the following API call, which generates a new refund transaction¹:

http
curl

PUT https://host.com/transaction-service/v1/transactions/{transactionId}/refunds/{refundTransactionId}
Content-Type: application/json
x-api-key: $apiKey
x-request-id: $requestId

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

curl -0 -v -k -X PUT https://host.com/transaction-service/v1/transactions/e074e5ac-ba20-4e11-b577-de233d838175/refunds/2efdea04-a29b-4c57-8910-7002ee61f53b \
   -H 'Content-Type: application/json; charset=utf-8' \
   -H "x-api-key: $apiKey" \
   -H "x-request-id: $requestId" \
   --data-binary @- << EOF
{
    "description": "Some description",
    "externalReference": "ABC12345"
}
EOF

Alternatively, the following API call can be used in case of partial refund, or refund with higher amount than the one of the original transaction:

http
curl

PUT https://host.com/transaction-service/v1/transactions/{transactionId}/refunds/{refundTransactionId}
Content-Type: application/json
x-api-key: $apiKey
x-request-id: $requestId

{
    "amount": 10,
    "currency": "EUR",
    "description": "Some description",
    "externalReference": "ABC12345"
}

curl -0 -v -k -X PUT https://host.com/transaction-service/v1/transactions/e074e5ac-ba20-4e11-b577-de233d838175/refunds/2efdea04-a29b-4c57-8910-7002ee61f53b \
   -H 'Content-Type: application/json; charset=utf-8' \
   -H "x-api-key: $apiKey" \
   -H "x-request-id: $requestId" \
   --data-binary @- << EOF
{
    "amount": 10,
    "currency": "EUR",
    "description": "Some description",
    "externalReference": "ABC12345"
}
EOF

note

e074e5ac-ba20-4e11-b577-de233d838175 is the original transactionId of an existing transaction, already known to the Merchant based on a previous webhook notification, see Handle Transaction Events for more information.

note

2efdea04-a29b-4c57-8910-7002ee61f53b is the refundTransactionId and must be a newly clientside-generated UUID v4

note

The following restrictions apply:

The state of the original transaction must be Completed

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

200 OK
Location: v1/transactions/2efdea04-a29b-4c57-8910-7002ee61f53b

{
  "id": "2efdea04-a29b-4c57-8910-7002ee61f53b",
  "type": "MerchantToCustomerRefund",
  "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": "e074e5ac-ba20-4e11-b577-de233d838175"
}

note

Note that the new transaction has a type MerchantToCustomerRefund, id 2efdea04-a29b-4c57-8910-7002ee61f53b and referenceTransactionId attribute equal to e074e5ac-ba20-4e11-b577-de233d838175 which is the original transaction id.

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

and does not change the original transaction ↩

Footnotes​

Footnotes