APIs for APM provisioning

Information about integrating Alternative Payment Methods (APMs) via API.

• Overview
• Authentication
• Environments
• Integration flow diagrams
  • Use case: In-store or online (desktop) customer with APM app
  • Use case: Online (mobile) customer with APM app
• Integration flow walk-through
  • APM app functionality
  • APM Host functionality
  • Step: “Initiate Payment”
  • Step: “Notify Payment”
  • Step: “Validate Payment”
• Get Support

Overview

Viva offers APIs to enable Alternative Payment Method (APM) providers to integrate with our solutions, so that our merchants can offer these alternative payment methods to their customers.

In particular, the below APIs allow the various APMs to be offered as payment options to customers, both for in-store payments (through our Tap on Phone app ) and online payments (through our Smart Checkout solution) across all European countries that Viva operates in.

Authentication

The API calls below use Basic Auth authentication.

Environments

The demo environment has a base URL of https://demo.vivapayments.com/ and for the live environment it’s https://www.vivapayments.com/.

Integration flow diagrams

The below sequence diagrams outline two use cases with regards to the use of an APM app for in-store payments (through our Tap on Phone app) or online payments (through our Smart Checkout solution).

The first sequence diagram refers to the use case when a customer uses an APM app on their phone to pay either in-store, or while shopping online using a desktop computer.

• In-store: the customer pays by using their APM app on their phone to scan the QR presented by our Tap on Phone app.
• Online (desktop): the customer pays by using their APM app on their phone to scan the QR presented by our Smart Checkout solution on the desktop computer.

The second sequence diagram refers to the use case when a customer uses an APM app on their phone to pay while shopping online using their phone.

• Online (mobile): the customer pays by using their APM app on their phone, which is invoked by a link provided by our Smart Checkout solution to their phone.

Use case: In-store or online (desktop) customer with APM app

Use case: Online (mobile) customer with APM app

Integration flow walk-through

1. Initially, the customer selects the specific APM to pay with, whether shopping in-store (via our Tap on Phone app) or online (via our Smart Checkout solution).
2. In case the customer is shopping in-store or online using a desktop computer, the customer is presented with a QR, which they need to scan with their APM app on their phone.
3. Then, Viva initiates a payment with the APM provider (APM Host), who in turn requests a payment approval by the customer by providing a link to invoke the APM app of the customer; the link is forwarded to the customer by Viva.
4. The customer approves the payment using the APM app on their phone, which was invoked by the link provided by the APM Host via Viva, and then the APM Host notifies Viva of the payment (Viva validates also the payment).

APM app functionality

1. The APM app should be able to scan the QR presented by Viva, and be able to render the URL linked to the QR.
2. The APM app should also be able to accept the link forwarded to it by Viva; that is, the link generated by APM Host to invoke the APM app.
3. In case the customer is shopping online using their phone, the customer is then redirected to a Viva payment conclusion page.

APM Host functionality

1. The APM Host should be able to receive an “initiate payment” request by Viva, and then send back an “initiate payment” response, according to the below specifications.
2. The APM Host should also be able to send a “notify payment” message to Viva, according to the below specifications.
3. The APM Host should finally be able to receive a “validate payment” request by Viva, and then send back a “validate payment” response, according to the below specifications.

Step: “Initiate Payment”

1. Viva sends appropriate information to APM Host to initiate a payment for a specific merchant for a specific currency and amount.
2. APM Host responds with a transaction ID and a URL to invoke APM app (deep link).

Initiate Payment Request Example

{
"vwMerchantId": "b1a3067c-321b-4ec6-bc9d-1778aef2a19d", // id of the merchant for Viva
"apmMerchantId": "21192b18-78cc-4643-b8ae-e796318dbb38", // id of the merchant for APM provider
"vwTransactionId": "66165eae-b19d-4f01-bbcc-d48404c75bc3", // id of the transaction for Viva
"currency": "826", // indicates GBP
"amount": 200, // indicates £2.00
"vwRedirectUrl": "https://...",	// the URL to return the customer to after the successful payment with APM app
"vwNotificationUrl": "https://...",	// the URL (endpoint) to use to notify Viva about the status of the payment
"requestLang": "en-GB", // the language to be presented to the customer for the payment
"email": "customer@email.com", // the email of the customer
"fullName": "customer full name", // the full name of the customer (may be empty)
"phone": "7967813180", // the phone number of the customer (may be empty)
"customerTrns": "Short description of items/services purchased", //  to display to customer
"merchantTrns": "Short description of items/services purchased", //  to display to merchant
"timeStamp": "2021-02-25T06:34:28.5943635+02:00" // in ISO 8601 format
}

Initiate Payment Response Example

{
"vwTransactionId": "66165eae-b19d-4f01-bbcc-d48404c75bc3", // id of the transaction for Viva
"apmTransactionId": "ac1bd7a0-0485-42e6-b589-48da497236ed", // id of the transaction for APM provider
"apmRedirectUrl": "https://...", // the URL to invoke the APM app (deep link)
"timeStamp": "2021-12-24T15:21:44.3263755+02:00", // in ISO 8601 format
"success": true, // boolean; true if the initiation of the payment is successful
"errorCode": "", // empty if the initiation of the payment is successful
"errorText": "" // empty if the initiation of the payment is successful
}

Step: “Notify Payment”

1. APM Host sends appropriate information to Viva to notify about the outcome of the payment; the APM uses the vwNotificationUrl as the endpoint.
2. Viva responds with an acknowledgement.

Notify Payment Request example

{
"vwTransactionId": "66165eae-b19d-4f01-bbcc-d48404c75bc3", // id of the transaction for Viva
"apmTransactionId": "ac1bd7a0-0485-42e6-b589-48da497236ed", // id of the transaction for APM provider
"currency": "826", // indicates GBP
"amount": 200, // indicates £2.00
"status": "fail", // success or fail depending on whether the payment was successful or not
"statusCode": "Status Code", // additional details for reference purposes
"statusReason": "Status Reason", // additional details for reference purposes
"timeStamp": "2021-12-24T15:23:38.5157933+02:00" // in ISO 8601 format
}

Notify Payment Response example

{
    "vwTransactionId": "66165eae-b19d-4f01-bbcc-d48404c75bc3", // id of the transaction for Viva
    "apmTransactionId": "ac1bd7a0-0485-42e6-b589-48da497236ed", // id of the transaction for APM provider
    "timeStamp": "2021-12-24T15:23:38.5157933+02:00", // in ISO 8601 format
}

Step: “Validate Payment”

1. Viva sends appropriate information to APM Host to ask about the outcome of a payment.
2. APM Host responds with appropriate information about the outcome of the payment.

Validate Payment Request Example

{
    "vwTransactionId": "66165eae-b19d-4f01-bbcc-d48404c75bc3", // id of the transaction for Viva
    "apmTransactionId": "ac1bd7a0-0485-42e6-b589-48da497236ed", // id of the transaction for APM provider
    "timeStamp": "2021-12-24T15:23:38.5157933+02:00", // in ISO 8601 format
}

Validate Payment Response Example

{
"vwTransactionId": "66165eae-b19d-4f01-bbcc-d48404c75bc3", // id of the transaction for Viva
"apmTransactionId": "ac1bd7a0-0485-42e6-b589-48da497236ed", // id of the transaction for APM provider
"currency": "826", // indicates GBP
"amount": 200, // indicates £2.00
"status": "fail", // success or fail depending on whether the payment was successful or not
"statusCode": "Status Code", // additional details for reference purposes
"statusReason": "Status Reason", // additional details for reference purposes
"timeStamp": "2021-12-24T15:23:38.5157933+02:00" // in ISO 8601 format
}

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!