Create a recurring payment

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

A recurring payment is a payment made automatically by the merchant, initiated by the merchant without the involvement or presence of the customer (no 3DS authentication is required), done on a regular or non-regular schedule, for a fixed or variable amount (the payments may be for different amounts over time). This requires an initial payment to be done with the involvement of the customer (3DS authentication may be required), during which the customer provides consent to the merchant to make future automatic payments (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 transaction ID of the initial payment, and provide additional information such as the amount to be charged (either the same as for the initial payment or different) 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, for any amount (either the same as for the initial payment or different), by simply creating a new transaction (recurring payment) using the transaction ID of the initial payment.

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.

Both authentication methods basic auth and OAuth2 auth are used additionally to the below API Calls.

Before you start

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 Payment Order , using the allowRecurring parameter (set to true).

Note that for this API Call, you should use the OAuth2 auth method for your authentication.

Request example

post    /checkout/v2/orders

Run in Postman

curl --location --request POST 'https://demo-api.vivapayments.com/checkout/v2/orders' \
-H 'Authorization: Bearer [access token]' \
-H 'Content-Type: application/json' \
-d '{
"amount": 100,
"allowRecurring": "true"
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/checkout/v2/orders',
  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": 100,
"allowRecurring": "true"
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjBEOEZCOEQ2RURFQ0Y1Qzk3RUY1MjdDMDYxNkJCMjMzM0FCNjVGOUZSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCJ9.eyJuYmYiOjE2MzkwNTEwOTIsImV4cCI6MTYzOTA1NDY5MiwiaXNzIjoiaHR0cHM6Ly9kZW1vLWFjY291bnRzLnZpdmFwYXltZW50cy5jb20iLCJhdWQiOlsiY29yZV9hcGkiLCJodHRwczovL2RlbW8tYWNjb3VudHMudml2YXBheW1lbnRzLmNvbS9yZXNvdXJjZXMiXSwiY2xpZW50X2lkIjoiZ2JqdXM3ZGdzZTBzcTJ0dXQ4MDdyYTN1cW8wM3Rtb2NsdnljemljYWhyYTQyLmFwcHMudml2YXBheW1lbnRzLmNvbSIsInVybjp2aXZhOnBheW1lbnRzOmNsaWVudF9wZXJzb25faWQiOiJCREY0QzZCMy1DMjZELTQwNDYtQjVERi01QzQ0M0VDMzlEMDkiLCJpYXQiOjE2MzkwNTEwOTIsInNjb3BlIjpbInVybjp2aXZhOnBheW1lbnRzOmNvcmU6YXBpOnJlZGlyZWN0Y2hlY2tvdXQiXX0.ZGNmMOJ1MAaQ5Dk0tHq6kb9LP8mmPq_NirNs2_A_WZJaI2aXbLuVdaBrsTa4PI56bs4Id2QWau49xK_1K3Dj4DGb_k5oOLVt_KwQF9luBTrHeHDCSqhjUQIUVLcNfwdon_d9noCmNbd_wJaTCrPZV--KJ1bOwh0lRuufAKfYq_n5p_6T6jaft2WUbtBXM_BvtAjQHsjT-0EILPsSvCZwYjmmAigQnmSHBpbKDvUHkXWnfjkOlrdzzl5MEsx1Bz6uYSDGVgSi9n-VGOsWS7RVmJY5hJrbFoLJmsCMCi8sVGCfJFSsjHIMJ9C1FT_kwlKRBufUOq0BvzYEvQ89p77cxA',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response example

{
    "orderCode": 8615308677872601
}

Step 2: Redirect customer to pay the payment order

Next, the customer would need to successfully complete the payment of the created payment order, and thus also provide indirectly his consent for recurring payments.

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

After the customer makes the payment on Smart Checkout, the customer is redirected back to your website. If the payment has been successful or is pending, the customer is redirected to the Success URL, otherwise (i.e. if the payment has been unsuccessful) they are redirected to your Failure URL.

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(recurring payment) against the customer, charging automatically the payment method they have used for the initial payment, without any customer interaction. To create this new payment(recurring payment), you would need to create a payment using the transaction ID of the initial payment, and provide additional information such as the amount to be charged(either the same as for the initial payment or different) and the description to appear on the receipt the customer receives.

You get the initial transaction ID as a query string parameter from the URL displayed in the browser address bar after execution of the payment(when we redirect the customer back to your website after conclusion of Step 2):

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 (recurring payment).

Request example

post    /api/transactions/{id}

Run in Postman

Note that for this API Call, you should use the basic auth method for your authentication.

curl -L -X POST 'https://demo.vivapayments.com/api/transactions/f60c357d-e940-4832-9f13-ab3e9dd7e3d4' \
-H 'Authorization: Basic OTZjYjVhMDctNDhjZS00ZDgxLTg3NmQtYTZjM2RmOGRiZDE2OkFEMmUqKA==' \
-H 'Content-Type: application/json' \
-d '{
  "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;

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