Create a recurring payment

Applicable to our Smart Checkout solution. The payment method should support recurring payments.

Recurring payments are not available with pre-authorizations or instalments.

On this page:

The below example illustrates a simple use case for creating a recurring payment.

To start with, you would need to create a payment order, using the allowRecurring parameter (set to true). Following on from that, the customer would need to successfully complete the payment of the above payment order. You can then, at a later point in time, create a new payment against the customer, charging directly the payment method they have used in the initial payment, without any customer interaction. To create this new payment, you would need to create a transaction using the ID of the initial transaction, and provide additional information such as the amount to be charged and the description to appear on the receipt the customer receives.

The key point is that, following the first successful payment, you can perform subsequent new payments, at any moment in the future, by simply creating a new transaction using the ID of the initial transaction.

Keep in mind it is your responsibility to have the customer’s consent to perform recurring payments!

The below sequence diagram summarises the recurring payment procedure.

sequenceDiagram participant Merchant app participant Merchant backend participant Viva Wallet API Merchant backend->>Viva Wallet API:Create payment order for recurring payment Viva Wallet API-->>Merchant backend:Payment order created Merchant backend-->>Merchant app:Payment order Merchant app->>Viva Wallet API:Redirect customer to payment page to pay the payment order Viva Wallet API-->>Merchant app:Confirm payment & initial transaction created loop Recurring payments Merchant backend->>Viva Wallet API:Create new transaction using ID of initial transaction Viva Wallet API-->>Merchant backend:Confirm payment & subsequent transaction created End

See also the full-length PHP code sample for creating a recurring payment.

The below example uses basic auth for authentication.

Before you start

Before you can use this API call you need to enable recurring payments in the Viva Wallet banking app:

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

  2. Go to Settings > API Access.

  3. Select the Allow recurring payments checkbox as shown below:

    Enable recurring payments
    The new setting is saved automatically.

Step 1: Create payment order for recurring payment

Initially, you would need to create a payment order, using the allowRecurring parameter (set to true).

Request example

curl -L -X POST 'https://demo.vivapayments.com/api/orders' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic OTZjYjVhMDctNDhjZS00ZDgxLTg3NmQtYTZjM2RmOGRiZDE2OkFEMmUqKA==' \
--data-raw '{
"amount": 100,
"allowRecurring": "true"
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/orders',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
"amount": 100,
"allowRecurring": "true"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic OTZjYjVhMDctNDhjZS00ZDgxLTg3NmQtYTZjM2RmOGRiZDE2OkFEMmUqKA=='
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Run in Postman

Response example

{
    "OrderCode": 9863454843479513,
    "ErrorCode": 0,
    "ErrorText": null,
    "TimeStamp": "2021-03-29T17:09:08.4347951+03:00",
    "CorrelationId": null,
    "EventId": 0,
    "Success": true
}

Step 2: Redirect customer to pay the payment order

Next, the customer would need to successfully complete the payment of the created payment order.

Redirect customer to the below URL replacing [OrderCode] with the order code from Step 1:

https://demo.vivapayments.com/web/checkout?ref=[OrderCode]

Payment page example

Payment page of the above URL:

Recurring payment step 2

Step 3: Create a new payment from the initial payment

This can be done in one of two ways:

Even if one of the subsequent payments fails (e.g. if the third payment fails), you can retry at any time, and you can continue to make subsequent payments going forward (i.e. you can make a fourth, fifth and so on payment).

Via the API

You can create a new transaction against the customer, charging directly the payment method they have used in the initial payment, without any customer interaction. To create this new payment, you would need to create a transaction using the ID of the initial transaction, and provide additional information such as the amount to be charged and the description to appear on the receipt the customer receives.

You get the initial transaction ID from the URL displayed in the browser address bar after execution of the payment:

Browser address bar

In the below request you can see the initial transaction ID as a path parameter. The response then returns an additional transaction ID for the new transaction.

Request example

curl -L -X POST 'https://demo.vivapayments.com/api/transactions/f60c357d-e940-4832-9f13-ab3e9dd7e3d4' \
-H 'Authorization: Basic OTZjYjVhMDctNDhjZS00ZDgxLTg3NmQtYTZjM2RmOGRiZDE2OkFEMmUqKA==' \
-H 'Content-Type: application/json' \
--data-raw '{
  "amount": 100,
  "customerTrns": "Short description of items/services purchased to display to your customer"
}'\'''

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/transactions/f60c357d-e940-4832-9f13-ab3e9dd7e3d4',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "amount": 100,
  "customerTrns": "Short description of items/services purchased to display to your customer"
}\'',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic OTZjYjVhMDctNDhjZS00ZDgxLTg3NmQtYTZjM2RmOGRiZDE2OkFEMmUqKA==',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Run in Postman

Response example

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

{
    "Emv": null,
    "Amount": 1.00,
    "StatusId": "F",
    "RedirectUrl": null,
    "CurrencyCode": "826",
    "TransactionId": "14c59e93-f8e4-4f5c-8a63-60ae8f8807d1",
    "ReferenceNumber": 838982,
    "AuthorizationId": "838982",
    "RetrievalReferenceNumber": "109012838982",
    "Loyalty": null,
    "ThreeDSecureStatusId": 2,
    "ErrorCode": 0,
    "ErrorText": null,
    "TimeStamp": "2021-03-31T15:52:27.2029634+03:00",
    "CorrelationId": null,
    "EventId": 0,
    "Success": true
}

Via the banking app

To create a new payment:

  1. Once you have received payment, it will show under Sales > Sales transactions in your Viva Wallet account.

  2. Simply click on the Repeat button against the payment:

    Sales transaction