Introduction

Bienvenue sur la documentation API Yavin !

Elle permet d'intégrer facilement les fonctionnalités de votre TPE Android Yavin X avec une API REST ou Android Intent, par exemple pour lancer un paiement ou une impression depuis votre caisse.

Il existe 3 niveaux d'intégration API pour initier un paiement:

• API Cloud (doc)

Avantage: Le TPE peut utiliser une carte SIM 3G/4G pour se connecter à la banque.

Inconvénient : La réponse est asynchrone vers une IP publique.

Cas d'usage type : Caisse SaaS web.

Vous pourrez aussi utiliser cette API pour extraire les informations de votre backoffice My Yavin, par exemple pour connecter votre logiciel de comptabilité.

• API Local (doc)

Avantage : La requête HTTP est synchrone (ouverte jusqu'à 5 minutes soit le temps du paiement).

Inconvénient : Le TPE doit être connecté au réseau local avec une IP fixe (petite manipulation dans les paramètres Android). Le réseau local doit avoir une connexion internet stable.

Cas d'usage type : Caisse embarquée sans synchronisation web par websocket.

• API Android Intent (doc)

Avantage : La caisse est embarquée directement sur le TPE.

Inconvénient : Il faut programmer sur mobile (Java/Kotlin/react native...) et l'APK doit être approuvé par le constructeur du TPE.

Cas d'usage type : Caisse sur smartphone (prise de commande à table, food truck, commerçant ambulant).

Si vous avez une app Android, et que vous souhaitez le déployer directement sur les TPE Yavin, c'est possible :) Contactez nous pour forger un partenariat.

Login / Identification

Afin de pouvoir utiliser les API, il faut s'assurer que le commerçant soit identifié dans l'application.

Concernant l'API local et l'API Android Intent, il faut s'identifier manuellement au sein de l'app avec les mêmes identifiants que l'accès à My Yavin https://my.yavin.com.

Pour l'API Cloud l'identification se fait grâce au token Yavin.

API Cloud

cloud-Identification

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 utilise une clé d'API pour restreindre l'accès aux données et services aux utilisateurs ayant droit. Vous pouvez trouver votre clé d'API sur my.yavin.com dans l'onglet API.

Toutes les requêtes doivent être identifiées. Pour ce faire, renseigner votre clé d'API dans les headers de la requête POST:

cloud-Erreurs

L'API Yavin utilise les codes d'erreur suivants :

Code	Explication
400	Bad Request -- La requête est invalide.
401	Unauthorized -- La clé d'API n'est pas valide ou le terminal n'est pas accessible avec la clé d'API
404	Not Found -- Le lien n'existe pas.
405	Method Not Allowed -- Vous essayez d'accéder à un lien avec une methode HTTP invalide.
500	Internal Server Error -- Il y a un problème avec notre serveur. Ré-essayez plus tard. Contactez le service client si le problème persiste.

cloud-Effectuer une transaction

Cette API est utilisée pour lancer un paiement sur un terminal Yavin via le framework HTTP REST. Elle fonctionnera donc depuis un ordinateur, une tablette iPad ou Android, ou n'importe quel objet connecté à internet.

Requête

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)

Paramètres	Type	Défaut	Description
serialNumber	String	(obligatoire)	Numéro de série du terminal. Il peut être trouvé à l'arrière du terminal avec l'acronyme S/N.
amount	Integer		Montant à payer en centimes. 1€ => 100. Ce montant n'inclut pas les pourboires. Ce montant doit toujours être positif, même pour les annulation (transactionType=Reversal) et remboursements (transactionType=Refund)
giftAmount	Integer	0	Pourboires en centimes
medium	String	card	card = transaction classique par carte. (D'autres méthodes de paiement seront bientôt disponibles). [card, qrcode, 2x, 3x, 4x,ancv, wechat, alipay, lydia, restoflash,...]
transactionType	String	debit	debit = transaction classique par carte. reversal = annulation d'un paiement. refund = remboursement [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer		Pré-remplissage des infos client pour un envoi du ticket pas SMS ou email. Voir l'objet Customer
vendor	Vendor		Infos relatives à l'éditeur de logiciel pour l'identifier. Voir l'objet Vendor
reference	String		Champ libre que le marchand pourra voir sur son back office My Yavin
receiptTicket	ReceiptTicket		Infos pour imprimer le ticket de caisse en meme temps que le ticket CB. Voir l'objet ReceiptTicket
receiptTicketJson	Objèt Ecommerce		Prend un objet json contenant les mêmes données que celles requises pour l'api du ecommerce.
cartId	String		Numéro de panier associé à la transaction. Cela pourra être utile pour associer une transaction et un ticket de caisse si le ticket de caisse n'a pas été renseigné initialement

cloud-payment-Customer

Paramètres	Type	Défaut	Description
email	String		Email du client
firstName	String		Prénom du client
lastName	String		Nom du client
phone	String		Téléphone du client au format international commençant par le symbôle + (ex: +33612345678)

cloud-payment-ReceiptTicket

Paramètres	Type	Défaut	Description
format	String	text	Format de texte à imprimer. Valeurs possible : [text, escpos]
data	String		Le ticket de caisse à imprimer. Si format = text, data est imprimé tel quel. Si format = escpos, alors data doit être la sortie ESCPOS encodée au format hexa string (ex: 1b401d6210...). Nous supportons l'ESCPOS en Android, Javascript, Python, voir les exemples sur notre github Yavin

cloud-payment-Vendor

Paramètres	Type	Défaut	Description
softwareName	String		Nom de l'éditeur de caisse
softwareVersion	String		Version de l'éditeur de caisse. Cela sera utile pour identifier les éventuels bugs rapidement

Réponse

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

Paramètres	Type	Description
status	String	ok si la transaction a bien été reçue. Sinon ko
transactionId	String	id unique de la transaction

Réponse Webhook

{
  "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 si la transaction a bien été reçue. Sinon ko
trs_id	String	id unique de la transaction
app_version	String	Version de l'app Yavin Pay
asked_amount	Integer	Montant à payer en centimes. 1€ => 100
gift_amount	Integer	Pourboires en centimes
total_amount	Integer	Montant total de la transaction (= gift_amount + asked_amount)
cartId	String	Numéro de panier associé à la transaction. Cela pourra être utile pour associer une transaction et un ticket de caisse si le ticket de caisse n'a pas été renseigné initialement
client_ticket	String	Ticket client CB de la transaction
company_ticket	String	Ticket marchand CB de la transaction
receipt_ticket	ReceiptTicket	Infos pour imprimer le ticket de caisse en meme temps que le ticket CB. Voir l'objet ReceiptTicket
currencyCode	String	Code ISO 4217 de la devise dans laquelle s'effectuera le paiement (disponible uniquement sur activation)
device_datetime	String	Date et heure du terminal à laquelle la transaction a été effectuée
device_timestamp	String	Timestamp du terminal
medium	String	card = transaction classique par carte. (D'autres méthodes de paiement seront bientôt disponibles). [card, qrcode, 2x, 3x, 4x,ancv, wechat, alipay, lydia, restoflash,...]
reference	String	Champ libre que le marchand pourra voir sur son back office My Yavin
serial_number	String	Numéro de série du terminal
server_timestamp	String	Timestamp du serveur
type	String	debit = transaction classique par carte. reversal = annulation d'un paiement. [debit, reversal, preauthorisation, closingbatch]
vendor	Vendor	Infos relatives à l'éditeur de logiciel pour l'identifier. Voir l'objet Vendor

cloud-Imprimer un ticket de caisse

Requête

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)

Paramètres	Type	Défaut	Description
serialNumber	String	(obligatoire)	Numéro de série du terminal. Il peut être trouvé à l'arrière du terminal avec l'acronyme S/N.
format	String	text	Format de texte à imprimer. Valeurs possible : [text, escpos]
data	String	(obligatoire)	Le texte à imprimer. Si format = text, data est imprimé tel quel. Si format = escpos, alors data doit être la sortie ESCPOS encodée au format hexa string (ex: 1b401d6210...). Nous supportons l'ESCPOS en Android, Javascript, Python, voir les exemples sur notre github Yavin

Réponse

{
  "status": "ok"
}

Réponse	Type	Description
status	String	ok / ko

cloud-Partager un ticket de caisse

Cette API permet de partager un ticket de caisse via une méthode spécifique (par email, sms, impression papier). Si les champs du client Customer sont présents dans la requête, le ticket lui sera partager directement. Autrement le champ nécessaire lui sera demander par le 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	Défaut	Description
serialNumber	String	(obligatoire)	Numéro de série du terminal. Il peut être trouvé à l'arrière du terminal avec l'acronyme S/N.
receiptTicket	ReceiptTicket	(obligatoire)	Ticket de caisse à partager. Voir ReceiptTicket
transactionId	String	(obligatoire)	Identifiant de la transaction associé au ticket de caisse à envoyer. L'identifiant doit être celui reçu via l'API Payment
medium	String	yavin	La méthode utilisée pour partager le ticket de caisse. Les valeurs possible sont [sms, email, print]. Si yavin alors nous stockerons et enverrons le ticket de caisse au client suivant ses préférences de notifications
customer	Customer		Pré-remplissage des infos client pour un envoi du ticket pas SMS ou email. Voir l'objet Customer

cloud-share-Customer

Paramètres	Type	Défaut	Description
email	String		Email du client
firstName	String		Prénom du client
lastName	String		Nom du client
phone	String		Téléphone du client au format international commençant par le symbôle + (ex: +33612345678)

cloud-share-ReceiptTicket

Paramètres	Type	Défaut	Description
format	String	text	Format de texte à partager. Valeurs possible : [text, escpos]
data	String		Le ticket de caisse à partager. Si format = text, data est imprimé tel quel. Si format = escpos, alors data doit être la sortie ESCPOS encodée au format hexa string (ex: 1b401d6210...). Nous supportons l'ESCPOS en Android, Javascript, Python, voir les exemples sur notre github Yavin

Response

{
  "status": "ok"
}

Parameters	Type	Description
status	String	ok / ko

cloud-Récupérer les 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)

La requête ci-dessus retourne le JSON ci-dessous :

{
    "total": 356,
    "limit": 100,
    "offset": 0,
    "count": 100,
    "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",
            "serialNumber": "123456789"
        },
        {
            "amount": 100,
            "createdAt": "2022-05-10T14:08:25",
            "customer": {},
            "giftAmount": 0,
            "issuer": "EDENRED",
            "reference": "",
            "scheme": "CB",
            "status": "ok",
            "transactionId": "8tPuSUIN6AaP",
            "type": "debit",
            "serialNumber": "123456789"
        },

      ...
    ]
}

Requête

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

Paramètres	Type	Défaut	Description
serialNumbers	Liste de String	(optionnel)	Liste des numéros de série des terminal. Il peut être trouvé à l'arrière du terminal avec l'acronyme S/N.
timezone	String	(optionnel)	ID de la Timezone de l'appelant (ex: "Europe/Paris"). Nous recommandons fortement à renseigner la timezone pour obtenir des données correctes
startDate	String	(optionnel)	Date de début (yyyy-MM-dd format)
endDate	String	(optionnel)	Date de fin (yyyy-MM-dd format) Note: est exclusive
startTime	String	(optionnel)	Heure de début (hh:mm:ss format)
endTime	String	(optionnel)	Heure de fin (hh:mm:ss format)
limit	Integer	20	Limite du nombre de transactions à recevoir par requête (max = 200)
offset	Integer	0	Décalage dans les transactions requêtées

Par défaut, si aucun paramètre de date / temps n'est indiqué, les 30 derniers jours sont pris en compte.

Réponse

Une transaction contient les champs suivant : (voir l'exemple pour le format de la réponse)

Parameters	Type	Description
status	String	[ok / ko] Transaction réussie ou non
transactionId	String	Identifiant unique de la transaction
amount	Integer	Montant en centime de la transaction. N'inclut pas les pourboires
giftAmount	Integer	Montant en centime de la transaction du pourboires
currencyCode	String	Devise de la transaction en ISO 4217
issuer	String	Emetteur du paiement
scheme	String	Réseau utilisé pour valider la transactiosn (CB,CBSC (contactless),VISA,MASTERCARD,CONECS...)
transactionType	String	debit = paiement. reversal = annulation refund = remboursement [debit, reversal, refund, preauthorisation, closingbatch]
reference	String	Réference de la transaction, visible sur le My Yavin backoffice
cartId	String	Identifiant du panier lié à la transaction
appVersion	String	Version de Yavin Pay
createdAt	String	Date de la transaction en UTC (ex: 2022-10-21T12:45:30.000Z)
serialNumber	String	Numéro de serie du terminal qui a encaissé la transaction

cloud-transactions-Customer

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

cloud-Annuler une transaction

This endpoint is used to cancel a payment on your terminal. Ce endpoint est utilisé pour annuler un paiement sur votre terminal.

Requête

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

import requests
import json

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)

Paramètre	Type	Defaut	Description
serialNumber	String	(obligatoire)	Numéro de série du terminal. Celui-ci peut-être trouvé sur le dos de votre terminal à côté de l'acronyme S/N

Réponse

{
  "status": "ok"
}

Paramètre	Type	Description
status	String	ok / ko

API Local

Cette API est utilisée pour lancer un paiement, imprimer ou bien récupérer l'historique sur le terminal Yavin connecté au réseau local.

Vous pouvez utiliser directement l'IP locale ou le Network Service Discovery compatible avec Apple Bonjour. (voir l'exemple ici)

N'oubliez pas le port d'écoute 16125 dans l'URL. Il est facile à retenir :

• P : 16ème lettre de l'alphabet
• A : 1ère lettre de l'alphabet
• Y : 25ème lettre de l'alphabet

local-Ping le terminal

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

Requête

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

Exécutez la requête afin de vérifier votre configuration et sa connectivité avec le terminal.
Vous pouvez ajouter un paramètre showMessage qui affichera un message sur le terminal "Hello there" si la valeur est true.
Par défaut showMessage est false.

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

Réponse

{
  "status": "ok"
}

Réponse	Type	Description
status	String	ok / ko

local-Effectuer une transaction

Requête

Pour une requête simple (avec seulement le montant) :

Requête simple

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

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

Pour une requête complexe (avec d'autres champs), il faudra envoyer un POST en remplissant les champs 'form-data' :

Requête complète

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

Paramètres	Type	Défaut	Description
amount	Integer		Montant à payer en centimes. 1€ => 100. Ce montant n'inclut pas les pourboires. Ce montant doit toujours être positif, même pour les annulation (transactionType=Reversal) et remboursements (transactionType=Refund)
giftAmount	Integer	0	Pourboires en centines
medium	String	card	card = transaction classique par carte. (D'autres méthodes de paiement seront bientôt disponibles). [card, qrcode, 2x, 3x, 4x,ancv, wechat, alipay, lydia, restoflash,...]
transactionType	String	debit	debit = transaction classique par carte. reversal = annulation d'un paiement. refund = remboursement [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer		Pré-remplissage des infos client pour un envoi du ticket pas SMS ou email. Voir l'objet Customer
vendor	Vendor		Infos relatives à l'éditeur de logiciel pour l'identifier. Voir l'objet Vendor
reference	String		Champ libre que le marchand pourra voir sur son back office My Yavin
receiptTicket	ReceiptTicket		Infos pour imprimer le ticket de caisse en meme temps que le ticket CB. Voir l'objet ReceiptTicket
receiptTicketJson	Objèt Ecommerce		Prend un objet json contenant les mêmes données que celles requises pour l'api du ecommerce.
cartId	String		Numéro de panier associé à la transaction. Cela pourra être utile pour associer une transaction et un ticket de caisse si le ticket de caisse n'a pas été renseigné initialement
idempotentUuid	String		Id idempotent pour identifier la transaction et retourner la même réponse si l'id est connu. Si le terminal possède une transaction avec cet UUID au cours des dernières 24 heures, le terminal répondra avec la transaction correspondante. Sinon, si aucune transaction n'est associée à l'UUID, un nouveau paiement sera initié et associé à l'UUID une fois le paiement effectué. Remarque : si une transaction a échoué (statut "ko") et que l'UUID idempotent reste le même, le terminal répondra par la transaction échouée. Dans ce cas, vous souhaiterez peut-être modifier l'UUID idempotent.

local-payment-Customer

Paramètres	Type	Défaut	Description
email	String		Email du client
firstName	String		Prénom du client
lastName	String		Nom du client
phone	String		Téléphone du client au format international commençant par le symbôle + (ex: +33612345678)

local-payment-ReceiptTicket

Paramètres	Type	Défaut	Description
format	String	text	Format de texte à imprimer. Valeurs possible : [text, escpos]
data	String		Le ticket de caisse à imprimer. Si format = text, data est imprimé tel quel. Si format = escpos, alors data doit être la sortie ESC POS encodée au format hexa string (ex: 1b401d6210...). Nous supportons l'ESCPOS en Android, Javascript, Python, voir les exemples sur notre github Yavin

local-payment-Vendor

Paramètres	Type	Défaut	Description
softwareName	String		Nom de l'éditeur de caisse
softwareVersion	String		Version de l'éditeur de caisse. Cela sera utile pour identifier les éventuels bugs rapidement

Réponse

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] Est ce que la transaction a été validé ou non
transactionId	String	Identifiant de la transaction. Utile pour le partage (voir l'API share)
amount	Integer	Montant à payer en centimes. 1€ => 100
giftAmount	Integer	Pourboires en centines
currencyCode	String	Code ISO 4217 de la devise dans laquelle s'effectuera le paiement (disponible uniquement sur activation)
issuer	String	Emetteur du paiement
scheme	String	Réseau utilisé pour valider la transactiosn (CB,CBSC (contactless),VISA,MASTERCARD,CONECS...)
transactionType	String	debit = transaction classique par carte. reversal = annulation d'un paiement. refund = remboursement [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer	Pré-remplissage des infos client pour un envoi du ticket pas SMS ou email. Voir l'objet Customer
reference	String	Champ libre que le marchand pourra voir sur son back office My Yavin
cartId	String	Numéro de panier associé à la transaction. Cela pourra être utile pour associer une transaction et un ticket de caisse si le ticket de caisse n'a pas été renseigné initialement
clientCardTicket	String	Ticket client CB de la transaction
merchantCardTicket	String	Ticket marchand CB de la transaction
appVersion	String	Version de l'app Yavin Pay
idempotentUuid	String	Id idempotent de la requête

local-Imprimer un ticket de caisse

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)

Requête

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

Paramètres	Type	Défaut	Description
format	String	text	Format de texte à imprimer. Valeurs possible : [text, escpos]
data	String	(obligatoire)	Le texte à imprimer. Si format = text, data est imprimé tel quel. Si format = escpos, alors data doit être la sortie ESC POS encodée au format hexa string (ex: 1b401d6210...). Nous supportons l'ESCPOS en Android, Javascript, Python, voir les exemples sur notre github Yavin

Réponse

{
  "status": "ok"
}

Réponse	Type	Description
status	String	ok / ko
message	String	Information complémentaire

local-Partager un ticket de caisse

Cette API permet de partager un ticket de caisse via une méthode spécifique (par email, sms, impression papier). Si les champs du client Customer sont présents dans la requête, le ticket lui sera partager directement. Autrement le champ nécessaire lui sera demander par le 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	Défaut	Description
receiptTicket	ReceiptTicket	(obligatoire)	Ticket de caisse à partager. Voir ReceiptTicket
transactionId	String	(obligatoire)	Identifiant de la transaction associé au ticket de caisse à envoyer. L'identifiant doit être celui reçu via l'API Payment
medium	String	yavin	La méthode utilisée pour partager le ticket de caisse. Les valeurs possible ont [sms, email, print]. Si yavin alors nous stockerons et enverrons le ticket de caisse au client suivant ses préférences de notifications
customer	Customer		Pré-remplissage des infos client pour un envoi du ticket pas SMS ou email. Voir l'objet Customer

local-share-Customer

Paramètres	Type	Défaut	Description
email	String		Email du client
firstName	String		Prénom du client
lastName	String		Nom du client
phone	String		Téléphone du client au format international commençant par le symbôle + (ex: +33612345678)

local-share-ReceiptTicket

Paramètres	Type	Défaut	Description
format	String	text	Format de texte à partager. Valeurs possible : [text, escpos]
data	String		Le ticket de caisse à partager. Si format = text, data est imprimé tel quel. Si format = escpos, alors data doit être la sortie ESCPOS encodée au format hexa string (ex: 1b401d6210...). Nous supportons l'ESCPOS en Android, Javascript, Python, voir les exemples sur notre github Yavin

Réponse

{
  "status": "ok"
}

Réponse	Type	Description
status	String	ok / ko

local-Récupérer les transactions

curl -XPOST 'http://<IP_LOCALE>: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)

Requête

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

Paramètres	Type	Défaut	Description
startDate	String	(optionnel)	Date de début (yyyy-MM-dd format)
endDate	String	(optionnel)	Date de fin (yyyy-MM-dd format) Note: est exclusive
startTime	String	(optionnel)	Heure de début (hh:mm:ss format)
endTime	String	(optionnel)	Heure de fin (hh:mm:ss format)
limit	Integer	20	Limite du nombre de transactions à recevoir par requête (max = 200)
offset	Integer	0	Décalage dans les transactions requêtées

Par défaut, si aucun paramètre de date / temps n'est indiqué, les 30 derniers jours sont pris en compte.

Réponse

Voir exemple.

Parameters	Type	Description
status	String	[ok / ko] Transaction réussie ou non
transactionId	String	Identifiant unique de la transaction
amount	Integer	Montant en centime de la transaction. N'inclut pas les pourboires
giftAmount	Integer	Montant en centime de la transaction du pourboires
currencyCode	String	Devise de la transaction en ISO 4217
issuer	String	Emetteur du paiement
scheme	String	Réseau utilisé pour valider la transactiosn (CB,CBSC (contactless),VISA,MASTERCARD,CONECS...)
transactionType	String	debit = paiement. reversal = annulation refund = remboursement [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer	Voir l'objet Customer
reference	String	Réference de la transaction, visible sur le My Yavin backoffice
cartId	String	Identifiant du panier lié à la transaction
appVersion	String	Version de Yavin Pay
createdAt	String	Date de la transaction en UTC (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

L'application Android Yavin Pay peut recevoir des Intent pour lancer des paiements ou bien imprimer directement sur le TPE.

La section kotlin fournit les classes et usage de l'API Android Intent.

android-Effectuer une transaction

Requête

Pour lancer un paiement par intent, utiliser ce code:

Voir la section kotlin

Voir la section kotlin

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);

Un paiement est lancé par Intent en suivant le format défini dans la section kotlin.

Si dessous est la structure de la donnée d'entrée TransactionRequest:

TransactionRequest.kt

Voir la section kotlin

Voir la section kotlin

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?
)

Paramètres	Type	Défaut	Description
amount	Integer		Montant à payer en centimes. 1€ => 100
giftAmount	Integer	0	Pourboires en centines
medium	String	card	card = transaction classique par carte. (D'autres méthodes de paiement seront bientôt disponibles). [card, qrcode, 2x, 3x, 4x,ancv, wechat, alipay, lydia, restoflash,...]
transactionType	String	debit	debit = transaction classique par carte. reversal = annulation d'un paiement. refund = remboursement [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer		Pré-remplissage des infos client pour un envoi du ticket pas SMS ou email. Voir l'objet Customer
vendor	Vendor		Infos relatives à l'éditeur de logiciel pour l'identifier. Voir l'objet Vendor
reference	String		Champ libre
receiptTicket	ReceiptTicket		Infos pour imprimer le ticket de caisse en meme temps que le ticket CB. Voir l'objet ReceiptTicket
receiptTicketJson	Objèt Ecommerce		Prend un objet json contenant les mêmes données que celles requises pour l'api du ecommerce.
cartId	String		Numéro de panier associé à la transaction
idempotentUuid	String		Id idempotent pour identifier la transaction et retourner la même réponse si l'id est connu. Si le terminal possède une transaction avec cet UUID au cours des dernières 24 heures, le terminal répondra avec la transaction correspondante. Sinon, si aucune transaction n'est associée à l'UUID, un nouveau paiement sera initié et associé à l'UUID une fois le paiement effectué. Remarque : si une transaction a échoué (statut "ko") et que l'UUID idempotent reste le même, le terminal répondra par la transaction échouée. Dans ce cas, vous souhaiterez peut-être modifier l'UUID idempotent.

Customer.kt

Voir la section kotlin

Voir la section kotlin

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

Paramètres	Type	Défaut	Description
email	String		Email du client
firstName	String		Prénom du client
lastName	String		Nom du client
phone	String		Téléphone du client au format international commençant par le symbôle + (ex: +33612345678)

ReceiptTicket.kt

Voir la section kotlin

Voir la section kotlin

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

android-payment-ReceiptTicket

Paramètres	Type	Défaut	Description
format	String	text	Format de texte à imprimer. Valeurs possible : [text, escpos]
data	String		Le ticket de caisse à imprimer. Si format = text, data est imprimé tel quel. Si format = escpos, alors data doit être la sortie ESCPOS encodée au format hexa string (ex: 1b401d6210...). Nous supportons l'ESCPOS en Android, Javascript, Python, voir les exemples sur notre github Yavin

Vendor.kt

Voir la section kotlin

Voir la section kotlin

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

android-payment-Vendor

Paramètres	Type	Défaut	Description
softwareName	String		Nom de l'éditeur de caisse
softwareVersion	String		Version de l'éditeur de caisse. Cela sera utile pour identifier les éventuels bugs rapidement

Réponse

Lorsque votre application reçoit la réponse de la transation dans onActivityResult(), récupérez la transaction sérialisée en JSON depuis l'Intent data via les extras en utilisant la clé response.

Pour récupérer la réponse de la transaction:

Voir la section kotlin

Voir la section kotlin

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)
    }
}

Voici la structure de la classe TransactionResponse:

TransactionResponse.kt

Voir la section kotlin

Voir la section kotlin

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?
)

Paramètres	Type	Description
status	String	[ok / ko] Est ce que la transaction a été validé ou non
transactionId	String	Identifiant de la transaction. Utile pour le partage (voir l'API share)
amount	Integer	Montant à payer en centimes. 1€ => 100. Ce montant n'inclut pas les pourboires. Ce montant doit toujours être positif, même pour les annulation (transactionType=Reversal) et remboursements (transactionType=Refund)
giftAmount	Integer	Pourboires en centines
currencyCode	String	Code ISO 4217 de la devise dans laquelle s'effectuera le paiement (disponible uniquement sur activation)
issuer	String	Emetteur du paiement
scheme	String	Réseau utilisé pour valider la transactiosn (CB,CBSC (contactless),VISA,MASTERCARD,CONECS...)
transactionType	String	debit = transaction classique par carte. reversal = annulation d'un paiement. refund = remboursement [debit, reversal, refund, preauthorisation, closingbatch]
customer	Customer	Pré-remplissage des infos client pour un envoi du ticket pas SMS ou email. Voir l'objet Customer
reference	String	Champ libre que le marchand pourra voir sur son back office My Yavin
cartId	String	Numéro de panier associé à la transaction. Cela pourra être utile pour associer une transaction et un ticket de caisse si le ticket de caisse n'a pas été renseigné initialement
clientCardTicket	String	Ticket client CB de la transaction
merchantCardTicket	String	Ticket marchand CB de la transaction
appVersion	String	Version de l'app Yavin Pay
idempotentUuid	String	Id idempotent de la requête

android-Imprimer un ticket de caisse

Requête

Pour lancer une impression par intent, utiliser ce code:

Voir la section kotlin

Voir la section kotlin

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

Voir la section kotlin

Voir la section kotlin

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

Paramètres	Type	Défaut	Description
format	String	text	Format de texte à imprimer. Valeurs possible : [text, escpos]
data	String	(obligatoire)	Le texte à imprimer. Si format = text, data est imprimé tel quel. Si format = escpos, alors data doit être la sortie ESCPOS encodée au format hexa string (ex: 1b401d6210...). Nous supportons l'ESCPOS en Android, Javascript, Python, voir les exemples sur notre github Yavin

Réponse

Pour récupérer la réponse :

Voir la section kotlin

Voir la section kotlin

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

Voir la section kotlin

Voir la section kotlin

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

Réponse	Type	Description
status	String	ok / ko

android-Partager un ticket de caisse

Cette API permet de partager un ticket de caisse via une méthode spécifique (par email, sms, impression papier). Si les champs du client Customer sont présents dans la requête, le ticket lui sera partager directement. Autrement le champ nécessaire lui sera demander par le terminal.

Request

Pour partager par Intent, utiliser ce code:

Voir la section kotlin

Voir la section kotlin

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

Voir la section kotlin

Voir la section kotlin

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	(obligatoire)	Ticket de caisse à partager. Voir ReceiptTicket
transactionId	String	(obligatoire)	Identifiant de la transaction associé au ticket de caisse à envoyer. L'identifiant doit être celui reçu via l'API Payment
medium	String	yavin	La méthode utilisée pour partager le ticket de caisse. Possible values are [sms, email, print]. Si yavin alors nous stockerons et enverrons le ticket de caisse au client suivant ses préférences de notifications
customer	Customer		Pré-remplissage des infos client pour un envoi du ticket pas SMS ou email. Voir l'objet Customer

Customer.kt

Voir la section kotlin

Voir la section kotlin

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

Paramètres	Type	Défaut	Description
email	String		Email du client
firstName	String		Prénom du client
lastName	String		Nom du client
phone	String		Téléphone du client au format international commençant par le symbôle + (ex: +33612345678)

ReceiptTicket.kt

Check kotlin section

Voir la section kotlin

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

android-share-ReceiptTicket

Paramètres	Type	Défaut	Description
format	String	text	Format de texte à partager. Valeurs possible : [text, escpos]
data	String		Le ticket de caisse à partager. Si format = text, data est imprimé tel quel. Si format = escpos, alors data doit être la sortie ESCPOS encodée au format hexa string (ex: 1b401d6210...). Nous supportons l'ESCPOS en Android, Javascript, Python, voir les exemples sur notre github Yavin

Response

Pour récupérer la réponse :

Voir la section kotlin

Voir la section kotlin

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

Voir la section kotlin

Voir la section kotlin

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

Paramètres	Type	Description
status	String	ok / ko

android-Récupérer les transactions

Requête

Pour récupérer les transactions du terminal par Intent, utiliser ce code:

Check kotlin section

Voir la section kotlin

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

Voir la section kotlin

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	(optionnel)	Date de début (yyyy-MM-dd format)
endDate	String	(optionnel)	Date de fin (yyyy-MM-dd format) Note: est exclusive
startTime	String	(optionnel)	Heure de début (hh:mm:ss format)
endTime	String	(optionnel)	Heure de fin (hh:mm:ss format)
limit	Integer	20	Nombre de transactions à récupérer par requête (max = 200)
offset	Integer	0	Décalage de offset * limite dans la requête

Par défaut, si aucun paramètre de date / temps n'est indiqué, les 30 derniers jours sont pris en compte.

Response

To get response :

Check kotlin section

Voir la section kotlin

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

Voir la section kotlin

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 = remboursement [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
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

Voir la section kotlin

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-Lire un tag NFC via Yavin Pay

Ce document décrit comment récupérer les données d'un tag NFC via Yavin Pay.

L'application mettra fin de manière automatique à l'intent au bout de 1 minute et 30 secondes par défaut.

Requête

Les paramètres de cette requête sont optionnels, pour l'instant ils permettent de contrôler le timeout de la lecture et d'afficher un texte customisable à l'écran à la lecture de carte.

Pour demander une lecture via l'intent, vous pouvez utiliser ce code:

Voir la section kotlin

Voir la section kotlin

val request = NFCReaderRequestV4(10000, "Approchez vorte carte")
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	durée maximale en milliseconds pour lire la carte. Doit être superieur à 10000
readerIncentive	String		Texte à afficher à l'écran lors de la lecture de carte

Réponse

Pour obtenir la réponse :

Voir la section kotlin

Voir la section kotlin

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

Voir la section kotlin

Voir la section kotlin

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

Parameters	Type	Default	Description
status	Boolean	(obligatoire)	Indique si la lecture s'est correctement déroulée: true or false
tagInfo	TagInfo		Contient les informations du tag. Seul le numéro de série est communiqué pour l'instant

TagInfo.kt

Voir la section kotlin

Voir la section kotlin

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

android-nfc-TagInfo

Parameters	Type	Description
serialNumber	String	Représente le numéro de série du tag

Ecommerce

L'API ecommerce fournit un lien de paiement qui peut ensuite être utilisé pour rediriger un utilisateur vers un écran de paiement personnalisable.

La page de paiement affichée fournit des informations supplémentaires à l'utilisateur (il peut s'agir, par exemple, d'une liste détaillée de la commande). En cas de paiement réussi ou d'annulation par l'utilisateur, une réponse est envoyée à une url de retour spécifiée avec l'état du paiement. Si le paiement n'a pas abouti, le client a la possibilité de réessayer.

ecommerce-Flow

1. L'utilisateur sélectionne un ou plusieurs articles sur votre site web et clique sur le bouton de paiement, notifiant à votre serveur qu'il souhaite effectuer un paiement.
2. Votre serveur traite la demande et effectue un appel api pour générer un lien de paiement.
3. Le serveur Yavin génère un lien de paiement unique et l'envoie en réponse.
4. Votre serveur envoie une réponse de redirection au frontend, le redirigeant vers l'url du lien de paiement (page alimentée par Yavin).
5. Le client est présenté avec un widget pour fournir ses informations de paiement et effectuer le paiement.
6. Le paiement est traité et une réponse est envoyée à votre serveur à l'url de retour fournie, avec un cartId et un statut dans les params de la requête.
7. Votre serveur traite la réponse et affiche les informations pertinentes à l'utilisateur.

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 utilise une clé d'API pour restreindre l'accès aux données et services aux utilisateurs ayant droit. Vous pouvez trouver votre clé d'API sur my.yavin.com dans l'onglet API.

Toutes les requêtes doivent être identifiées. Pour ce faire, renseigner votre clé d'API dans les headers de la requête POST:

ecommerce-Responses

Cette API fournit deux types de réponses :

• Synchrone : Il s'agit de la réponse initiale lors de la demande d'un lien de paiement, qui contient le lien de paiement vers lequel le client doit être redirigé.
• Asynchrone : il s'agit de la réponse envoyée aux urls returnUrlSuccess / returnUrlCancelled. Ces urls de notification sont appelées soit lorsqu'un paiement a été effectué avec succès, soit lorsqu'un lien de paiement a été annulé

Les deux réponses à l'url de notification fournissent le cartId dans les paramètres de la requête (c.-à-d. https://mydomain/yavinPaymentLink/success?cartId=abcde12345) à utiliser comme référence.

ecommerce-Errors

The Yavin API uses the following error codes:

L'API Yavin utilise les codes d'erreur suivants :

Code	Explication
400	Bad Request -- La requête est invalide.
401	Unauthorized -- La clé d'API n'est pas valide ou le terminal n'est pas accessible avec la clé d'API
404	Not Found -- Le lien n'existe pas.
405	Method Not Allowed -- Vous essayez d'accéder à un lien avec une methode HTTP invalide.
500	Internal Server Error -- Il y a un problème avec notre serveur. Ré-essayez plus tard. Contactez le service client si le problème persiste.

ecommerce-Demander un lien de paiement

La demande d'un lien de paiement est très simple à configurer car il n'y a que trois paramètres obligatoires dans le body de la requête. Cependant, de nombreux paramètres facultatifs peuvent être utilisés pour fournir des informations supplémentaires à l'utilisateur et offrir une experience plus personnalisée.

NOTE: Tous les variable numériques sont des integers
NOTE: Tous les montant sont en centimes

ecommerce-Requête

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

Paramètres	Type	Défaut	Description
cartId	String	requis	L'ID qui fait référence à cette commande particulière. Il sera envoyé comme référence dans la réponse à l'url de retour après un paiement réussi/échec.
returnUrlSuccess	String	requis	Seront jointes le params cartId pour référence
returnUrlCancelled	String	requis	Seront jointes le params cartId pour référence. Veuillez noter qu'une réponse cet url ne signifie pas que le paiement a échoué, car le client aura toujours la possibilité de réessayer. Par conséquent, une réponse sur cet url est le résultat d'une annulation (le plus souvent déclenchée par le client).
amount	Number	requis	Le montant total que le client doit payer, taxe inclus (valeur en centimes)
amountWithoutTax	Number	optionnel	Le montant total que le client doit payer hors-taxe (valeur en centimes)
taxAmount	Number	optionnel	Le montant de taxe total (valeur en centimes)
message	String	optionnel	Cela vous permet d'afficher un message personnalisé à l'intention de l'utilisateur (il s'agit généralement d'informations supplémentaires ou d'un message de remerciement).
currency	String	optionnel	Au format ISO 4217, utilisé pour communiquer la devise dans laquelle le client paie, afin de garantir que le format correct est affiché à l'utilisateur final. Si aucune devise n'est fournie, la valeur par défaut sera € euros.
datetime	String	optionnel	Un objet datetime avec le fuseau horaire
vendor	vendor	optionnel	Ces informations peuvent être utilisées pour plusieurs raisons. Elles seront principalement utilisées pour afficher des informations à l'utilisateur final, ainsi que pour aider au debugging.
customer	customer	optionnel	Utilisé pour fournir des informations sur le client afin d'afficher des messages personnalisés.
items	Array/List of item	optionnel	Utilisé pour afficher une liste détaillée de ce que le client paie

Décomposition des objets/dictionnaires

item

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

Paramètres	Type	Défaut	Description
name	String	requis	La description principale de l'article
totalAmount	Number	requis	La valeur totale de l'article (unitPrice x quantity)
totalAmountWithoutTax	Number	requis	La valeur totale de l'article hors-taxe (unitPriceWithoutTax x quantity)
eligibleTitreRestaurant	Boolean	optionnel	L'article peut être acheté avec un titre restaurant
category	String	optionnel	Peut être utilisé pour catégoriser vos articles
freeNote	String	optionnel	Peut être utilisé pour communiquer quelque chose sur l'article à l'utilisateur, ou être une demande du client.
quantity	Number	optionnel	Quantité de cet article particulier (combien d'articles sont facturés) demandée
unitPrice	Number	optionnel	La valeur d'un élément spécifique. Une valeur négative fera apparaître la ligne en rouge.
unitPriceWithoutTax	Number	optionnel	La valeur d'un élément spécifique hors-taxe. Une valeur négative fera apparaître la ligne en rouge.
tax	tax	optionnel	Utilisé pour afficher la répartition des taxes sur un article. Doit fournir montant en cents et taux en pourcentage décimal.
items	Array/List of item	optionnel	Une liste d'éléments, qui sont les mêmes objets que celui-ci.

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

Paramètres	Type	Défaut	Description
brandName	String	requis	Le nom de l'entreprise tel qu'il est connu publiquement
legalName	String	requis	Le nom de l'entreprise tel qu'il est connu légalement
country	String	optionnel	ISO 3166-2
merchantId	String	optionnel	Le numéro d'identification du commerçant, par exemple en France, ce serait la "Sirène".
merchantCategoryCode	String	optionnel	Le code de la catégorie du commerçant, par exemple en France, ce serait le "Code NAF".
softwareName	String	optionnel	S'il est intégré à un logiciel, tel qu'un point de vente, il peut s'agir d'informations utiles pour le debugging.
softwareVersion	String	optionnel	S'il est intégré à un logiciel, tel qu'un point de vente, il peut s'agir d'informations utiles pour le debugging.
store	store	optionnel	Les informations du point de vente associé. Si elles sont fournies, toutes les options de l'objet sont obligatoires. Le storeId (ce serait le "Siret" en France) et un objet adresse contenant address, postcode, et city qui sera formaté par 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	requis	Prénom du client
lastName	String	requis	Nom du client
email	String	optionnel	Email du client
telephone	String	optionnel	Numéro de téléphone du client
address	String	optionnel	Adresse de résidence du client
city	String	optionnel	Ville de résidence du client
postcode	String	optionnel	Code postal de résidence du client

store

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

Parameters	Type	Default	Description
storeId	String	requis	SIREN du point de vente
address	address	requis	Informations relatives au point de vente

Address

Parameters	Type	Default	Description
address	String	requis	Adresse du point de vente
postcode	String	requis	Code postal du point de vente
city	String	requis	Ville du point de vente

tax

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

Parameters	Type	Default	Description
amount	integer	requis	Montant des taxes en cts
rate	decimal integer	requis	Taux de la taxe appliquée

Exemple

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": 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"
      }
    }
  },
  "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)