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
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:
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. |
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 paymentrefund = 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 |
Customer
Parameters | Type | Default | Description |
---|---|---|---|
String | |||
firstName | String | First name | |
lastName | String | Last name | |
phone | String | Phone number international format starting with + symbol (e.g: +33612345678) |
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
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 |
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 |
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 |
Customer
Parameters | Type | Default | Description |
---|---|---|---|
String | |||
firstName | String | First name | |
lastName | String | Last name | |
phone | String | Phone number international format starting with + symbol (e.g: +33612345678) |
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 |
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 paymentrefund = 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. |
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 :
16
st letter of the alphabet - A :
1
st letter of the alphabet - Y :
25
st letter of the alphabet
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 |
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 paymentrefund = 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
Parameters | Type | Default | Description |
---|---|---|---|
String | |||
firstName | String | First name | |
lastName | String | Last name | |
phone | String | Phone number international format starting with + symbol (e.g: +33612345678) |
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
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 paymentrefund = 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 |
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 |
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 |
Customer
Parameters | Type | Default | Description |
---|---|---|---|
String | |||
firstName | String | First name | |
lastName | String | Last name | |
phone | String | Phone number international format starting with + symbol (e.g: +33612345678) |
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 |
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 paymentrefund = 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
Parameters | Type | Description |
---|---|---|
String | ||
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.
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)
TransactionRequest request = new TransactionRequest();
request.amount = 100;
request.customer = new Customer("John", "Doe", "john@yavin.com");
request.vendor = new Vendor("Awesome Partner", "1.2.3");
request.receiptTicket = new ReceiptTicket("This is a wonderful\n receipt ticket to print", "text");
request.receiptTicketJson = new JSONObject("{\"transactionId\": \"123456\", \"amount\": 3500 }").toString();
String queryParams = new Gson().toJson(request);
Uri uri = Uri.parse("yavin://com.yavin.macewindu/v4/payment?data=" + queryParams);
Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(uri);
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 paymentrefund = 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?
)
Customer
Parameters | Type | Default | Description |
---|---|---|---|
String | |||
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?
)
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?
)
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 paymentrefund = 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 |
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 |
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?
)
Customer
Parameters | Type | Default | Description |
---|---|---|---|
String | |||
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?
)
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 |
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 paymentrefund = 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?
)
Customer
Parameters | Type | Description |
---|---|---|
String | ||
firstName | String | First name |
lastName | String | Last name |
phone | String | Phone number |
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
)
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.
Flow
- User selects item(s) on your website and clicks on button to pay, notifying your server of intent.
- Your server handles the request and makes request to Yavin api to generate a payment link
- Yavin server generates a unique payment link and sends it in the response.
- Your server sends redirect response to the user's client, redirecting them to the payment link url (Yavin powered page)
- Customer is presented with a widget to provide their payment information and make the payment
- 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.
- Your server handles response and displays relavent information to the user.
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:
Responses
This API provides 2 types of responses:
- Synchronous: This is the initial response when requesting a payment link, which contains the payment link to forward the client to.
- Asynchronous This is the response sent to the returnUrlSuccess / returnUrlCancelled. These notification urls are called either when a successful payment has been made, or if a payment link has been cancelled
Both notification url responses provide the cartId in the query params (i.e. https://mydomain/yavinPaymentLink/success?cartId=abcde12345) to be used as reference.
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. |
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.
NOTE:
Every numeric variable is an integer
NOTE:
Every amount is in cents
Request
Production Environment:
POST https://api.yavin.com/api/v4/generate_ecommerce_link/
Sandbox Environment:
POST https://api.sandbox.yavin.com/api/v4/generate_ecommerce_link/
Parameters
R
indicates a required parameter.O
indicates an optional parameter.
Parameters | Type | Description | |
---|---|---|---|
cartId | String | R | A unique ID which references this particular order. This is usually an internal reference ID, and will be sent as a query param in the response to the return URL after a successful/cancelled payment. |
webhookUrl | String | R | A URL that gets called whenever a transaction is made. For instance, if the customer pays with both a meal voucher and a bank card, the webhook is called twice, once for each transaction. |
returnUrlSuccess | String | R | Will be appended with param query cartId for reference. |
returnUrlCancelled | String | R | Will be appended with queries cartId for reference. Please note that a response to this URL does not mean a failed payment as the customer will always be given the chance to try again. Therefore, a response to this URL comes from a cancellation (most likely triggered by the customer). |
amount | Number | R | The total amount which the customer needs to pay (value in cents) |
clientReference | String | O | A public reference number which is communicated to the customer |
amountWithoutTax | Number | O | The amount which the customer needs to pay before tax has been applied (value in cents) |
taxAmount | Number | O | The amount of tax applied to the transaction (value in cents) |
message | String | O | This allows you to display a custom message to the user (typically will be additional information or a “thank-you” message) |
currency | String | O | 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 | O | A datetime object with timezone |
vendor | vendor | O | 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 | O | Used for providing information about the customer to display customized messages |
items | Array/List of item | O | Used for displaying an itemized breakdown of what the customer is paying for |
features | feature | O | Used for enabling/disabling features proposed by Yavin |
Responses
Generate Payment Link
When making a POST request for a payment link, the response will be in JSON as follows:
response = {
"payment_link": "https://yav.in/acde123"
}
returnUrlCancelled & returnUrlSuccess
These two parameters are used for redirecting the users once a payment has been paid in full or cancelled. These are GET
requests with the cartId and status included in the query params.
- There is no concept of a failed payment since users will always have the opportunity to try again. In the event of an order cancellation, the returnUrlCancelled
will be invoked.
successful_response = "https://yavin.com/successfulPayment?cartId=abcde12345&status=ok"
cancelled_response = "https://yavin.com/cancelledPayment?cartId=abcde12345&status=ko"
webhook
If a webhook url is provided, this endpoint will be hit using a POST request with a dictionary in the body containing pertinent information relating to the order. - If a webhook has been provide, a POST request will be made to this endpoint each time a transaction occurs, whether for the full or partial amount
key | Type | Description |
---|---|---|
cart_id | string | This is the cart_id you have provided in the original request |
amount_requested | Interger | The amount requested in the original request, in cents |
amount_paid | Interger | The total amount paid by the customer, in cents |
tip_amount | Interger | The amount of tip left by the customer (if activated), in cents |
status | ok ko pending |
The status of the requested order. Possible values are: ok (order has been paid), ko (order has been cancelled), and pending (order is still active but not yet paid in full). |
transactions | List of transaction | A list of dictionaries containing information relating to any payments made for this order |
body = {
"cart_id": "abcde123",
"amount_requested": 1000,
"amount_paid": 1200,
"tip_amount": 200,
"status": "ok",
"transactions": [
{
"amount_paid": 1200,
"currency_code": "EUR",
"date_of_payment": "2023-09-01 15:10:29",
"gateway": "cb",
"issuer": "SODEXO PASS FRANCE",
"transaction_id": "abc123def456",
"pan": "507599******1234"
}
]
}
Breakdown of objects/dictionaries
item
Parameters | Type | Description | |
---|---|---|---|
name | String | R | The main description of the item |
totalAmount | Number | R | The total value of item (unitPrice x quantity) |
totalAmountWithoutTax | Number | O | The total value of item before tax has been applied(unitPriceWithoutTax x quantity) |
category | String | O | Can be used to categorised your products |
eligibleTitreRestaurant | Boolean | O | The item is eligible to french restaurant vouchers |
freeNote | String | O | Can be used to communicate something about the item to the user, or be a customer request |
quantity | Number | O | Quantity of this particular item (how many of the items are being charged) requested |
unitPrice | Number | O | The value of specific item. A negative value will display that line in red |
unitPriceWithoutTax | Number | O | The value of specific item (before tax has been applied). A negative value will display that line in red |
tax | tax | O | Used for displaying tax breakdown of item. Must provide amount as cents and rate as a decimal percentage |
items | Array/List of item | O | A list of 'items', which are the same objects as this one |
item = {
"name": "Big Burger Menu",
"category": "food",
"freeNote": "no tomato",
"quantity": 3,
"unitPrice": 1000,
"unitPriceWithoutTax": 900,
"totalAmount": 3000,
"totalAmountWithoutTax": 2700,
"eligibleTitreRestaurant": True,
"tax": {
"amount": 300,
"rate": 1000 // =10.00%
}
}
vendor
Parameters | Type | Description | |
---|---|---|---|
brandName | String | R | The company name as known publicly |
legalName | String | O | The company name known legally |
country | String | O | ISO 3166-2 |
merchantId | String | O | The merchant's identification number, for instance in France it would be the "Siren" |
merchantCategoryCode | String | O | The merchant's category code, for instance in France it would be the "Code NAF" |
softwareName | String | O | If integrated into a software, such as a POS, this can be useful information for debugging. |
softwareVersion | String | O | If integrated into a software, such as a POS, this can be useful information for debugging. |
store | store | O | 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. |
vendor = {
"legalName": "Yavin SA",
"brandName": "Yavin",
"country": "FR",
"merchantId": "123456789",
"merchantCategoryCode": "6201Z",
"softwareName": "Shopify",
"softwareVersion": "1.0.1",
"store": {
"storeId": "12345678900012",
"address": {
"address": "58 Avenue de la Victoire",
"postcode": 75009,
"city": "Paris"
}
}
}
Customer
Parameters | Type | Description | |
---|---|---|---|
firstName | String | R | Customer first name |
lastName | String | R | Customer last name |
String | O | Customer email | |
telephone | String | O | Customer phone number |
address | String | O | Customer address residence's address |
city | String | O | Customer residence's city |
postcode | String | O | Customer residence's post code |
customer = {
"firstName": "Luke",
"lastName": "Skywalker",
"email": "luke@yavin.com",
"telephone": "06123456789",
"address": "58 Rue de Paris",
"city": "Paris",
"postcode": "75009"
}
Feature
By default, all features subscribed to by your company in MyYavin will be active. If you wish to deactivate a feature, you can do so by setting its value to False.
Parameters | Type | Default | Description |
---|---|---|---|
tips | boolean | True | Whether or not to allow the client to leave a tip |
customerContacts | boolean | True | Whether or not to ask the client to leave their contact details. Can be useful for generating marketing campaigns |
mealVouchers | boolean | True | Will propose the option to pay with meal voucher (if contract exists for your company) |
customer = {
"tips": True,
"customerContacts": True,
"mealVouchers": True
}
Store
Parameters | Type | Description | |
---|---|---|---|
storeId | String | R | SIREN number of your point of sale |
address | address | R | Object containing information related to the point of sale |
store = {
"storeId": "12345678900012",
"address": {
"address": "58 Avenue de la Victoire",
"postcode": 75009,
"city": "Paris"
}
}
Address
Parameters | Type | Description | |
---|---|---|---|
address | String | R | Address of the point of sale |
postcode | String | R | Post Code of the point of sale |
city | String | R | City of the point of sale |
Tax
Parameters | Type | Description | |
---|---|---|---|
amount | integer | R | Tax amount in cts |
rate | decimal integer | R | Tax rate |
tax = {
"amount": 120,
"rate": 0.1
}
Transaction
Parameters | Type | Description |
---|---|---|
amount_paid | integer | Amount which has been paid in cents |
currency_code | string | The currency code in ISO-4217 format (i.e. EUR ) |
date_of_payment | string | The date and time the payment was made. The datetime will string will be provided in the following format YYYY-MM-DD HH:MM:SS and is in GMT |
gateway | cb conecs edenred |
The gateway of the transaction that has been made. |
issuer | string | The name of the card's issuer |
transaction_id | string | Unique ID for the this transaction |
pan | string | The first and last numbers of the card used joined by asterix characters |
transaction = {
"amount_paid": 899,
"currency_code": "EUR",
"date_of_payment": "2023-09-01 15:10:29",
"gateway": "cb",
"issuer": "SODEXO PASS FRANCE",
"transaction_id": "abc123def456",
"pan": "507599******1234"
}
Example
import requests
url = 'https://api.yavin.com/api/v4/generate_ecommerce_link/'
headers = {
'Content-Type': 'application/json',
'Yavin-Secret': 'YAVIN_API_KEY'
}
data = {
"cartId": "12345678901234567890",
"amount": 3000,
"amountWithoutTax": 2700,
"taxAmount": 300,
"returnUrlSuccess": "https://my.yavin.com/api/payment_response/success",
"returnUrlCancelled": "https://my.yavin.com/api/payment_response/cancelled",
"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"
}
}
},
"features": {
"tips": True,
"customerContacts": False
},
"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,
"unitPriceWithoutTax": 900,
"totalAmount": 3000,
"totalAmountWithoutTax": 2700,
"eligibleTitreRestaurant": True,
"tax": {
"amount": 300,
"rate": 1000
},
"items": [
{
# subitems if there are any (nested "items")
}
]
}
]
}
r = requests.post(url=url, json=params, headers=headers)