Navigation:

Issue a refund

In the event of a customer returning a purchase, you have two approaches you can take to issue them with a refund. One is through the Viva Wallet banking app and the other is through our Payment API.

Refunds via banking app

You first have to ensure that you enable refunds between accounts in the Viva Wallet banking app. To do this:

Log in to Viva Wallet, demo or live , and select the required account.
From your dashboard go to Settings > API Access.
Select the Allow refunds checkbox as shown below:

The new setting is saved automatically.

Full refund before clearance

Clearance is normally overnight. If you want to do a refund on the same day as the payment you have to cancel the full amount. There is no option to issue partial refunds before funds have cleared.

To cancel a payment:

Log in to Viva Wallet, demo or live , and select the required account.
From your dashboard go to Sales > Sales Transactions.
Find the payment you wish to refund and click on the Cancel button:

Full or partial refund after clearance

Once clearance has taken place and the money is there in your account you can issue both partial and full refunds. The same approach is taken in each case:

Log in to Viva Wallet, demo or live , and select the required account.
From your dashboard go to Sales > Sales Transactions.
Find the payment you wish to refund and click on the Refund button:

The Refund Transaction dialog box is displayed:
Do one of the following:
- Full refund
  Leave the Amount to be refunded field populated with the full amount.
- Partial refund
  Enter an amount smaller than the total in the Amount to be refunded field.
Optional: Enter a meaningful description in the Merchant Reference field.
Click on the OK button.
A confirmation message is displayed:

A new entry is displayed in the transaction list as follows depending on the refund type:

Full refund

Partial refund
You will note that in the case of a partial refund, the Refund button is still available. This is because, if required, you can perform multiple partial refunds until the full amount is paid back.

Refunds via API

For refunds via the API, you also have to make sure you enable refunds between accounts in the Viva Wallet banking app as outlined under Refunds via banking app.

API refunds can be done via a simple Cancel transaction API call (including the amount) using basic auth.

You can issue full refunds immediately via this method and partial refunds once funds have cleared.

Once clearance has taken place and the money is there in your account you can issue both partial and full refunds. The same approach is taken in each case.

If you do not specify the sourceCode parameter within the query, the refund will automatically go to the “Default” payment source. If a particular payment source is required simply append the details to the query as shown below.

Example request

get /api/transactions/[transactionId]/?amount=XXX&sourceCode=XXX

Environment	URL
Production	https://www.vivapayments.com/api/transactions/{transactionId}/?amount={Amount}&sourceCode={SourceCode}
Demo	https://demo.vivapayments.com/api/transactions/{transactionId}/?amount={Amount}&sourceCode={SourceCode}

curl -L -X DELETE '[Environment URL]'
-H 'Authorization: Basic [Base64-encoded Merchant ID and API key]'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '[Environment URL]',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic [Base64-encoded Merchant ID and API key (escrow account)]'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response (successful)

A successful refund is identified by “statusId”:”F” (finished or finalised) in the response as shown in the example below.

{
    "Emv": null,
    "Amount": 100.00,
    "StatusId": "F",
    "RedirectUrl": null,
    "CurrencyCode": "826",
    "TransactionId": "1289e200-6891-4739-afe5-5c13e839545b",
    "ReferenceNumber": 839335,
    "AuthorizationId": "839335",
    "RetrievalReferenceNumber": "109110839335",
    "Loyalty": null,
    "ThreeDSecureStatusId": 2,
    "ErrorCode": 0,
    "ErrorText": null,
    "TimeStamp": "2021-04-01T13:48:23.5665277+03:00",
    "CorrelationId": null,
    "EventId": 0,
    "Success": true
}

An unsuccessful refund is identified by “statusId”:”E” (error) in the response as shown in the example below. This happens if:

Refund amount exceeds payment amount
“ErrorCode”:400
“ErrorText”:"PaymentsInvalidAmountForVoid"
“EventId”:2056
Transaction ID is invalid
“ErrorCode”:404
“ErrorText”:" Transaction [transaction ID] not found"
“EventId”:0
Payment has already been refunded
“ErrorCode”:403
“ErrorText”:"PaymentsNonReversibleTransaction: Request to reverse transaction aborted"
“EventId”:2055
Zero amount
“ErrorCode”:400
“ErrorText”:"Negative or zero amount in reversal, transaction cf6de03c-48a5-4786-80bd-0abb0c5f277c"
“EventId”:1
Partial refund for non-cleared transaction
“ErrorCode”:400
“ErrorText”:"PaymentsInvalidAmountForVoid"
“EventId”:2056

Example response (unsuccessful)

{
    "Emv": null,
    "Amount": null,
    "StatusId": "E",
    "RedirectUrl": null,
    "CurrencyCode": null,
    "TransactionId": null,
    "ReferenceNumber": null,
    "AuthorizationId": null,
    "RetrievalReferenceNumber": null,
    "Loyalty": null,
    "ThreeDSecureStatusId": null,
    "ErrorCode": 400,
    "ErrorText": "PaymentsInvalidAmountForVoid",
    "TimeStamp": "2021-07-20T11:30:00.5522532+03:00",
    "CorrelationId": null,
    "EventId": 2056,
    "Success": false
}

Further information

Check out the following tutorials for more details about some of the above topics:

Get Support

If you have any questions about our solutions, or questions about how to integrate with our solutions, please refer to our Get Support page.