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:

• API Cloud (doc)

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.

• API Local (doc)

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.

• API Android Intent (doc)

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.

Login / Authentification

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

Concerning the local API and the Android Intent API, you'll need to login manually to Yavin Pay using the same credentials as those of My Yavin https://my.yavin.com

Concerning the cloud API, the authentification is done via Yavin token.

API Cloud

cloud-Authentification

curl -XPOST "https://api.yavin.com/api/v4/pos/payment/" \
  --header 'Yavin-Secret: YAVIN_API_KEY' \
  --data '{
  ...
}'

import requests

url = 'https://api.yavin.com/api/v4/pos/payment/'
headers = {
  'Content-Type': 'application/json',
  'Yavin-Secret': 'YAVIN_API_KEY'
}

params = {
    ...
}

r = requests.post(url=url, json=params, headers=headers)

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, your API key must be in the headers of the POST request:

cloud-Errors

The Yavin API uses the following error codes:

Code	Explication
400	Bad Request -- The request is invalid.
401	Unauthorized -- The API key is invalid or the terminal cannot be access with this API key
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.

cloud-Start a transaction

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

Request

POST https://api.yavin.com/api/v4/pos/payment/

curl -XPOST "https://api.yavin.com/api/v4/pos/payment/" \
  --header 'Yavin-Secret: YAVIN_API_KEY' \
  --data '{
    "serialNumber": "123456789",
    "amount": 1000,
    "transactionType": "debit",
    "vendor": {
      "softwareVersion": "1.0",
      "softwareName": "name"
    },
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@yavin.com"
    },
    "receiptTicket": {
      "data": "This is the receipt ticket\nto print",
      "format": "text"
    },
    "receiptTicketJson": "{\"transactionId\": \"123456\", \"amount\": 3500 }"
}'

import requests
import json

url = 'https://api.yavin.com/api/v4/pos/payment/'
headers = {
  'Content-Type': 'application/json',
  'Yavin-Secret': 'YAVIN_API_KEY'
}

params = {
    "serialNumber": "123456789",
    "amount": 1000,
    "transactionType": "debit",
    "vendor": {
      "softwareVersion": "1.0",
      "softwareName": "name"
    },
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@yavin.com"
    },
    "receiptTicket": {
      "data": "This is the receipt ticket\nto print",
      "format": "text"
    },
    "receiptTicketJson": json.dumps({ "transactionId": "123456", "amount": 3500 })
}

r = requests.post(url=url, json=params, headers=headers)

Parameters	Type	Default	Description
serialNumber	String	(mandatory)	Terminal serial number. It can be found on the back of the terminal next to S/N acronym
amount	Integer		Amount in cents. 1€ => 100. This does not include tips. This amount should always be positive even for transactionType=Reversal or transactionType=Refund.
giftAmount	Integer	0	Tips or donation in cents
medium	String	card	card = Classical card transaction. (Other payment methods will be available soon). [card, qrcode, 2x, 3x, 4x,ancv, wechat, alipay, lydia, restoflash,...]
transactionType	String	debit	debit = classical card transaction. reversal = reversal of a payment refund = refund to a customer (not linked to previous payment) [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer		Pre-field customer info to send via SMS or Email. See object Customer
vendor	Vendor		Software editor info to identify it. See object Vendor
reference	String		Free field that the merchant can see in his My Yavin backoffice
receiptTicket	ReceiptTicket		Data to print receipt ticket in the same time as the card ticket. See object ReceiptTicket
receiptTicketJson	Ecommerce Object		Takes a json object consisting of the same data required for ecommerce api
cartId	String		Cart id associated to the transaction. This will be useful to link a payment and a receipt ticket if the receipt ticket wasn't filled initially

cloud-payment-Customer

Parameters	Type	Default	Description
email	String		Email
firstName	String		First name
lastName	String		Last name
phone	String		Phone number international format starting with + symbol (e.g: +33612345678)

cloud-payment-ReceiptTicket

Parameters	Type	Default	Description
format	String	text	Format of data to print. Possible values : [text, escpos]
data	String	(mandatory)	The data to print. If format = text, data will be printed as it is. If format = escpos, then data must be the ESCPOS output encoded to a hex string (e.g: 1b401d6210...) which is the output received by the printer. We currently support ESCPOS package in Android, Javascript, Python, look at Yavin github for examples

cloud-payment-Vendor

Parameters	Type	Default	Description
softwareName	String		Name of cashier software
softwareVersion	String		Version of cashier software. This will be useful to help track and identify bugs as quickly as possible

Response

{
  "status": "ok",
  "transactionId": "nvfkkFGFXr4Ew"
}

Parameters	Type	Description
status	String	ok if the transaction has been received successfully . Else ko
transactionId	String	Unique id of the transaction

Webhook Response

{
  "status": "ok",
  "trs_id": "nvfkkFGFXr4Ew",
  "app_version": "5.0.1",
  "asked_amount": 100,
  "gift_amount": 0,
  "total_amount": 100,
  "cartId": "2",
  "client_ticket": "Client Ticket\n\nStatus: OK\n\nPAN: 4444...4444\n\nCard token: 6767709988762\n\nAmount: € 1.00\n",
  "company_ticket": "Company Ticket\n\nStatus: OK\n\nPAN: 4444...4444\n\nCard token: 6767709988762\n\nAmount: € 1.00\n",
  "receiptTicket": {
      "data": "This is the receipt ticket\nto print",
      "format": "text"
    },
  "currencyCode": "EUR",
  "device_datetime": "2022-09-26T11:11:29.148",
  "device_timestamp": 1664183489148,
  "medium": "card",
  "reference": "YOUR-REF-01",
  "serial_number": "bf075053ef08078a",
  "server_timestamp": 1664183496498,
  "type": "Debit",
  "vendor": {
   "apiVersion": "v1"
  }

}

Paramètres	Type	Description
status	String	[ok / ko] Transaction successful or not
trs_id	String	Unique id of the transaction
app_version	String	Yavin Pay app version
asked_amount	Integer	Amount in cents. 1€ => 100
gift_amount	Integer	Tips or donation in cents
total_amount	Integer	Total amount of the transaction (=gift_amount + asked_amount)
cartId	String	Cart id associated to the transaction
client_ticket	String	Client transaction card ticket
company_ticket	String	Merchant transaction card ticket
receipt_ticket	ReceiptTicket	Data to print receipt ticket in the same time as the card ticket. See object ReceiptTicket
currencyCode	String	Currency Code as ISO 4217 in which the payment will be done (available with activation)
device_datetime	String	Date and time of the terminal when the transaction was made
device_timestamp	String	Timestamp of the terminal
medium	String	card = Classical card transaction. (Other payment methods will be available soon). [card, qrcode, 2x, 3x, 4x,ancv, wechat, alipay, lydia, restoflash,...]
reference	String	Free field that the merchant can see in his My Yavin backoffice
serial_number	String	Serial number of the terminal
server_timestamp	String	Timestamp of the server
type	String	debit = classical card transaction. reversal = cancellation of a payment. [debit, reversal, preauthorisation, closingbatch]
vendor	Vendor	Software editor info to identify it. See object Vendor

cloud-Print a receipt ticket

Request

POST https://api.yavin.com/api/v4/pos/print/

curl -XPOST "https://api.yavin.com/api/v4/pos/print/" \
  --header 'Yavin-Secret: YAVIN_API_KEY' \
  --data '{
    "serialNumber": "123456789",
    "format": "text",
    "data": "This is a ticket\nto print !"
}'

import requests

url = 'https://api.yavin.com/api/v4/pos/print/'
headers = {
  'Content-Type': 'application/json',
  'Yavin-Secret': 'YAVIN_API_KEY'
}

params = {
    "serialNumber": "123456789",
    "format": "text",
    "data": "This is a ticket\nto print !"
}

r = requests.post(url=url, json=params, headers=headers)

Parameters	Type	Default	Description
serialNumber	String	(mandatory)	Terminal serial number. It can be found on the back of the terminal next to S/N acronym
format	String	text	Format of data to print. Possible values : [text, escpos]
data	String	(mandatory)	The data to print. If format = text, data will be printed as it is. If format = escpos, then data must be the ESCPOS output encoded to a hex string (e.g: 1b401d6210...) which is the output received by the printer. We currently support ESCPOS package in Android, Javascript, Python, look at Yavin github for examples

Response

{
  "status": "ok"
}

Parameters	Type	Description
status	String	ok / ko

cloud-Share a receipt ticket

This API allows to share a receipt ticket via a specific medium (sms, email, print). If the customer field Customer is present in the request we can send the ticket directly to them. Otherwise the needed customer field will be asked through the terminal.

Request

POST https://api.yavin.com/api/v4/pos/share-receipt

curl -XPOST "https://api.yavin.com/api/v4/pos/share-receipt" \
  --header 'Yavin-Secret: YAVIN_API_KEY' \
  --data '{
    "serialNumber": "123456789",
    "receiptTicket": {
      "data": "This is the receipt ticket\nto print",
      "format": "text"
    },
    "transactionId": "fsOv53g7wxZ",
    "medium": "email",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@yavin.com"
    }
}'

import requests

url = 'https://api.yavin.com/api/v4/pos/share-receipt'
headers = {
  'Content-Type': 'application/json',
  'Yavin-Secret': 'YAVIN_API_KEY'
}

params = {
    "serialNumber": "123456789",
    "receiptTicket": {
      "data": "This is the receipt ticket\nto print",
      "format": "text"
    },
    "transactionId": "fsOv53g7wxZ",
    "medium": "email",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@yavin.com"
    }
}

r = requests.post(url=url, json=params, headers=headers)

Parameters	Type	Default	Description
serialNumber	String	(mandatory)	Terminal serial number. It can be found on the back of the terminal next to S/N acronym
receiptTicket	ReceiptTicket	(mandatory)	Receipt ticket to share. See object ReceiptTicket
transactionId	String	(mandatory)	The transaction ID corresponding to the ticket to be shared. It must be the one used from the Payment API
medium	String	yavin	The medium used to share ticket. Possible values are [yavin, sms, email, print]. If yavin then we will store and share the receipt ticket according to the user notification preferences
customer	Customer		Pre-field customer info to send via SMS or Email. See object Customer

cloud-share-Customer

Parameters	Type	Default	Description
email	String		Email
firstName	String		First name
lastName	String		Last name
phone	String		Phone number international format starting with + symbol (e.g: +33612345678)

cloud-share-ReceiptTicket

Parameters	Type	Default	Description
format	String	text	Format of data to share. Possible values : [text, escpos]
data	String	(mandatory)	The receipt ticket to share. If format = text, data will be printed as it is. If format = escpos, then data must be the ESCPOS output encoded to a hex string (e.g: 1b401d6210...) which is the output received by the printer. We currently support ESCPOS package in Android, Javascript, Python, look at Yavin github for examples

Response

{
  "status": "ok"
}

Parameters	Type	Description
status	String	ok / ko

cloud-Fetch transactions

curl -XPOST "https://api.yavin.com/api/v4/pos/transactions/" \
  --header 'Yavin-Secret: YAVIN_API_KEY' \
  --data '{
    "serialNumbers": ["123456789"],
    "timezone": "Europe/Paris",
    "startDate": "2022-01-01",
    "endDate": "2022-02-01",
    "startTime": "00:00:00",
    "endTime": "23:59:59",
    "limit": 100
}'

import requests

url = 'https://api.yavin.com/api/v4/pos/transactions/'
headers = {
  'Content-Type': 'application/json',
  'Yavin-Secret': 'YAVIN_API_KEY'
}

params = {
    "serialNumbers": ["123456789"],
    "timezone": "Europe/Paris",
    "startDate": "2022-01-01",
    "endDate": "2022-02-01",
    "startTime": "00:00:00",
    "endTime": "23:59:59",
    "limit": 100
}

r = requests.post(url=url, json=params, headers=headers)

The above request returns the below JSON response :

{
    "total": 356,
    "limit": 100,
    "offset": 0,
    "count": 100,
    "transactions": [
        {
            "amount": 100,
            "createdAt": "2022-05-10T14:09:06",
            "giftAmount": 0,
            "issuer": "BNP",
            "scheme": "CB",
            "status": "ok",
            "transactionId": "IEqoLmjuRqfq",
            "type": "debit",
            "serialNumber": "123456789"
        },
        {
            "amount": 300,
            "createdAt": "2022-05-10T14:08:25",
            "giftAmount": 0,
            "issuer": "EDENRED",
            "reference": "",
            "scheme": "CB",
            "status": "ok",
            "transactionId": "8tPuSUIN6AaP",
            "type": "debit",
            "serialNumber": "123456789"
        },
      ...
    ]
}

Request

POST https://api.yavin.com/api/v4/pos/transactions/

Parameters	Type	Default	Description
serialNumbers	Array of String	(optional)	Terminal serial numbers. It can be found on the back of the terminal next to S/N acronym
timezone	String	(optional)	Timezone ID of the caller (e.g: "Europe/Paris"). We strongly advise to set the timezone in order to get correct data
startDate	String	(optional)	Start date (yyyy-MM-dd format)
endDate	String	(optional)	End date (yyyy-MM-dd format) Note: is exclusive
startTime	String	(optional)	Start time (hh:mm:ss format)
endTime	String	(optional)	End time (hh:mm:ss format)
limit	Integer	20	Limit of the number of transactions to receive with a request (max = 200)
offset	Integer	0	Offset of transactions in the request

By default, if no date/time filters are set then the last 30 days are fetched.

Response

The transaction object contains the following fields: (see example)

Parameters	Type	Description
status	String	[ok / ko] Transaction successful or not
transactionId	String	Transaction id
amount	Integer	Amount in cents. 1€ => 100. Does not include tips
giftAmount	Integer	Tips or donation in cents
currencyCode	String	Currency Code as ISO 4217 in which the payment will be done (available with activation)
issuer	String	Issuer of the payment
scheme	String	Network used to validate the transaction (CB,CBSC (contactless),VISA,MASTERCARD,CONECS...)
transactionType	String	debit = classical card transaction. reversal = reversal of a payment refund = refund to a customer (not linked to previous payment) [debit, reversal, refund, preauthorisation, closingbatch]
reference	String	Free field that the merchant can see in his My Yavin backoffice
cartId	String	Cart id associated to the transaction
appVersion	String	Yavin Pay app version
createdAt	String	Datetime of the transactions at UTC timezone (ex: 2022-10-21T12:45:30.000Z)
serialNumber	String	Serial number of the transaction that collected the transaction.

cloud-Cancel a transaction

This endpoint is used to cancel a payment on your terminal.

Request

curl -XPOST "https://api.yavin.com/api/v4/pos/cancel/" \
  --header 'Yavin-Secret: YAVIN_API_KEY' \
  --data '{
    "serialNumber": "123456789"
}'

import requests

url = 'https://api.yavin.com/api/v4/pos/cancel/'
headers = {
  'Content-Type': 'application/json',
  'Yavin-Secret': 'YAVIN_API_KEY'
}

params = {
    "serialNumber": "123456789"
}

r = requests.post(url=url, json=params, headers=headers)

Parameters	Type	Default	Description
serialNumber	String	(mandatory)	Terminal serial number. It can be found on the back of the terminal next to S/N acronym

Response

{
  "status": "ok"
}

Parameters	Type	Description
status	String	ok / ko

API Local

This API allows you to initiate a payment, print a ticket or fetch transactions history from the Yavin terminal connected to a local network.

You can either use local IP or Network Service Discovery compatible with Apple Bonjour. (see example here)

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

• P : 16st letter of the alphabet
• A : 1st letter of the alphabet
• Y : 25st letter of the alphabet

local-Ping the terminal

curl -XGET 'http://<LOCAL_IP>:16125/localapi/v4/ping' 

Request

GET 'http://<LOCAL_IP>:16125/localapi/v4/ping

Make the above request to check if your configuration is correct.
You can append a query parameter showMessage that will display a message on the terminal saying "Hello there" if the value is true.
By default showMessage is false.

E.g: GET 'http://<LOCAL_IP>:16125/localapi/v4/ping?showMessage=true

Response

{
  "status": "ok"
}

Parameters	Type	Description
status	String	ok / ko

local-Start a transaction

Request

For a simple request (with only the amount):

Simple request

curl -XGET "http://<LOCAL_IP>:16125/localapi/v4/payment/1000"

GET http://<IP_LOCALE>:16125/localapi/v4/payment/<AMOUNT>

For a more complex request (with other fields), a POST request must be sent with JSON formatted input:

Complete request

curl -X POST 'http://<LOCAL_IP>:16125/localapi/v4/payment' \
  --header 'Content-Type: application/json' \
  --data '
  {
    "amount": 1000,
    "vendor": {
      "softwareVersion": "1.0",
      "softwareName": "name"
    },
    "receiptTicket": {
      "data": "This is the receipt ticket\nto print",
      "format": "text"
    },
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@yavin.com"
    },
    "receiptTicketJson": "{\"transactionId\": \"123456\", \"amount\": 3500 }"
  }'

import requests
import json

url = 'http://<IP_LOCALE>:16125/localapi/v4/payment'

params = {
    "amount": 1000,
    "vendor": {
      "softwareVersion": "1.0",
      "softwareName": "name"
    },
    "receiptTicket": {
      "data": "This is the receipt ticket\nto print",
      "format": "text"
    },
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@yavin.com"
    },
    "receiptTicketJson": json.dumps({ "transactionId": "123456", "amount": 3500 })
  }

r = requests.post(url=url, json=params)

Customer structure

{
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+33612345678",
    "email": "john@yavin.com"
  }
}

ReceiptTicket structure

{
  "receiptTicket": {
    "data": "Receipt ticket here to print if needed",
    "format": "text"
  }
}

Vendor structure

{
  "vendor": {
    "softwareVersion": "1.0",
    "softwareName": "Cool Name"
  }
}

POST http://<LOCAL_IP>:16125/localapi/v4/payment

Parameters	Type	Default	Description
amount	Integer		Amount in cents. 1€ => 100. This does not include tips. This amount should always be positive even for transactionType=Reversal or transactionType=Refund.
giftAmount	Integer	0	Tips or donation in cents
medium	String	card	card = Classical card transaction. (Other payment methods will be available soon). [card, qrcode, 2x, 3x, 4x,ancv, wechat, alipay, lydia, restoflash,...]
transactionType	String	debit	debit = classical card transaction. reversal = reversal of a payment refund = refund to a customer (not linked to previous payment) [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer		Pre-field customer info to send via SMS or Email. See object Customer
vendor	Vendor		Software editor info to identify it. See object Vendor
reference	String		Free field that the merchant can see in his My Yavin backoffice
receiptTicket	ReceiptTicket		Data to print receipt ticket in the same time as the card ticket. See object ReceiptTicket
receiptTicketJson	Ecommerce Object		Takes a json object consisting of the same data required for ecommerce api
cartId	String		Cart id associated to the transaction. This will be useful to link a payment and a receipt ticket if the receipt ticket wasn't filled initially
idempotentUuid	String		Idempotent unique identifier for the payment. If the terminal knows a transaction with this UUID in the last 24 hours then the terminal will respond with the corresponding transaction. Otherwise, if no transaction is associated to the UUID a new payment will be initiated and associated with the UUID once the payment completed. Note: if a transaction failed (status "ko") and the idempotent UUID stays the same, the terminal will respond with the failed transaction. You may want to change the idempotent UUID in this case.

local-payment-Customer

Parameters	Type	Default	Description
email	String		Email
firstName	String		First name
lastName	String		Last name
phone	String		Phone number international format starting with + symbol (e.g: +33612345678)

local-payment-ReceiptTicket

Parameters	Type	Default	Description
format	String	text	Format of data to print. Possible values : [text, escpos]
data	String	(mandatory)	The data to print. If format = text, data will be printed as it is. If format = escpos, then data must be the ESCPOS output encoded to a hex string (e.g: 1b401d6210...) which is the output received by the printer. We currently support ESCPOS package in Android, Javascript, Python, look at Yavin github for examples

local-payment-Vendor

Parameters	Type	Default	Description
softwareName	String		Name of cashier software
softwareVersion	String		Version of cashier software. This will be useful to help track and identify bugs as quickly as possible

Response

TransactionResponse

{
    "amount": 1000,
    "appVersion": "3.2.8",
    "cardToken": "1234567890",
    "clientCardTicket": "Sandbox Fake ticket\n\nStatus: OK\n\nPAN: 42424242....4242\n\nCard token: 1234567890\n\nAmount: 1.0\n\nTotal Amount: 10.0\n",
    "currencyCode": "EUR",
    "giftAmount": 0,
    "scheme": "CB",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@yavin.com"
    },
    "status": "ok",
    "transactionId": "xPUyi4fmdibD",
    "transactionType": "Debit"
}

Paramètres	Type	Description
status	String	[ok / ko] Transaction successful or not
transactionId	String	Transaction id
amount	Integer	Amount in cents. 1€ => 100
giftAmount	Integer	Tips or donation in cents
currencyCode	String	Currency Code as ISO 4217 in which the payment will be done (available with activation)
issuer	String	Issuer of the payment
scheme	String	Network used to validate the transaction (CB,CBSC (contactless),VISA,MASTERCARD,CONECS...)
transactionType	String	debit = classical card transaction. reversal = reversal of a payment refund = refund to a customer (not linked to previous payment) [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer	Pre-field customer info to send via SMS or Email. See object Customer
reference	String	Free field
cartId	String	Cart id associated to the transaction
clientCardTicket	String	Client transaction card ticket
merchantCardTicket	String	Merchant transaction card ticket
appVersion	String	Yavin Pay app version
idempotentUuid	String	Idempotent unique identifier from the request

local-Print a receipt ticket

curl -XPOST 'http://<IP_LOCALE>:6125/localapi/v4/print' \
  --header 'Content-Type: application/json' \
  --data '
  {
    "data": "This is the text\nto print",
    "format": "text"
  }'

import requests

url = 'http://<IP_LOCALE>:16125/localapi/v4/print'

params = {
    "data": "This is the text\nto print",
    "format": "text"
  }

r = requests.post(url=url, json=params)

Request

POST http://<IP_LOCALE>:6125/localapi/v4/print

Parameters	Type	Default	Description
format	String	text	Format of data to print. Possible values : [text, escpos]
data	String	(mandatory)	The data to print. If format = text, data will be printed as it is. If format = escpos, then data must be the ESCPOS output encoded to a hex string (e.g: 1b401d6210...) which is the output received by the printer. We currently support ESCPOS package in Android, Javascript, Python, look at Yavin github for examples

Response

{
  "status": "ok"
}

Parameters	Type	Description
status	String	ok / ko
message	String	Additional information

local-Share a receipt ticket

This API allows to share a receipt ticket via a specific medium (sms, email, print). If the customer field Customer is present in the request we can send the ticket directly to them. Otherwise the needed customer field will be asked through the terminal.

Request

curl -X POST 'http://<IP_LOCALE>:16125/localapi/v4/share-receipt' -d '{
  "receiptTicket": {
    "data": "This is the receipt ticket\nto print",
    "format": "text"
  },
    "transactionId": "fsOv53g7wxZ",
    "medium": "email",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@yavin.com"
    }
}'

import requests

url = 'http://<IP_LOCALE>:16125/localapi/v4/share-receipt'

params = {
    "receiptTicket": {
        "data": "This is the receipt ticket\nto print",
        "format": "text"
    },
    "transactionId": "fsOv53g7wxZ",
    "medium": "email",
    "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@yavin.com"
    }
}

r = requests.post(url=url, json=params)

Parameters	Type	Default	Description
receiptTicket	ReceiptTicket	(mandatory)	Receipt ticket to share. See object ReceiptTicket
transactionId	String	(mandatory)	The transaction ID corresponding to the ticket to be shared. It must be the one used from the Payment API
medium	String	yavin	The medium used to share ticket. Possible values are [yavin, sms, email, print]. If yavin then we will store and share the receipt ticket according to the user notification preferences
customer	Customer		Pre-field customer info to send via SMS or Email. See object Customer

local-share-Customer

Parameters	Type	Default	Description
email	String		Email
firstName	String		First name
lastName	String		Last name
phone	String		Phone number international format starting with + symbol (e.g: +33612345678)

local-share-ReceiptTicket

Parameters	Type	Default	Description
format	String	text	Format of data to share. Possible values : [text, escpos]
data	String	(mandatory)	The receipt ticket to share. If format = text, data will be printed as it is. If format = escpos, then data must be the ESCPOS output encoded to a hex string (e.g: 1b401d6210...) which is the output received by the printer. We currently support ESCPOS package in Android, Javascript, Python, look at Yavin github for examples

Response

{
  "status": "ok"
}

Parameters	Type	Description
status	String	ok / ko

local-Fetch transactions

curl -XPOST 'http://<LOCAL_IP>:16125/localapi/v4/transactions' \
  --header 'Content-Type: application/json' \
  --data '{
    "startDate": "2022-01-01",
    "endDate": "2022-02-01",
    "startTime": "00:00:00",
    "endTime": "23:59:59",
    "limit": 50
  }'

import requests

url = 'http://<IP_LOCALE>:16125/localapi/v4/transactions'

params = {
    "startDate": "2022-01-01",
    "endDate": "2022-02-01",
    "startTime": "00:00:00",
    "endTime": "23:59:59",
    "limit": 50
  }

r = requests.post(url=url, json=params)

Request

POST 'http://<LOCAL_IP>:16125/localapi/v4/transactions

Parameters	Type	Default	Description
startDate	String	(optional)	Start date (yyyy-MM-dd format)
endDate	String	(optional)	End date (yyyy-MM-dd format) Note: is exclusive
startTime	String	(optional)	Start time (hh:mm:ss format)
endTime	String	(optional)	End time (hh:mm:ss format)
limit	Integer	20	Limit of the number of transactions to receive with a request (max = 200)
offset	Integer	0	Offset of transactions in the request

By default, if no date/time filters are set then the last 30 days are fetched.

Response

See example.

Parameters	Type	Description
status	String	[ok / ko] Transaction successful or not
transactionId	String	Transaction id
amount	Integer	Amount in cents. 1€ => 100
giftAmount	Integer	Tips or donation in cents. Does not include tips
currencyCode	String	Currency Code as ISO 4217 in which the payment will be done (available with activation)
issuer	String	Issuer of the payment
scheme	String	Network used to validate the transaction (CB,CBSC (contactless),VISA,MASTERCARD,CONECS...)
transactionType	String	debit = classical card transaction. reversal = reversal of a payment refund = refund to a customer (not linked to previous payment) [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer	See object Customer
reference	String	Free field that the merchant can see in his My Yavin backoffice
cartId	String	Cart id associated to the transaction
appVersion	String	Yavin Pay app version
createdAt	String	Datetime of the transactions at UTC timezone (ex: 2022-10-21T12:45:30.000Z)

local-transactions-Customer

Parameters	Type	Description
email	String	Email
firstName	String	First name
lastName	String	Last name
phone	String	Phone number

{
    "count": 50,
    "limit": 50,
    "offset": 3,
    "total": 156,
    "transactions": [
        {
            "amount": 100,
            "createdAt": "2022-05-10T14:09:06",
            "customer": {
                "email": "",
                "phone": "0612345687"
            },
            "giftAmount": 0,
            "issuer": "BNP",
            "scheme": "CB",
            "status": "ok",
            "transactionId": "IEqoLmjuRqfq",
            "type": "debit"
        },
        {
            "amount": 100,
            "createdAt": "2022-05-10T14:08:25",
            "customer": {},
            "giftAmount": 0,
            "issuer": "EDENRED",
            "reference": "",
            "scheme": "CB",
            "status": "ok",
            "transactionId": "8tPuSUIN6AaP",
            "type": "debit"
        },

      ...
    ]
}

API Android

The Android Yavin Pay app allows Android Intent to initiate a payment or print some text.

Check the kotlin section on the right.

android-Start a transaction

Request

To trigger a payment by Intent, use the following code:

Check kotlin section

Check kotlin section

val request = TransactionRequest(
  amount = 100,
  customer = Customer("John", "Doe", "john@yavin.com"),
  vendor = Vendor("Awesome Partner", "1.2.3"),
  receiptTicket = ReceiptTicket(data = "This is a wonderful\n receipt ticket to print", format = "text"),
  receiptTicketJson = JSONObject("{\"transactionId\": \"123456\", \"amount\": 3500 }").toString()
)

val jsonData = Gson().toJson(request)
val queryParams = Uri.encode(jsonData)

val intent = Intent(Intent.ACTION_VIEW).apply {
  data = Uri.parse("yavin://com.yavin.macewindu/v4/payment?data=$queryParams")
}

startActivityForResult(intent, REQUEST_CODE_PAYMENT)

A payment is triggered on the terminal by Intent using the defined format in the kotlin section.

Below is the structure of the input data TransactionRequest :

TransactionRequest.kt

Check kotlin section

Check kotlin section

data class TransactionRequest(
    @SerializedName("amount")
    var amount: Int,
    @SerializedName("cartId")
    var cartId: String?,
    @SerializedName("customer")
    var customer: Customer?,
    @SerializedName("giftAmount")
    var giftAmount: Int?,
    @SerializedName("medium")
    var medium: String?,
    @SerializedName("receiptTicket")
    var receiptTicket: ReceiptTicket?,
    @SerializedName("receiptTicketJson")
    var receiptTicketJson: String?,
    @SerializedName("reference")
    var reference: String?,
    @SerializedName("transactionType")
    var transactionType: String?,
    @SerializedName("vendor")
    var vendor: Vendor?,
    @SerializedName("idempotentUuid")
    var idempotentUuid: String?
)

Parameters	Type	Default	Description
amount	Integer		Amount in cents. 1€ => 100. This does not include tips. This amount should always be positive even for transactionType=Reversal or transactionType=Refund.
giftAmount	Integer	0	Tips or donation in cents
medium	String	card	card = Classical card transaction. (Other payment methods will be available soon). [card, qrcode, 2x, 3x, 4x,ancv, wechat, alipay, lydia, restoflash,...]
transactionType	String	debit	debit = classical card transaction. reversal = reversal of a payment refund = refund to a customer (not linked to previous payment) [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer		Pre-field customer info to send via SMS or Email. See object Customer
vendor	Vendor		Software editor info to identify it. See object Vendor
reference	String		Free field that the merchant can see in his My Yavin backoffice
receiptTicket	ReceiptTicket		Data to print receipt ticket in the same time as the card ticket. See object ReceiptTicket
receiptTicketJson	Ecommerce Object		Takes a json object consisting of the same data required for ecommerce api
cartId	String		Cart id associated to the transaction. This will be useful to link a payment and a receipt ticket if the receipt ticket wasn't filled initially
idempotentUuid	String		Idempotent unique identifier for the payment. If the terminal knows a transaction with this UUID in the last 24 hours then the terminal will respond with the corresponding transaction. Otherwise, if no transaction is associated to the UUID a new payment will be initiated and associated with the UUID once the payment completed. Note: if a transaction failed (status "ko") and the idempotent UUID stays the same, the terminal will respond with the failed transaction. You may want to change the idempotent UUID in this case.

Customer.kt

Check kotlin section

Check kotlin section

data class Customer(
    @SerializedName("email")
    var email: String?,
    @SerializedName("firstName")
    var firstName: String?,
    @SerializedName("lastName")
    var lastName: String?,
    @SerializedName("phone")
    var phone: String?
)

android-payment-Customer

Parameters	Type	Default	Description
email	String		Email
firstName	String		First name
lastName	String		Last name
phone	String		Phone number international format starting with + symbol (e.g: +33612345678)

ReceiptTicket.kt

Check kotlin section

Check kotlin section

data class ReceiptTicket(
    @SerializedName("data")
    var `data`: String?,
    @SerializedName("format")
    var format: String?
)

android-payment-ReceiptTicket

Parameters	Type	Default	Description
format	String	text	Format of data to print. Possible values : [text, escpos]
data	String	(mandatory)	The data to print. If format = text, data will be printed as it is. If format = escpos, then data must be the ESCPOS output encoded to a hex string (e.g: 1b401d6210...) which is the output received by the printer. We currently support ESCPOS package in Android, Javascript, Python, look at Yavin github for examples

Vendor.kt

Check kotlin section

Check kotlin section

data class Vendor(
    @SerializedName("softwareName")
    var softwareName: String?,
    @SerializedName("softwareVersion")
    var softwareVersion: String?
)

android-payment-Vendor

Parameters	Type	Default	Description
softwareName	String		Name of cashier software
softwareVersion	String		Version of cashier software. This will be useful to help track and identify bugs as quickly as possible

Response

When your application receives the transaction response back in onActivityResult(), get the serialized JSON transaction output from the data Intent using the key response from the extras Bundle.

To get the transaction response, use this code:

Check kotlin section

Check kotlin section

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REQUEST_CODE_PAYMENT) {
        // handle post payment response from Yavin PAY
        val json = data.extras?.getString("response")
        val response = Gson().fromJson(json, TransactionResponse::class.java)
    }
}

Here is the TransactionResponse structure:

TransactionResponse.kt

Check kotlin section

Check kotlin section

data class TransactionResponse(
    @SerializedName("appVersion")
    var appVersion: String? = null,
    @SerializedName("amount")
    var amount: Int = 0,
    @SerializedName("cardToken")
    var cardToken: String? = null,
    @SerializedName("cartId")
    var cartId: String? = null,
    @SerializedName("clientCardTicket")
    var clientCardTicket: String? = null,
    @SerializedName("merchantCardTicket")
    var merchantCardTicket: String? = null,
    @SerializedName("currencyCode")
    var currencyCode: String? = null,
    @SerializedName("customer")
    var customer: Customer? = null,
    @SerializedName("giftAmount")
    var giftAmount: Int? = 0,
    @SerializedName("scheme")
    var scheme: String? = null,
    @SerializedName("issuer")
    var issuer: String? = null,
    @SerializedName("reference")
    var reference: String? = null,
    @SerializedName("status")
    var status: String? = null,
    @SerializedName("transactionId")
    var transactionId: String? = null,
    @SerializedName("transactionType")
    var transactionType: String? = null,
    @SerializedName("idempotentUuid")
    var idempotentUuid: String?
)

Parameters	Type	Description
status	String	[ok / ko] Transaction successful or not
transactionId	String	Transaction id
amount	Integer	Amount in cents. 1€ => 100. This does not include gift amount
giftAmount	Integer	Tips or donation in cents
currencyCode	String	Currency Code as ISO 4217 in which the payment will be done (available with activation)
issuer	String	Issuer of the payment
scheme	String	Network used to validate the transaction (CB,CBSC (contactless),VISA,MASTERCARD,CONECS...)
transactionType	String	debit = classical card transaction. reversal = reversal of a payment refund = refund to a customer (not linked to previous payment) [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer	Pre-field customer info to send via SMS or Email. See object Customer
reference	String	Free field that the merchant can see in his My Yavin backoffice
cartId	String	Cart id associated to the transaction
clientCardTicket	String	Client transaction card ticket
merchantCardTicket	String	Merchant transaction card ticket
appVersion	String	Yavin Pay app version
idempotentUuid	String	Idempotent unique identifier from the request

android-Print a receipt ticket

Request

To print by Intent, use this code:

Check kotlin section

Check kotlin section

val request = PrintRequest(
  format = "text",
  data = "Text to print"
)

val jsonData = Gson().toJson(request)
val queryParams = Uri.encode(jsonData)

val intent = Intent(Intent.ACTION_VIEW).apply {
  data = Uri.parse("yavin://com.yavin.macewindu/v4/print?data=$queryParams")
}

startActivityForResult(intent, REQUEST_CODE_PRINT)

PrintRequest.kt

Check kotlin section

Check kotlin section

data class PrintRequest(
    @SerializedName("format")
    var format: String?,
    @SerializedName("data")
    var `data`: String?
)

Parameters	Type	Default	Description
format	String	text	Format of data to print. Possible values : [text, escpos]
data	String	(mandatory)	The data to print. If format = text, data will be printed as it is. If format = escpos, then data must be the ESCPOS output encoded to a hex string (e.g: 1b401d6210...) which is the output received by the printer. We currently support ESCPOS package in Android, Javascript, Python, look at Yavin github for examples

Response

To get response :

Check kotlin section

Check kotlin section

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REQUEST_CODE_PRINT) {
        val json = data.extras?.getString("response")
        val response = Gson().fromJson(json, PrintResponse::class.java)
    }
}

PrintResponse.kt

Check kotlin section

Check kotlin section

data class PrintResponse(
    @SerializedName("status")
    var status: String?
)

Parameters	Type	Description
status	String	ok / ko

android-Share a receipt ticket

This API allows to share a receipt ticket via a specific medium (sms, email, print). If the customer field Customer is present in the request we can send the ticket directly to them. Otherwise the needed customer field will be asked through the terminal.

Request

To share by Intent, use this code:

Check kotlin section

Check kotlin section

val request = ShareRequest(
  receiptTicket = ReceiptTicket(format = "text", data = "Text to print"),
  transactionId = "gks15fQSfw",
  medium = "email",
  customer = Customer("John", "Doe", email = "john@yavin.com")
)

val jsonData = Gson().toJson(request)
val queryParams = Uri.encode(jsonData)

val intent = Intent(Intent.ACTION_VIEW).apply {
  data = Uri.parse("yavin://com.yavin.macewindu/v4/share-receipt?data=$queryParams")
}

startActivityForResult(intent, REQUEST_CODE_SHARE)

ShareRequest.kt

Check kotlin section

Check kotlin section

data class ShareRequest(
    @SerializedName("receiptTicket")
    var receiptTicket: ReceiptTicket?,
    @SerializedName("transactionId")
    var transactionId: String?,
    @SerializedName("medium")
    var medium: String?,
    @SerializedName("customer")
    var customer: Customer?
)

Parameters	Type	Default	Description
receiptTicket	ReceiptTicket	(mandatory)	Receipt ticket to share. See object ReceiptTicket
transactionId	String	(mandatory)	The transaction ID corresponding to the ticket to be shared. It must be the one used from the Payment API
medium	String	yavin	The medium used to share ticket. Possible values are [yavin, sms, email, print]. If yavin then we will store and share the receipt ticket according to the user notification preferences
customer	Customer		Pre-field customer info to send via SMS or Email. See object Customer

Customer.kt

Check kotlin section

Check kotlin section

data class Customer(
    @SerializedName("email")
    var email: String?,
    @SerializedName("firstName")
    var firstName: String?,
    @SerializedName("lastName")
    var lastName: String?,
    @SerializedName("phone")
    var phone: String?
)

android-share-Customer

Parameters	Type	Default	Description
email	String		Email
firstName	String		First name
lastName	String		Last name
phone	String		Phone number international format starting with + symbol (e.g: +33612345678)

ReceiptTicket.kt

Check kotlin section

Check kotlin section

data class ReceiptTicket(
    @SerializedName("data")
    var `data`: String?,
    @SerializedName("format")
    var format: String?
)

android-share-ReceiptTicket

Parameters	Type	Default	Description
format	String	text	Format of data to share. Possible values : [text, escpos]
data	String	(mandatory)	The receipt ticket to share. If format = text, data will be printed as it is. If format = escpos, then data must be the ESCPOS output encoded to a hex string (e.g: 1b401d6210...) which is the output received by the printer. We currently support ESCPOS package in Android, Javascript, Python, look at Yavin github for examples

Response

To get the response :

Check kotlin section

Check kotlin section

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REQUEST_CODE_SHARE) {
        val json = data.extras?.getString("response")
        val response = Gson().fromJson(json, ShareResponse::class.java)
    }
}

ShareResponse.kt

Check kotlin section

Check kotlin section

data class ShareResponse(
    @SerializedName("status")
    var status: String?
)

Parameters	Type	Description
status	String	ok / ko

android-Fetch transactions

Request

To fetch transaction from the terminal by Intent, use this code:

Check kotlin section

Check kotlin section

val request = TransactionsRequest(
  startDate = "2022-01-01",
  endDate = "2022-02-01",
  startTime = "00:00:00",
  endTime = "23:59:59",
  limit = 50
)

val jsonData = Gson().toJson(request)
val queryParams = Uri.encode(jsonData)

val intent = Intent(Intent.ACTION_VIEW).apply {
  data = Uri.parse("yavin://com.yavin.macewindu/v4/transactions?data=$queryParams")
}

startActivityForResult(intent, REQUEST_CODE_TRANSACTIONS)

TransactionsRequest.kt

Check kotlin section

Check kotlin section

data class TransactionsRequest(
    @SerializedName("startDate")
    var startDate: String? = null,
    @SerializedName("endDate")
    var endDate: String? = null,
    @SerializedName("startTime")
    var startTime: String? = null,
    @SerializedName("endTime")
    var endTime: String? = null,
    @SerializedName("limit")
    var limit: Int? = 20,
    @SerializedName("offset")
    var offset: Int? = 0,
)

Parameters	Type	Default	Description
startDate	String	(optional)	Start date (yyyy-MM-dd format)
endDate	String	(optional)	End date (yyyy-MM-dd format) Note: is exclusive
startTime	String	(optional)	Start time (hh:mm:ss format)
endTime	String	(optional)	End time (hh:mm:ss format)
limit	Integer	20	Limit of the number of transactions to receive with a request (max = 200)
offset	Integer	0	Offset of transactions in the request

By default, if no date/time filters are set then the last 30 days are fetched.

Response

To get response :

Check kotlin section

Check kotlin section

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REQUEST_CODE_TRANSACTIONS) {
        val json = data.extras?.getString("response")
        val response = Gson().fromJson(json, TransactionsResponse::class.java)
    }
}

TransactionsResponse.kt

Check kotlin section

Check kotlin section

data class TransactionsResponse(
    @SerializedName("total")
    var total: Int? = null,
    @SerializedName("count")
    var count: Int? = null,
    @SerializedName("limit")
    var limit: Int? = null,
    @SerializedName("offset")
    var offset: Int? = null,
    @SerializedName("transactions")
    var transactions: List<ItemTransactionResponse>? = null
)

Where ItemTransactionResponse is :

data class ItemTransactionResponse(
    @SerializedName("appVersion")
    var appVersion: String? = null,
    @SerializedName("createdAt")
    var createdAt: String? = null,
    @SerializedName("amount")
    var amount: Int? = null,
    @SerializedName("giftAmount")
    var giftAmount: Int? = null,
    @SerializedName("status")
    var status: String? = null,
    @SerializedName("currencyCode")
    var currencyCode: String? = null,
    @SerializedName("transactionId")
    var transactionId: String? = null,
    @SerializedName("scheme")
    var scheme: String? = null,
    @SerializedName("issuer")
    var issuer: String? = null,
    @SerializedName("cartId")
    var cartId: String? = null,
    @SerializedName("transactionType")
    var transactionType: String? = null,
    @SerializedName("reference")
    var reference: String? = null,
    @SerializedName("customer")
    var customer: Customer? = null
)

Parameters	Type	Description
status	String	[ok / ko] Transaction successful or not
transactionId	String	Transaction id
amount	Integer	Amount in cents. 1€ => 100. Does not include tips
giftAmount	Integer	Tips or donation in cents
currencyCode	String	Currency Code as ISO 4217 in which the payment will be done (available with activation)
issuer	String	Issuer of the payment
scheme	String	Network used to validate the transaction (CB,CBSC (contactless),VISA,MASTERCARD,CONECS...)
transactionType	String	debit = classical card transaction. reversal = reversal of a payment refund = refund to a customer (not linked to previous payment) [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer	See object Customer
reference	String	Free field that the merchant can see in his My Yavin backoffice
cartId	String	Cart id associated to the transaction
appVersion	String	Yavin Pay app version
createdAt	String	Datetime of the transactions at UTC timezone (ex: 2022-10-21T12:45:30.000Z)

Customer.kt

Check kotlin section

Check kotlin section

data class Customer(
    @SerializedName("email")
    var email: String?,
    @SerializedName("firstName")
    var firstName: String?,
    @SerializedName("lastName")
    var lastName: String?,
    @SerializedName("phone")
    var phone: String?
)

android-transactions-Customer

Parameters	Type	Description
email	String	Email
firstName	String	First name
lastName	String	Last name
phone	String	Phone number

android-Read NFC tag via Yavin Pay

The purpose of this document is to describe how to get NFC tag data from yavinPay. This feature able you to retrieve tag serial number for cashless application for example.

The api timeout after 1 minute 30 seconds by default.

Request

The parameters for this request are optional, for now you can just control the timeout and a customizable text to display when reading the card.

To trigger NFC Reader by Intent, use this code:

Check kotlin section

Check kotlin section

val request = NFCReaderRequestV4(10000, "Pass your card here)
val jsonData = Gson().toJson(request)
val queryParams = Uri.encode(jsonData)

val intent = Intent(Intent.ACTION_VIEW).apply {
    val url = StringBuilder("yavin://com.yavin.macewindu/v4/nfc-reader").apply {
        append("?data=$queryParams") // optionnal
    }

    data = Uri.parse(url.toString())
}

startActivityForResult(intent, REQUEST_CODE_READ)

NFCReaderRequestV4.kt

Check kotlin section

Check kotlin section

data class NFCReaderRequestV4(
    @SerializedName("timeout")
    val timeout: Long,
    @SerializedName("readerIncentive")
    val readerIncentive: String
)

Parameters	Type	Default	Description
timeout	Long	90000	timeout for reading in milliseconds. Must be above 10000
readerIncentive	String		text to display when reading card

Response

To get the response :

Check kotlin section

Check kotlin section

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REQUEST_CODE_READ) {
        // handle post read response from Yavin PAY
        val json = data.extras?.getString("response")
        val response = Gson().fromJson(json, NFCReadResponse::class.java)
    }
}

NFCReadResponse.kt

Check kotlin section

Check kotlin section

data class NFCReadResponse(
    @SerializedName("status")
    val status: Boolean,
    @SerializedName("tagInfo")
    var tagInfo: TagInfo?
)

Parameters	Type	Default	Description
status	Boolean	(mandatory)	Tell if the reading is successful: true or false
tagInfo	TagInfo		Hold the tag info, for now only the serial number is available.

TagInfo.kt

Check kotlin section

Check kotlin section

data class TagInfo(
    @SerializedName("serialNumber")
    var serialNumber: String
)

android-nfc-TagInfo

Parameters	Type	Description
serialNumber	String	Represent the tag serial number

Ecommerce

The API ecommerce provided a payment link which can then be used to redirect a user to a customisable payment screen.

The displayed payment page will provide some additional information to the user (this could, for instance, be an itemised breakdown of the order). Upon successful payment, or cancellation by the user, a response is sent to a specified return url with the status of the payment. If the payment is unsuccessful the customer will be given the opportunity to try again.

ecommerce-Flow

1. User selects item(s) on your website and clicks on button to pay, notifying your server or intent.
2. Your server handles the request and makes an api call to generate a payment link
3. Yavin server generates a unique payment link and sends it in response.
4. Your server sends redirect response to the user's client, redirecting them to the payment link url (Yavin powered page)
5. Customer is presented with a widget to provide their payment information and make the payment
6. The payment is processed and a response is sent to your server at the return url supplied, with a cartId and status in the query params.
7. Your server handles response and displays relavent information to the user.

ecommerce-Authentification

curl -XPOST "https://api.yavin.com/api/v4/generate_ecommerce_link/" \
  --header 'Yavin-Secret: YAVIN_API_KEY' \
  --data '{
  ...
}'

import requests

url = 'https://api.yavin.com/api/v4/generate_ecommerce_link/'
headers = {
  'Content-Type': 'application/json',
  'Yavin-Secret': 'YAVIN_API_KEY'
}

params = {
    ...
}

r = requests.post(url=url, json=params, headers=headers)

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, your API key must be in the headers of the POST request:

ecommerce-Errors

The Yavin API uses the following error codes:

Code	Explication
400	Bad Request -- The request is invalid.
401	Unauthorized -- The API key is invalid or the endpoint cannot be access with this API key
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.

ecommerce-Requesting a payment link

Requesting a payment link is very straight forward to initially get setup as there are only 3 required parameters in the body. However, there are numerous optional parameters which can be used to provide extra information to the user.

POST https://api.yavin.com/api/v4/generate_ecommerce_link/

Parameters	Type	Default	Description
cartId	String	required	The ID which references this particular order. This will be sent as a reference in the response to the return url after a successful/failed payment.
returnUrl	String	required	Will be appended with queries cartId and status [The status can be either ‘ok’ for a successful payment, or ‘ko’ for a cancelled payment. Please note that a ‘ko’ response does not mean a failed payment as the customer will always be given the chance to try again. Therefore a ‘ko’ response comes from a cancellation (most like triggered by the customer)].
amount	Number	required	The amount which the customer needs to pay (value in cents)
message	String	optional	This allows you to display a custom message to the user (typically will be additional information or a “thank-you” message)
currency	String	optional	In ISO 4217 format, used to communicate which currency the customer is paying in, to ensure the correct format is displayed to the end user. If no currency is provided the default will be € euros.
datetime	String	optional	A datetime object with timezone
vendor	vendor	optional	This information can be used for multiple purposes. It will be used primarily for displaying information to the end user, as well as helping with debugging purposes.
customer	customer	optional	Used for providing information about the customer to display customised messages
items	Array/List of item	optional	Used for displaying an itemised breakdown of what the customer is paying for

Breakdown of objects/dictionaries

item

item = {
  "name": "Big Burger Menu",
  "category": "food",
  "freeNote": "no tomato",
  "quantity": 3,
  "unitPrice": 1000,
  "totalAmount": 3000,
  "eligibleTitreRestaurant": True,
  "tax": {
    "amount": 30,
    "rate": 1000
  }
}

Parameters	Type	Default	Description
name	String	required	The main description of the item
totalAmount	Number	required	The total value of item (unitPrice x quantity)
category	String	optional	Can be used to categorised your products
eligibleTitreRestaurant	Boolean	optional	The item is eligible to french restaurant vouchers
freeNote	String	optional	Can be used to communicate something about the item to the user, or be a customer request
quantity	Number	optional	Quantity of this particular item requested
unitPrice	Number	optional	The value of specific item. A negative value will dispaly that line in red
tax	tax	optional	Used for displaying tax breakdown of item. Must provide amount as cents and rate as a decimal percentage
items	Array/List of item	optional	A list of 'items', which are the same objects as this one

vendor

vendor = {
  "legalName": "Yavin SA",
  "brandName": "Yavin",
  "country": "FR",
  "merchantId": "123456789",
  "merchantCategoryCode": "string",
  "softwareName": "Shopify",
  "softwareVersion": "1.0.1",
  "store": {
    "storeId": "12345678900012",
    "address": {
      "address": "58 Avenue de la Victoire",
      "postcode": 75009,
      "city": "Paris"
    }
  }
}

Parameters	Type	Default	Description
brandName	String	required	The company name as known publicly
legalName	String	optional	The company name known legally
country	String	optional	ISO 3166-2
merchantId	String	optional	The merchant's identification number, for instance in France it would be the "Siren"
merchantCategoryCode	String	optional	The merchant's category code, for instance in France it would be the "Code NAF"
softwareName	String	optional	If integrated into a software, such as a POS, this can be useful information for debugging.
softwareVersion	String	optional	If integrated into a software, such as a POS, this can be useful information for debugging.
store	store	optional	The associated store's information. If provided, all options in the object are required. The storeId (this would be the "Siret" in France) and an address object containing address, postcode, and city which will be formatted by Yavin.

customer

customer = {
  "firstName": "Luke",
  "lastName": "Skywalker",
  "email": "luke@yavin.com",
  "telephone": "06123456789",
  "address": "58 Rue de Paris",
  "city": "Paris",
  "postcode": "75009"
}

Parameters	Type	Default	Description
firstName	String	required	Customer first name
lastName	String	required	Customer last name
email	String	optional	Customer email
telephone	String	optional	Customer phone number
address	String	optional	Customer address residence's address
city	String	optional	Customer residence's city
postcode	String	optional	Customer residence's post code

Store

store = {
  "storeId": "12345678900012",
  "address": {
    "address": "58 Avenue de la Victoire",
    "postcode": 75009,
    "city": "Paris"
  }
}

Parameters	Type	Default	Description
storeId	String	required	SIREN number of your point of sale
address	address	required	Object containing information related to the point of sale

Address

Parameters	Type	Default	Description
address	String	required	Address of the point of sale
postcode	String	required	Post Code of the point of sale
city	String	required	City of the point of sale

tax

tax = {
  "amount": 120,
  "rate": 0.1
}

Parameters	Type	Default	Description
amount	integer	required	Tax amount in cts
rate	decimal integer	required	Tax rate

Example

import requests

url = 'https://api.yavin.com/api/v4/generate_ecommerce_link/'

headers = {
  'Content-Type': 'application/json',
  'Yavin-Secret': 'YAVIN_API_KEY'
}

params = {
  "cartId": "12345678901234567890",
  "amount": 2000,
  "returnUrl": "https://my.yavin.com/api/payment_response",
  "currency": "EUR",
  "datetime": "2023-02-10T13:59:44.258Z",
  "message": "Thank you for your confidence and for shopping with us. Please find your order details below:",
  "vendor": {
    "legalName": "Yavin SA",
    "brandName": "Yavin",
    "country": "FR",
    "merchantId": "123456789",
    "merchantCategoryCode": "string",
    "softwareName": "Shopify",
    "softwareVersion": "1.0.1",
    "store": {
      "storeId": "12345678900012",
      "address": {
        "address": "58 Avenue de la Victoire",
        "postcode": 75009,
        "city": "Paris"
      }
    }
  },
  "customer": {
    "firstName": "Luke",
    "lastName": "Skywalker",
    "email": "luke@yavin.com",
    "telephone": "06123456789",
    "address": "58 Rue de Paris",
    "city": "Paris",
    "postcode": "75009"
  },
  "items": [
    {
      "name": "Big Burger Menu",
      "category": "food",
      "freeNote": "no tomato",
      "quantity": 3,
      "unitPrice": 1000,
      "totalAmount": 3000,
            "eligibleTitreRestaurant": True,
      "tax": {
        "amount": 30,
        "rate": 1000
      },
      "items": [
        {
          # subitems if there are any (nested "items")
        }
      ]
    }
  ]
}

r = requests.post(url=url, json=params, headers=headers)