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.

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

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.

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

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"
}'

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"
}'

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%.

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.

Viva Wallet terminal will wait for the payment:

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