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.
On this page:
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.
- Full refund
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
/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.