Viva Wallet

In this section, we will see how to use My Azur API to make a payment through a Viva Wallet terminal. This tutorial is aimed at Point of Sales developers who want to quickly integrate a Viva Wallet terminal with their software.

Prerequisities:

• You created a My Azur account and registered your company on My Azur platform;

• Your company profile has been verified by Sita Software;

• You have a verified account on vivawallet.com;

• You have a physical Smart POS Viva Wallet terminal (Android based).

Activate your terminal on Viva Wallet.com

Go to https://www.vivawallet.com/ and login with your Viva Wallet account.

Viva Wallet accounts

Select the Blue Account (Merchant Account), the Purple one is the ISV account.

Now navigate using the sidebar to the menu Sales -> Physical Payments -> Card Terminals

How to find the Terminal ID

Now click the green button New Card Terminal on the top right. On the physical terminal launch the Viva Wallet app and click "Sign-in with activation code", the app will display a code that you'll put into the new card terminal form. After confirmation your new terminal will appear in the list above. The mobile app is now ready to start a new payment session.

Write down the Terminal ID (TID), we will need it in the next section.

Viva Wallet Smart POS has been activated

Now navigate using the sidebar to the menu Settings->API Access

How to find the Merchant ID

Write down the Merchant ID, we will need it in the next section.

Add the terminal to My Azur

In My Azur, each Company can have a set of Stores, and for each Store, one or more Machines can be defined. Each Machine will be associated with one or more Payment Terminals.

Let's start by adding a Store to our Company. In this tutorial we assume our company id = 13.

curl --location '{api_base_url}/stores' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Firebase Token>' \
--data '{
    "company_id" : 13,
    "name" : "My Store"
}'

Add a new store

Let's add now a machine to our new store:

curl --location '{api_base_url}/stores/3/machines' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Firebase Access Token>' \
--data '{
    "name": "My Machine"
}'

Add a new machine

We now have everything we need to register the Viva Wallet Payment terminal to My Azur:

curl --location '{api_base_url}/machines/3/payment_terminals' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Firebase Access Token> ' \ 
--data '{
    "payment_terminal_type_id": 1, 
    "name" : "Viva Wallet Android Tablet 1",
    "code" : "1600000",
    "merchant_code" : "7164123-842a-4b0e-456f-2makNskl",
    "fee" : "0.6"
}'

Let's break down the meaning of each fields passed in the payload:

• payment_terminal_type_id = 1 indicate this is a Viva Wallet terminal

• code: put here the Viva Wallet Terminal ID (TID) that you got on the previous section Activate your terminal on Viva Wallet.com

• merchant_code: put here the Viva Wallet Merchant ID that you got on the previous section Activate your terminal on Viva Wallet.com

• fee: you can specify a percentage fee that Sita Software will receive as percentage for each transaction, in this example 0.6%.

Add a Viva Wallet payment terminal to My Azur API

Create a Payment Session

We can now create a new Payment session:

curl --location '{api_base_url}/payment_terminals/2/payment_sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Firebase Access Token> 
--data '{
    "type_id" : 1,
    "merchant_reference" : "DOC1234",
    "amount" : "0.10"
}'

Let's break down the meaning of each fields passed in the payload:

• type_id = 1 means this is a SALE, see Payment Session for more details about this field;

• merchant_reference: this can be used to pass a reference, for example the internal document number used by your Point of Sale system;

• amount: transaction amount in euro.

Add a Viva Wallet Payment Session

Viva Wallet terminal will wait for the payment:

Viva Wallet payment session initiated from My Azur API

Monitor the status of the Payment Session

It is recommended to wait about 4 seconds, after that you can start polling for the status of the payment session by sending a refresh request to My Azur API, that will fetch the status from the physical terminal and returns the current status as json:

curl --location --request POST '{api_base_url}/payment_sessions
/<payment_session_id>/refresh' \
--header 'Authorization: Bearer <Firebase Access Token> 

As response you will get:

{
    "amount": "0.10",
    "application_label": null,
    "authorization_code": "367371",
    "code": "e3282ea1-287b-4b49-8510-fb33a234424",
    "created_at": "2024-04-12T14:16:41.781768",
    "created_by": "XyWjp31BVWOTUazhK5VNKusI3lv1",
    "currency_code": "978",
    "fee_amount": "0.00",
    "id": 13,
    "merchant_reference": "DOC1234",
    "order_code": "4103167443454",
    "payment_session_type_id": 1,
    "preauth": false,
    "primary_account_number_masked": "455812******5663",
    "reference_number": 334123,
    "retrieval_reference_number": 41031324234,
    "short_order_code": "4103423426",
    "status_id": 3,
    "tip_amount": "0.00",
    "transaction_code": "e0cdac35b4-d9bf-4521-adf1-45c7b6fda2e3",
    "transaction_message": "Transaction successful",
    "updated_at": "2024-04-12T14:17:08.056230",
    "updated_by": "XyWjp31BVWOTUazhK5VNKusI3lv1",
    "verification_method": "CONTACTLESS - NO CVM"
}

status_id = 3 means the transaction has been successful. To learn more about the meaning of each of the fields that you get in the response please refer to Payment Session

Congratulations: you completed your first transaction with the Viva Wallet Smart POS.