APIs for APM provisioning

Viva Wallet 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 Wallet operates in.

The information on this page is intended for APM providers and is not for general merchant usage.

On this page:

Authentication

The API calls below use basic auth.

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.

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.

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

%% APM + VW App, for customer = in-store or e-commerce desktop sequenceDiagram participant APM App participant VW App participant APM Host VW App ->> VW App: select APM VW App ->> APM App: present QR APM App ->> VW App: scan QR Note right of APM App: QR renders
VW App url VW App ->> APM Host: initiate payment APM Host ->> VW App: request payment approval Note left of APM Host: provide link to
invoke APM App VW App ->> APM App: request payment approval APM App ->> APM Host: approve payment APM Host ->> VW App: notify payment VW App ->> APM Host: validate payment APM Host ->> VW App: validate payment

Use case: Online (mobile) customer with APM app

%% APM + VW App, for APM App = e-commerce mobile sequenceDiagram participant APM App participant VW App participant APM Host VW App ->> VW App: select APM VW App ->> APM Host: initiate payment APM Host ->> VW App: request payment approval Note left of APM Host: provide link to
invoke APM App VW App ->> APM App: request payment approval APM App ->> APM Host: approve payment APM Host ->> VW App: notify payment VW App ->> APM Host: validate payment APM Host ->> VW App: validate payment APM Host ->> APM App: redirect payment conclusion

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 Wallet 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 Wallet.
  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 Wallet, and then the APM Host notifies Viva Wallet of the payment (Viva Wallet validates also the payment).

APM app functionality

  1. The APM app should be able to scan the QR presented by Viva Wallet, 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 Wallet; 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 Wallet payment conclusion page.

APM Host functionality

  1. The APM Host should be able to receive an “initiate payment” request by Viva Wallet, 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 Wallet, according to the below specifications.
  3. The APM Host should finally be able to receive a “validate payment” request by Viva Wallet, and then send back a “validate payment” response, according to the below specifications.

Step: “Initiate Payment”

  1. Viva Wallet 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 Wallet
"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 Wallet
"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 Wallet 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 Wallet
"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 Wallet to notify about the outcome of the payment; the APM uses the vwNotificationUrl as the endpoint.
  2. Viva Wallet responds with an acknowledgement.

Request example

{
"vwTransactionId": "66165eae-b19d-4f01-bbcc-d48404c75bc3", // id of the transaction for Viva Wallet
"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
}

Response example

{
    "vwTransactionId": "66165eae-b19d-4f01-bbcc-d48404c75bc3", // id of the transaction for Viva Wallet
    "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 Wallet 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 Wallet
    "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 Wallet
"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
}