# 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.&#x20;

<figure><img src="https://1871886970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYCFtTQBLcw5O9QcwHz5%2Fuploads%2FFAFQcHn5txnOMQZPhMx9%2FCapture%20d%E2%80%99e%CC%81cran%202024-04-12%20a%CC%80%2011.40.51.png?alt=media&#x26;token=c97e4ce0-02b7-4c73-a533-57945de03af0" alt=""><figcaption><p>Viva Wallet accounts</p></figcaption></figure>

Select the Blue Account (Merchant Account), the Purple one is the ISV account.&#x20;

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

<figure><img src="https://1871886970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYCFtTQBLcw5O9QcwHz5%2Fuploads%2FtL8BxG6sq2uMsOFWZLeM%2FCapture%20d%E2%80%99e%CC%81cran%202024-04-12%20a%CC%80%2011.42.52.png?alt=media&#x26;token=052d9360-6401-4c54-9acc-a17c37fb66f3" alt=""><figcaption><p>How to find the Terminal ID</p></figcaption></figure>

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.&#x20;

{% hint style="warning" %}
Write down the Terminal ID (TID), we will need it in the next section.&#x20;
{% endhint %}

<figure><img src="https://1871886970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYCFtTQBLcw5O9QcwHz5%2Fuploads%2FBFOBH0nu1GRIA2O5yO0l%2FCapture%20d%E2%80%99e%CC%81cran%202024-04-18%20a%CC%80%2009.34.58.png?alt=media&#x26;token=e4f80c34-b070-4866-8f90-b2fbcb21a1c4" alt="" width="375"><figcaption><p>Viva Wallet Smart POS has been activated</p></figcaption></figure>

Now navigate using the sidebar to the menu  `Settings->API Access`&#x20;

<figure><img src="https://1871886970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYCFtTQBLcw5O9QcwHz5%2Fuploads%2FrMQrNNVEaOCOFAnpQaT4%2FCapture%20d%E2%80%99e%CC%81cran%202024-04-12%20a%CC%80%2012.02.39.png?alt=media&#x26;token=ec39853e-4a4e-42d4-9c0e-bbac1b270e35" alt=""><figcaption><p>How to find the Merchant ID </p></figcaption></figure>

{% hint style="warning" %}
Write down the Merchant ID, we will need it in the next section.&#x20;
{% endhint %}

## Add the terminal to My Azur&#x20;

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.&#x20;

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

<figure><img src="https://1871886970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYCFtTQBLcw5O9QcwHz5%2Fuploads%2FVRg16k01TDdAt4FoGoP6%2FCapture%20d%E2%80%99e%CC%81cran%202024-04-12%20a%CC%80%2015.35.07.png?alt=media&#x26;token=49b54dc9-0e12-4dfe-82ae-a987d21b3cff" alt=""><figcaption><p>Add a new store</p></figcaption></figure>

Let's add now a machine to our new store:&#x20;

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

<figure><img src="https://1871886970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYCFtTQBLcw5O9QcwHz5%2Fuploads%2FMHeme21BIaQrDdxpDDXf%2FCapture%20d%E2%80%99e%CC%81cran%202024-04-12%20a%CC%80%2015.42.29.png?alt=media&#x26;token=e84d2a3a-6d76-42be-a621-e2eead212bac" alt=""><figcaption><p>Add a new machine</p></figcaption></figure>

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

```bash
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&#x20;
* code:  put here the Viva Wallet Terminal ID (TID) that you got on the previous section [#activate-your-terminal-on-viva-wallet.com](#activate-your-terminal-on-viva-wallet.com "mention")
* merchant\_code: put here the Viva Wallet Merchant ID that you got on the previous section [#activate-your-terminal-on-viva-wallet.com](#activate-your-terminal-on-viva-wallet.com "mention")
* fee: you can specify a percentage fee that Sita Software will receive as percentage for each transaction, in this example 0.6%.&#x20;

<figure><img src="https://1871886970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYCFtTQBLcw5O9QcwHz5%2Fuploads%2Fg8my1XU9b0L4MoYVCfdu%2FCapture%20d%E2%80%99e%CC%81cran%202024-04-12%20a%CC%80%2015.50.27.png?alt=media&#x26;token=1585e61f-3c7b-4ef6-8e45-cc1403681121" alt=""><figcaption><p>Add a Viva Wallet payment terminal to My Azur API</p></figcaption></figure>

## Create a Payment Session

We can now create a new Payment session:&#x20;

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

&#x20;Let's break down the meaning of each fields passed  in the payload:

* type\_id = 1 means this is a SALE, see [payment-session](https://developer.myazur.app/models/payment-session "mention") 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.

<figure><img src="https://1871886970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYCFtTQBLcw5O9QcwHz5%2Fuploads%2Fs9nQCxs437DFKAF8QXkQ%2FCapture%20d%E2%80%99e%CC%81cran%202024-04-12%20a%CC%80%2016.10.59.png?alt=media&#x26;token=68a1b65a-0173-4ed4-9358-b60a695f0427" alt=""><figcaption><p>Add a Viva Wallet Payment Session</p></figcaption></figure>

Viva Wallet terminal will wait for the payment:&#x20;

<figure><img src="https://1871886970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIYCFtTQBLcw5O9QcwHz5%2Fuploads%2F1mNhlQvVgkGOQZSQyI3x%2FCapture%20d%E2%80%99e%CC%81cran%202024-04-18%20a%CC%80%2009.36.35.png?alt=media&#x26;token=198f0c45-1d23-45fb-b2df-877c38a459ff" alt="" width="375"><figcaption><p>Viva Wallet payment session initiated from My Azur API</p></figcaption></figure>

## 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:

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

As response you will get:&#x20;

```json
{
    "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](https://developer.myazur.app/models/payment-session "mention")

{% hint style="success" %}
Congratulations: you completed your first transaction with the Viva Wallet Smart POS.&#x20;
{% endhint %}