☰

Navigation:

Issue a marketplace refund

How to issue a marketplace refund.

Overview

When using the Marketplace schema, the process to perform refunds can differ, depending on your use case.

There are two main use cases:

Pre-requisites

Before getting started, please take a look at the below pre-requisites to ensure you are ready to begin transfers:

Allow transfers

Firstly, please ensure that you enable transfers between accounts in the Viva banking app (for the platform account only). To do this:

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

  2. Go to Settings > API Access

  3. Ensure the Allow transfers between accounts checkbox is checked, as shown below:

    Allow transfers between accounts

Find transactionId

The transactionID refers to the individual transaction (i.e. prior transfer) which relates to the transfer being performed.

This can be found within the response of the original transfer, or within the Account Transaction Created webhook.

Process

The marketplace refund process varies depending on your use case:

Use Case A - manual transfers (online customer refunds)

Manual refunds should be used for cases in which manual transfers were performed (Use Case A and Use Case C).

The process for online manual refunds is as follows:

1. To perform a refund to an end customer, you will need to use the Cancel transaction API call, specifying the transactionId of the original customer payment [see example request]

2. To retrieve funds back from the seller accounts to the Platform account, you will need to use the Create a transfer reversal API call, as needed, specifying the transferId of the original transfer you are ‘reversing’. In cases of multiple-seller payments, a separate transfer reversal will be needed for each seller transfer [see example request]

For the refund to be executed successfully, the platform account must have adequate balance

Use Case B - automatic transfers (online customer refunds)

Automatic refunds should be used for cases in which automatic transfers were performed (Use Case B).

The process for automatic refunds is as follows:

1. To perform a refund to an end customer, you will need to use the Cancel marketplace transaction API call, specifying the transactionId of the original payment [see example request]

2. The related transfer reversal from the seller back to the Platform account can be triggered automatically by using the reverseTransfers parameter in the above ‘Cancel transaction’ API call, with the option to return the commission to the seller with the refundPlatformFee parameter

For the refund to be executed successfully, the platform account must have adequate balance

Use Case C - manual transfers (in-store customer refunds)

Manual refunds should be used for cases in which manual transfers were performed (Use Case A and Use Case C).

The process for in-store manual refunds is as follows:

1. The refund/cancellation is performed within the POS device or app (either standalone, via Android inter-app integration, via iOS inter-app integration or via Cloud Terminal API integration)

2. To retrieve funds back from the seller accounts to the Platform account, you will need to use the Create a transfer reversal API call, as needed, specifying the transferId of the original transfer you are ‘reversing’. In cases of multiple-seller payments, a separate transfer reversal will be needed for each seller transfer [see example request]

For the refund to be executed successfully, the platform account must have adequate balance

Example requests

Cancel transaction

Environment Method URL
Production DELETE https://www.vivapayments.com/api/transactions/{transaction_id}
Demo DELETE https://demo.vivapayments.com/api/transactions/{transaction_id} 
curl --location -g --request DELETE 'https://demo.vivapayments.com/api/transactions/{id}?amount={amount}' \
--header 'Authorization: Basic TWVyY2hhbnRfSUQ6QVBJX0tleQ=='

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/transactions/%7Bid%7D?amount=%7Bamount%7D',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic TWVyY2hhbnRfSUQ6QVBJX0tleQ=='
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response
{
  "Emv": null,
  "Amount": 2,
  "StatusId": "F",
  "CurrencyCode": 826,
  "TransactionId": "bd5390a9-5870-4d8d-abea-7f5a94f9cecc",
  "ReferenceNumber": 909196,
  "AuthorizationId": null,
  "RetrievalReferenceNumber": 122409743701,
  "ThreeDSecureStatusId": 2,
  "ErrorCode": 0,
  "ErrorText": null,
  "TimeStamp": "2023-03-08T15:20:26.606Z",
  "CorrelationId": null,
  "EventId": 0,
  "Success": true
}

Cancel marketplace transaction

Environment Method URL
Production DELETE https://api.vivapayments.com/acquiring/v1/transactions/{transactionID}
Demo DELETE https://demo-api.vivapayments.com/acquiring/v1/transactions/{transactionID} 
curl --location -g --request DELETE 'https://demo-api.vivapayments.com/acquiring/v1/transactions/{transactionID}?amount'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/acquiring/v1/transactions/%7BtransactionID%7D?amount',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response
{
  "transactionId": "47398b8d-7933-4ed4-ba46-65171366e3df"
}

Create a transfer reversal

Environment Method URL
Production POST https://api.vivapayments.com/platforms/v1/transfers/{transferId}:reverse
Demo POST https://demo-api.vivapayments.com/platforms/v1/transfers/{transferId}:reverse 
curl --location -g --request POST 'https://demo-api.vivapayments.com/platforms/v1/transfers/{transferId}:reverse' \
--header 'Authorization: Bearer Token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 10
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/platforms/v1/transfers/%7BtransferId%7D:reverse',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "amount": 10
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer Token',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response
{
  "transferId": "fa176a3b-a7e8-4f3d-abe6-5e65626f5994",
  "executed": "2023-02-13T08:56:51.219Z"
}

Cloud Terminal API - Refund Request

Environment Method URL
Production POST https://api.vivapayments.com/ecr/v1/transactions:refund
Demo POST https://demo-api.vivapayments.com/ecr/v1/transactions:refund 
curl --location 'https://demo-api.vivapayments.com/ecr/v1/transactions:refund' \
--header 'Authorization: Bearer Bearer_Token' \
--header 'Content-Type: application/json' \
--data '{
    "sessionId": "4bdebe62-c211-4ca0-a994-b2fbea2061c5",
    "terminalId": 16000010,
    "cashRegisterId": "XDE384678UY",
    "parentSessionId": "f7287549-e93a-4d33-b936-000027d326d0",
    "amount": 1170,
    "currencyCode": 978,
    "merchantReference": null
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/ecr/v1/transactions:refund',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "sessionId": "4bdebe62-c211-4ca0-a994-b2fbea2061c5",
    "terminalId": 16000010,
    "cashRegisterId": "XDE384678UY",
    "parentSessionId": "f7287549-e93a-4d33-b936-000027d326d0",
    "amount": 1170,
    "currencyCode": 978,
    "merchantReference": null
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer Bearer_Token',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example response
{
  "Message": "Successful Response."
}

Get Support

If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!