NAV Navbar
shell python kotlin java

Introduction

Welcome to the Yavin API documentation !

The API allows to easily integrate the functionalities of your Yavin X Android Terminal with an API REST or Android Intent, for instance, to initiate a payment or to print directly from your POS.

There are three levels of API integration to initiate a payment:

Perk: The terminal can use a 3G/4G SIM card to connect to the bank.

Drawback: The response is asynchronous towards a public IP.

Typical use case: Web SaaS POS.

You can also use this API to extract information for your My Yavin backoffice, for instance, to connect your accounting software.

Perk: The HTTP request is synchronous (open up to 5 minutes, corresponding to the time for the payment).

Drawback: The terminal must be connected to a local network with a fix IP (small handling in the Android settings). The local network must have a stable internet connexion.

Typical use case: Onboarded POS without web synchronization with websocket.

Perk: The POS is onboarded directly on the terminal.

Drawback: We need to program on mobile (Java/Kotlin/react native...) and the APK must be approved by the terminal constructor.

Typical use case : POS on smartphone (order taking at the table, food truck, itinerant merchants).

If you have an Android app and wish to deploy directly on the Yavin terminals, it's possible :) Contact us to make a sponsorship.

Authentication

To log in, use the code below:

import yavin

api = yavin.authorize('<yavin_secret>')
curl -XPOST "https://api.yavin.com/api/v1/transactions" --data '{"yavin_secret": "<yavin_secret>"}'

Don't forget to replace <yavin_secret> with your Yavin API key. Yavin uses API keys to restrict data and services access to the right users. You can find your API key on my.yavin.com in the API tab.

All the requests must be identified. To do so, the field "yavin_secret" must be added in the POST parameters of the request:

{"yavin_secret": "<yavin_secret>"}

Errors

The Yavin API uses the following error codes:

Code Explanation
400 Bad Request -- The request is invalid.
401 Unauthorized -- The API key is invalid.
404 Not Found -- The link doesn't exist.
405 Method Not Allowed -- You are trying to access a link with an invalid HTTP method.
500 Internal Server Error -- There is an issue with our server. Please try again later. Contact the support team if the problem persists.

Transactions

Example of a transaction :

{
    "transaction_id": "b14fbe01-fd2a-419b-9f4d-6aea4edf514b",
    "date": "2020-01-15",
    "time": "11:19:31",
    "amount": 1000,
    "currency": "EUR",
    "status": "DEBIT",
    "pan": "527345XXXXXX2315",
    "logical_number": "003",
    "scheme": "VISA"
}

The transaction object contains the following fields:

Settings Description
transaction_id Unique credential of the transaction
date Date of the transaction
time Time of the transaction
amount Amount of the transaction in cts
currency Currency of the transaction
status DEBIT = The transaction worked correctly, TNA = the transaction failed
pan Masked card number
pan_token Unique token linked to the card number to identify a client (contact us for the activation)
logical_number Rank, number to allow the merchant to identify the terminal.
serial_number Serial number of the transaction that collected the transaction.
scheme Network used to validate the transaction (CB,CBSC (contactless),VISA,MASTERCARD,CONECS...)

Extract all the transactions

from yavin import Client

yavin_client = Client('<yavin_secret>')
yavin_client.transactions.get({
    'start_date': '2019-12-12',
    'end_date': '2020-03-03',
    'limit': 2
})
print(yavin_client.transactions.data)
curl -XPOST "https://api.yavin.com/api/v1/transactions/" --data '{"yavin_secret":"<yavin_secret>"}'

The request below returns the following JSON :

{
  "meta": {
    "total": 55,
    "start": 0,
    "count": 2,
    "code": 200,
    "message": "ok"
  },
  "data": {
    "transactions": [
      {
        "transaction_id": "b14fbe01-fd2a-419b-9f4d-6aea4edf514b",
        "date": "2020-01-15",
        "time": "11:19:31",
        "amount": 1000,
        "currency": "EUR",
        "status": "DEBIT",
        "pan": "527345XXXXXX2315",
        "logical_number": "003",
        "scheme": "VISA"
      },
      {
        "transaction_id": "5fdd0db6-0038-4369-9296-9ef57ac0ef80",
        "date": "2020-01-14",
        "time": "15:43:14",
        "amount": 300,
        "currency": "EUR",
        "status": "TNA",
        "pan": "472906XXXXXX4031",
        "logical_number": "003",
        "scheme": "MASTERCARD"
      }
    ]
  }
}

GET https://api.yavin.com/api/transactions

Settings Default Description
end_date today End date of the filter.
start_date 30 days before the end_date Start date of the filter.
limit 20 Limit of the number of payment to receive with a request.

New transaction on the terminal

Example:

   curl -XPOST "https://api.yavin.com/api/v1/pos/payment/new/" --data '{"yavin_secret": "<yavin_secret>", "amount": 1000, "serial_number": "123456",       "receiptTicket": ["hello printer", "this is a", "    wonderful", "        TICKET"]'

    {"message": "ok", "uuid": "68c2b707-a1fb-4682-8e8b-2b6829b4da80"}

This API is used to iniate a payment on a Yavin X terminal connected to the internet via the HTTP REST framework. It will work from a computer, a tablet or Android, or any objects connected to the internet

POST https://api.yavin.com/api/v1/pos/payment/new/

New transaction on the terminal

Settings Default Description
amount - Amount of the transaction in cts.
serial_number - Serial number of the terminal. It can be found at the back of the terminal with the S/N acronym.
transactionType Debit Debit = classic card transaction. Reversal = payment reversal.
currency EUR Currency in which the payment will occur (available only on activation).
medium CB CB = classic card transaction. (Other methods will soon be available).
receiptTicket - cash register ticket to print at the same time as the card ticket. The format is defined by the variable 'printType'
receiptTicketJson {} receipt ticket in json format to share with the client preferred information system
printType text Type of the text to print. Values allowed are : [text, escpos] 'text' will print the raw text. 'escpos' will print the escpos encoded string
yavin_secret - Secret API key of the merchant.
cartId - id to identify the cart linked to the transaction. This field will be returned in the API callback
reference - free text
Response Description
message ok, the transaction has been received successfully
uuid unique id of the transaction

Callback after the transaction on the terminal

This API triggers if the field "callback_url" has been filled when creating a new transaction on the terminal. It allows the Yavin server to notify the calling software of the transaction status (ok/ko). POST "callback_url"

Settings Description
uuid Unique id of the transaction (the same than the on received when creating the transaction)
status Transaction status. ok/ko

Print a receipt

This will print a receipt from the targeted terminal.

Example:

   curl -XPOST "https://api.yavin.com/api/v1/pos/print/new/" --data '{
      "device_serial_number": "082226XXXX",
      "receipt_ticket": "Ticket de caisse",
      "transaction_id": "gRSeQdr30XXX"
    }'

    {"message": "ok"}
Settings Default Description
device_serial_number - Terminal serial number
receipt_ticket - Character string of the ticket to print
transaction_id - Transaction ID
yavin_secret_key - API key
Response Description
message ok
status 200

Send a push notification on the Yavin Terminal

For safety reasons (PCI PTS norms), Play Store and Google Services are not available on Android payment terminals. Therefore, Yavin re-built an instant push-notifications service with a very slow battery consumption that allows to send messages easier and safer on the terminals.

The issuing of notifications is based on the serial number that can be found at the back of the terminal with the acronym S/N. It is also mandatory to add the secret API key of the merchant to identify the request. More details here

curl -XPOST "https://api.yavin.com/api/v1/pos/notification/new/" --data '{"yavin_secret": "<yavin_secret>", "data": "{'Hello': 'world'}", "package": "com.yavin.macewindu", "class": "com.yavin.macewindu.PaymentActivity", "serial_number": "123456"}'

{"message": "ok"}

POST https://api.yavin.com/api/v1/pos/notification/new/

New notification

Settings Default Description
data - String containing the information you want to send to you application
package - Name of the package towards who you want to send your intent Android (for instance "com.yavin.macewindu")
class - Name of the class towards who you want to send your intent Android (for instance "com.yavin.macewindu.PaymentActivity")
serial_number - Serial number of the terminal. It can be found at the back of your terminal with the acronym S/N.
yavin_secret - Secret API key of the merchant
Response Description
message ok, the request was received successfully

Android Integration

The Yavin Pay Android application (package com.yavin.macewindu) can receive some intent according to the Android framework under Java and Kotlin, to trigger payments on the terminal.

Login

Before triggering payments on the Yavin Pay application, we must ensure that the merchant is identified.

To do so, there are 2 solutions: - The maintainer identifies himself on the YavinPAY application. The application offers him the possibility to identify a third-party merchant. - The merchant identifies himself with its own credentials who are the same as those of My Yavin https://my.yavin.com

New payment intent

To trigger a payment from an Android App on the terminal, just call the following Activity: com.yavin.macewindu.PaymentActivity and add the settings needed.

private fun startPaymentOnYavinPay() {
    val intent = Intent()
    intent.component = ComponentName("com.yavin.macewindu", "com.yavin.macewindu.PaymentActivity")
    intent.putExtra("vendorToken", "<vendor_token>")
    intent.putExtra("amount", "100")
    intent.putExtra("currency", "EUR")
    intent.putExtra("transactionType", "Debit")
    intent.putExtra("reference", "12345")
    intent.putExtra("client", "{\"phone\":\"0611223344\",\"email\":\"client@client.com\"}")
    val jArray = JSONArray("[\"hello printer\", \"this is a\", \"    wonderful\", \"        TICKET\"]")
    val receiptTicket = ArrayList<String>()
    for (i in 0 until jArray.length()) {
        try {
            receiptTicket.add(jArray.getString(i))
        } catch (e: JSONException) {
            e.printStackTrace()
        }
    }
    intent.putExtra("receiptTicket", receiptTicket)
    startActivityForResult(intent, 1111)
}
public void startPaymentOnYavinPay() {
    Intent intent = new Intent();
    intent.setComponent( new ComponentName("com.yavin.macewindu", "com.yavin.macewindu.PaymentActivity"));
    intent.putExtra("vendorToken", "<vendor_token>");
    intent.putExtra("amount", "100");
    intent.putExtra("currency", "EUR");
    intent.putExtra("transactionType", "Debit");
    intent.putExtra("reference", "12345");
    intent.putExtra("client", "{\"phone\":\"0611223344\",\"email\":\"client@client.com\"}");
    JSONArray jArray = null;
    try {
        jArray = new JSONArray("[\"hello printer\", \"this is a\", \"    wonderful\", \"        TICKET\"]");
    } catch (JSONException e) {
        e.printStackTrace();
    }
    ArrayList<String> receiptTicket = new ArrayList<String>();
    for (int i = 0 ; i < jArray.length(); i++) {
        try {
            receiptTicket.add(jArray.getString(i));
        } catch (JSONException e) {
            e.printStackTrace();
        }
    }
    intent.putExtra("receiptTicket", receiptTicket);
    startActivityForResult(intent, 2222);
}
Settings Default Description
amount - Amount to pay in cts.
currency EUR Currency in which the payment will be done (available with activation)
medium CB CB = Classical card transaction. (Other payment methods will be available soon)
transactionType Debit Debit = classical card transaction. Reversal = reversal of a payment
showPrepay true false Not to show any page before the payment (for instance, asking tips or donation)
showPostpay true false Not to show the print-out/send CB digital ticket page after the payment
showOnlyLastPostpay false true To show only the print-out/send CB digital ticket of the last credit card payment
client {} json that can contain the following keys: [firstName/lastName/phone/email] to pre-fill the SMS/email ticket before issuing it
cartId - id of the basket generated by the pos software
vendorToken - token of the software editor to identify him
reference - free field
forcePayment false If you want to bypass the warning screen when a payment is not yet finish.
receiptTicket [] list of strings to print the receipt ticket at the same time as the card ticket
override fun onActivityResult(requestCode: Int, resultCode: Int, intent: Intent?) {
    super.onActivityResult(requestCode, resultCode, intent)
    if (requestCode == 1111) {
        // handle post payment response from Yavin PAY
        val bundle: Bundle = intent!!.extras!!
        Log.d("clientTicket", bundle["clientTicket"].toString())
        Log.d("status", bundle["status"].toString())
        Log.d("signatureRequired", bundle["signatureRequired"].toString())
        Log.d("transactionId", bundle["transactionId"].toString())
    }
}
@Override
public void onActivityResult(int requestCode, int resultCode, Intent intent) {
    if(requestCode == 2222) {
        Bundle bundle = intent.getExtras();
        for (String key : bundle.keySet()) {
            Object value = bundle.get(key);
            Log.d("results", String.format("%s %s (%s)", key, value.toString(), value.getClass().getName()));
        }
    }
}

If you wish that your application receives the transaction results, prefer the use of the function startActivityForResult rather than startActivity. Below are the parameters YavinPay returns :

Response Description
clientTicket Client CB ticket
transactionId id of the transaction generated by Yavin
amount Amount of the requested transaction
giftAmount Additional amount (tips or donation)
totalAmount Total amount paid (totalAmount = amount + giftAmount)
status [ok/ko] Has the transaction been validated or not
signatureRequired [yes/no] notification if the signature on the CB ticket is required, for instance, for the American Express cards
cardToken Unique credential of the client card number to identify him
reference Reference filled by the software editor

API on local network

This API is used to initiate a payment on the Yavin X terminal connected to a local network via the HTTP REST framework.

Don't forget the port number 16125 in the URL. It's easy to remember:

For a simple request (with only the amount):

GET http://<IP_LOCALE>:16125/localapi/v1/payment/<MONTANT>/

For a complex request (with other fields), a POST request must be sent with 'form-data' fields filled:

POST http://<IP_LOCALE>:16125/localapi/v1/payment/ --form '<KEY>="<VALUE>"'

To test or initialize the terminal, you can send a transaction with the amount of 0. The webservice will immediately answer with an error message.

Example :

curl -XGET "http://192.168.0.12:16125/localapi/v1/payment/1000"
{
  "amount": "1000",
  "transactionType": "Debit",
  "giftAmount": "200",
  "totalAmount": "1200",
  "medium": "CB",
  "currency": "EUR",
  "status": "ok",
  "signatureRequired": "false",
  "transactionId": "c89655d4f990",
  "clientTicket": "A0000000041010\nDebit MasterCard\nLe 08/11/2020 a 11:27:40\nDEBIT\nXXXXXXX XXXXX\n############9853\n003 001 000014 C \nMONTANT :\n         12,00 EUR\nPour information :\n         72,16 FRF\nTICKET CLIENT\nA CONSERVER\nMERCI AU REVOIR\n",
  "client": "{}",
  "cardToken": "082AC3281C3834A6B3A3248611BE7377D734F619C7124652EFA4B97599BB3D02",
  "reference": "my_ref_123",
  "receiptTicket": "[\"hello printer\", \"this is a\", \"    wonderful\", \"        TICKET\"]"
}

curl --XPOST 'http://192.168.0.12:16125/localapi/v1/payment/' --form 'amount="1000"' --form 'currency="EUR"' 
{
  "amount": "1000",
  "transactionType": "Debit",
  "giftAmount": "200",
  "totalAmount": "1200",
  "medium": "CB",
  "currency": "EUR",
  "status": "ok",
  "signatureRequired": "false",
  "transactionId": "c89655d4f990",
  "clientTicket": "A0000000041010\nDebit MasterCard\nLe 08/11/2020 a 11:27:40\nDEBIT\nXXXXXXX XXXXX\n############9853\n003 001 000014 C \nMONTANT :\n         12,00 EUR\nPour information :\n         72,16 FRF\nTICKET CLIENT\nA CONSERVER\nMERCI AU REVOIR\n",
  "client": "{}",
  "cardToken": "082AC3281C3834A6B3A3248611BE7377D734F619C7124652EFA4B97599BB3D02",
  "reference": "my_ref_123",
  "cartId": ""
}

Test the connectivity between the terminal and your local network

curl --XGET 'http://<IP_LOCALE>:16125/localapi/v1/testconnection/' 

You should see a message on the terminal saying "Test connection local: OK".

New transaction on the terminal with the local network

Settings Default Description
amount - Amount to pay in cts.
currency EUR Currency in which the payment will be done (available with activation)
medium CB CB = Classical card transaction. (Other payment methods will be available soon)
transactionType Debit Debit = classical card transaction. Reversal = reversal of a payment
showPrepay true false Not to show any page before the payment (for instance, asking tips or donation)
showPostpay true false Not to show the print-out/send CB digital ticket page after the payment
showOnlyLastPostpay false true To show only the print-out/send CB digital ticket of the last credit card payment
client {} json that can contain the following keys: [firstName/lastName/phone/email] to pre-fill the SMS/email ticket before issuing it
cartId - id of the basket generated by the pos software
vendorToken - token of the software editor to identify him
reference - free field
forcePayment false If you want to bypass the warning screen when a payment is not yet finish.
receiptTicket [] list of strings to print the receipt ticket at the same time as the card ticket
Response Description
clientTicket Client CB ticket
transactionId id of the transaction generated by Yavin
amount Amount of the requested transaction
giftAmount Additional amount (tips or donation)
totalAmount Total amount paid (totalAmount = amount + giftAmount)
status [ok/ko] Has the transaction been validated or not
signatureRequired [yes/no] notification if the signature on the CB ticket is required, for instance, for the American Express cards
cardToken Unique credential of the client card number to identify him
reference Reference filled by the software editor

Printing on the terminal with the local network

curl --XPOST 'http://192.168.0.12:16125/localapi/v1/print/' --form 'type="text"' --form 'raw_text="Text to print\nGood morning there!"' 
Settings Default Description
type text Type of data to print. Possible values : [text, escpos]
format utf-8 The encoding of the parameter raw_text
raw_text (required) The data to print
receiptTicket (deprecated) Array of string to print. If both raw_text and receiptTicket are set, receiptTicket is unused.
Response Description
message ok

Getting the transactions history with the local network

curl --XPOST 'http://192.168.0.12:16125/localapi/v1/history/' --form 'start="2022-01-01T00:00Z"' --form 'end="2022-02-01T00:00Z"' 
Settings Default Description
start (optional) Start date to request transactions (ISO-8601 format)
end (optional) End date to request transactions (ISO-8601 format)

ISO-8601 format : [yyyy-MM-dd|yyyyMMdd][T(hh:mm[:ss[.sss]]|hhmm[ss[.sss]])]?[Z|[+-]hh[:]mm]]

E.g: 2022-02-16T00:00Z

Response

json array

E.g: [ { "amount": 1500, "created_at": "2022-01-25T10:55:55.197", "email": "null", "gift_amount": 0, "phone_number": "null", "reference": "", "scheme": "null", "scheme_group": "NULL", "status": "ko", "trs_id": "Fyv9txEnzhVw", "type": "Debit" }, { "amount": 100, "created_at": "2022-01-28T10:55:36.767", "email": "null", "gift_amount": 0, "phone_number": "null", "reference": "", "scheme": "null", "scheme_group": "NULL", "status": "ko", "trs_id": "pZCSf4fEpGYr", "type": "Debit" } ]