Create a recurring payment

Applicable only when integrating with our Smart Checkout solution.

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.

On this page:

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 new transaction using ID of initial transaction

Afterwards, you can 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.

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
}