Issue refunds via banking app or API

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:

  1. Log in to Viva Wallet, demo or live , and select the required account.

  2. From your dashboard go to Settings > API Access.
    Select the Allow refunds checkbox as shown below:

    Allow refunds checkbox
    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:

  1. Log in to Viva Wallet, demo or live , and select the required account.

  2. From your dashboard go to Sales > Sales Transactions.

  3. Find the payment you wish to refund and click on the Cancel button:

    Cancel sales transaction

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:

  1. Log in to Viva Wallet, demo or live , and select the required account.

  2. From your dashboard go to Sales > Sales Transactions.

  3. Find the payment you wish to refund and click on the Refund button:

    Refund sales transaction
    The Refund Transaction dialog box is displayed:

    Refund transaction dialog box

  4. 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.
  5. Optional: Enter a meaningful description in the Merchant Reference field.

  6. Click on the OK button.
    A confirmation message is displayed:

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

    Full refund
    Full refund
    Partial 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

curl -L -X DELETE 'https://demo.vivapayments.com/api/transactions/[transactionId]/?amount=10000&sourceCode=1234 \
-H 'Authorization: Basic [Base64-encoded Merchant ID and API key (escrow account)]'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/transactions/[transactionId]/?amount=10000&sourceCode=1234',
  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: