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,
  "card_token": "F12345678",
  "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
card_token	String	Le token unique de la carte

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-Abandon d'une transaction

Cet endpoint a été conçu pour permettre l'abandon d'un paiement en cours sur votre terminal. Lorsque cette action est déclenchée, tous les écrans associés au paiement en cours sont fermés et le terminal est ramené à son écran principal. Recommandation importante: Il est vivement conseillé d'éviter d'annuler un paiement pendant la phase de lecture de la carte. Une annulation à ce stade pourrait entraîner la fermeture inopinée de l'écran de la passerelle de paiement. Cette action pourrait engendrer des incohérences dans les données, car l'information relative au paiement ne serait pas correctement transmise.

Requête

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

curl -XPOST "https://api.yavin.com/api/v4/pos/abort/" \
  --header 'Yavin-Secret: YAVIN_API_KEY' \
  --data '{
    "serialNumber": "123456789",
    "idempotentUuid": "dbcb384c-7d8d-4d2b-b367-133bfdf5c9c"
}'

import requests
import json

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

params = {
    "serialNumber": "123456789",
    "idempotentUuid": "dbcb384c-7d8d-4d2b-b367-133bfdf5c9c"
}

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
idempotentUuid	String	(optionnel mais recommandé)	UUID de la transaction que vous souhaitez annuler s'il y en a une en cours. Si aucun idempotentUuid n’est envoyé, alors nous forcerons l’annulation de toute transaction en cours sur le terminal

Réponse

{
  "status": "ok"
}

Paramètre	Type	Description
status	String	ok / ko en fonction de si la requête a été envoyé ou pas

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ée 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
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 transaction (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 informations 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
cardToken	String	Le token unique de la carte
message	String (optionnel)	Le message d'erreur s'il y en a un

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

      ...
    ]
}

local-Abandon d'une requête

Cet endpoint a été conçu pour permettre l'abandon d'un paiement en cours sur votre terminal. Lorsque cette action est déclenchée, tous les écrans associés au paiement en cours sont fermés et le terminal est ramené à son écran principal. Recommandation importante: Il est vivement conseillé d'éviter d'annuler un paiement pendant la phase de lecture de la carte. Une annulation à ce stade pourrait entraîner la fermeture inopinée de l'écran de la passerelle de paiement. Cette action pourrait engendrer des incohérences dans les données, car l'information relative au paiement ne serait pas correctement transmise.

curl -X POST 'http://<LOCAL_IP>:16125/localapi/v4/abort' \
  --header 'Content-Type: application/json' \
  --data '
  {
    "idempotentUuid": "dbcb384c-7d8d-4d2b-b367-133bfdf5c9c"
  }'

Requête

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

Parameters	Type	Default	Description
idempotentUuid	String (optionnel mais recommandé)		UUID de la transaction que vous souhaitez annuler s'il y en a une en cours. Si aucun idempotentUuid n’est envoyé, alors nous forcerons l’annulation de toute transaction en cours sur le terminal

Réponse

{
  "status": "ok"
}

Paramètres	Type	Description
status	String	ok / ko
message	String (optionnel)	Le message d'erreur s'il y en a un
idempotentUuid	String (optionnel)	Peut ne pas être présent dans la réponse. L'idempotentUuid de la transaction en cours sur le terminal

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
cardToken	String	Le token unique de la carte

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

Introduction

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

La page de paiement affichée fournira des informations supplémentaires à l'utilisateur (il pourrait s'agir, par exemple, d'un récapitulatif détaillé de la commande). Après un paiement réussi, ou une annulation par l'utilisateur, une réponse est envoyée à une URL de retour spécifiée avec le statut du paiement. Si le paiement échoue, le client aura l'opportunité de réessayer.

ecommerce-Flow

1. L'utilisateur sélectionne des articles sur votre site web et clique sur le bouton de paiement, informant votre serveur de son intention.
2. Votre serveur gère la demande et fait une demande à l'API Yavin pour générer un lien de paiement.
3. Le serveur Yavin génère un lien de paiement unique et l'envoie dans la réponse.
4. Votre serveur envoie une réponse de redirection au client de l'utilisateur, le redirigeant vers l'URL du lien de paiement (page alimentée par Yavin).
5. Le client se voit présenter 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 paramètres de requête.
7. Votre serveur gère la réponse et affiche les informations pertinentes à l'utilisateur.

ecommerce-Authentification

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

import requests

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

params = {
    ...
}

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

Yavin utilise des clés API pour restreindre l'accès aux données et services aux utilisateurs autorisés. Vous pouvez trouver votre clé API sur my.yavin.com dans l'onglet paramètres>API.

Toutes les requêtes doivent être identifiées. Pour ce faire, votre clé API doit être dans les en-têtes de la requête POST :

Erreurs

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

Code	Explication
400	Requête incorrecte -- La requête est invalide.
401	Non autorisé -- La clé API est invalide ou le point de terminaison ne peut pas être accédé avec cette clé API
404	Non trouvé -- Le lien n'existe pas.
405	Méthode non autorisée -- Vous essayez d'accéder à un lien avec une méthode HTTP invalide.
500	Erreur interne du serveur -- Il y a un problème avec notre serveur. Veuillez réessayer plus tard. Contactez l'équipe de support si le problème persiste.

Informations clés

• État du panier : Il n'y a pas de notion d'état 'échoué'. Voici une ventilation des états possibles :

  • pending : En attente de paiement.
  • ok : Paiement réussi.
  • authorised : Payé mais contient une ou plusieurs transactions autorisées nécessitant une capture.
  • ko : Le panier a été annulé.

• Convention snake_case :

  • Toutes les clés ont été converties de camelCase à snake_case pour une meilleure lisibilité. Cependant, la convention camelCase est toujours acceptée.
  • Les paramètres de requête dans les URL de réponse_success et response_cancel resteront en camelCase afin d'éviter d'introduire des changements susceptibles de causer des problèmes.

• Représentation du 'Cart' :

  • Un panier représente une seule demande de paiement. Il peut contenir une ou plusieurs transactions, permettant aux utilisateurs de payer en partie avec des tickets-repas et de compléter le reste avec une autre carte.
  • Chaque fois que la notion de 'panier' est utilisée, elle fait référence à une demande de paiement initiée par le point final /generate_link/.

ecommerce-Générer un Lien

Description

Cet endpoint est utilisé pour générer un lien de commerce électronique pour une nouvelle demande de paiement.

Requête

Paramètres

body = {
  "cart_id": "my_custom_cart_id_001",
  "amount": 3000,
  "amount_without_tax": 2400,
  "tax_amount": 600,
  "return_url_success": "https://mydomain.com/ecommerce/success",
  "return_url_cancelled": "https://mydomain.com/ecommerce/cancelled",
  "is_instant_capture": True,
  "webhook_url": "https://mydomain.com/ecommerce/webhook",
  "message": "Thank you for shopping with us",
  "datetime": "2023-10-16 14:35:15",
  "currency": "EUR",
  "reference": "Luke",
  "client_reference": "aoj239uvn2ca"
}

Nom	Type	Description	Requis
cart_id	String	Identifiant unique pour le panier. Si le cart_id fourni existe déjà dans le système, la réponse inclura le message d'erreur "This cart_id already exists", ainsi que le lien vers le panier existant à l'indice 1.	Oui
return_url_success	String	URL pour rediriger en cas de paiement réussi.	Oui
return_url_cancelled	String	URL pour rediriger en cas d'annulation du paiement.	Oui
amount	Integer	Le montant total à payer.	Oui
is_instant_capture	Boolean	Default : True, si la valeur est False, les transactions seront pré-autorisées et les fonds ne seront pas collectés tant que le endpoint /capture_transactions/ n'aura pas été appelé.	Non
amount_without_tax	Integer	Montant sans taxe, le cas échéant.	Non
webhook_url	String	URL pour les notifications de webhook. Doit commencer par "http".	Non
tax_amount	Integer	Le montant de la taxe.	Non
message	String	Message ou note supplémentaire.	Non
datetime	String	Date et heure de la création du panier.	Non
currency	String	Code de devise (par exemple, USD).	Non
vendor	Object	Détails du vendeur. Voir Objet Vendor.	Non
customer	Object	Détails du client. Voir Objet Customer.	Non
items	Array	Liste d'articles. Voir Objet Item.	Non
reference	String	Informations de référence supplémentaires.	Non
client_reference	String	Informations de référence du client.	Non
features	Object	Fonctionnalités supplémentaires. Voir Objet Features.	Non

return_url_cancelled & return_url_success

Ces deux paramètres sont utilisés pour rediriger les utilisateurs une fois un paiement effectué en totalité ou annulé. Ce sont des requêtes GET avec le cartId et le statut inclus dans les paramètres de requête.

• Il n'y a pas de concept de paiement échoué, car les utilisateurs auront toujours la possibilité de réessayer. En cas d'annulation de commande, return_url_cancelled sera invoqué.

Validation

• cart_id : Doit être un identifiant unique et ne doit pas exister dans le système pour l'entreprise donnée.

• webhook_url : Doit commencer par "http" ou "https".

• features : Les fonctionnalités supplémentaires sont mappées à partir de clés camelCase en clés snake_case.

Réponses

Cette API fournit 2 types de réponses :

• Synchrones : Il s'agit de la réponse initiale lors de la demande d'un lien de paiement, qui contient le lien de paiement à transmettre au client.
• Asynchrones : Il s'agit de la réponse envoyée aux return_url_success / return_url_cancelled. Ces URL de notification sont appelées soit lorsqu'un paiement réussi a été effectué, soit si un lien de paiement a été annulé.

Réponse asynchrone

Les réponses aux URL de notification fournissent le cartId dans les paramètres de requête à utiliser comme référence, ainsi que le statut du panier (c'est-à-dire https://mondomaine/yavinLienPaiement/success?cartId=abcde12345&status=ok)

Réponse synchrone

Réponse de succès

• status code : 201

• Réponse body : { "payment_link": "https://yav.in/example" }

Réponse erreur

• Status Code: 400

• Réponse Body: { "errors": { "cart_id": [ "This cart_id already exists", "https://yav.in/example ] } }

éxample + analyse

ecommerce-Déscription des objets

Objet Vendeur

vendor = {
    "brand_name": "VendorXYZ",
    "country": "US",
    "store": {
      "store_id": "ABC123",
      "address": {
        "address": "123 Main St",
        "postcode": "10001",
        "city": "New York"
      }
    }
  }

Nom	Type	Description	Requis
brand_name	String	Nom de la marque du vendeur.	Oui
legal_name	String	Nom légal du vendeur.	Non
country	String	Code de pays à deux lettres (ISO 3166-1 alpha-2)	Non
merchant_id	String	ID du marchand.	Non
merchant_category_code	String	Code de catégorie du marchand.	Non
software_name	String	Nom du logiciel.	Non
software_version	String	Version du logiciel.	Non
store	Object	Détails du magasin. Voir Objet Store.	Non

Objet Store

store = {
  "store_id": "ABC123",
  "address": {
    "address": "123 Main St",
    "postcode": "10001",
    "city": "New York"
  }
}

Nom	Type	Description	Requis
store_id	String	Identifiant du magasin.	Oui
address	Object	Adresse du magasin. Voir Objet Address.	Non

Objet Address

Nom	Type	Description	Requis
address	String	Adresse du magasin.	Oui
postcode	String	Code postal du magasin.	Oui
city	String	Ville du magasin.	Oui

Objet Customer

customer = {
    "first_name": "Luke",
    "last_name": "Skywalker",
    "email": "luke.skywalker@yavin.com",
    "telephone": "0612345678",
    "address": "456 Oak St",
    "city": "Paris",
    "postcode": "20002"
}

Nom	Type	Description	Requis
first_name	String	Prénom du client.	Oui
last_name	String	Nom de famille du client.	Oui
email	String	Adresse e-mail du client.	Non
telephone	String	Numéro de téléphone du client.	Non
address	String	Adresse du client.	Non
city	String	Ville du client.	Non
postcode	String	Code postal du client.	Non

Objet Item

items = [
  {
    "name": "Item1",
    "total_amount": 200,
    "quantity": 2,
    "tax": {
      "amount": 20,
      "rate": 10
    },
    "items": [
      {
        "name": "SubItem1",
        "total_amount": 100
      },
      {
        "name": "SubItem2",
        "total_amount": 100
      }
    ]
  },
  {
    "name": "Item2",
    "total_amount": 300
  }
]

Nom	Type	Description	Requis
name	String	Nom de l'article.	Oui
total_amount	Integer	Montant total de l'article.	Oui
total_amount_without_tax	Integer	Montant sans taxe pour l'article.	Non
category	String	Catégorie de l'article.	Non
eligible_titre_restaurant	Boolean	Éligibilité au Titre Restaurant.	Non
free_note	String	Note libre pour l'article.	Non
quantity	Integer	Quantité de l'article.	Non
unit_price	Integer	Prix unitaire de l'article.	Non
unit_price_without_tax	Integer	Prix unitaire sans taxe pour l'article.	Non
tax	Object	Détails de la taxe. Voir Objet Tax.	Non
items	Array	Articles imbriqués. Voir Objet Item.	Non

Objet Tax

Nom	Type	Description	Requis
amount	Integer	Montant de la taxe.	Oui
rate	Integer	Taux de taxe en décimal.	Oui

Objet Features

features = {
  {
    "tips": True,
    "customer_contacts": True,
    "meal_vouchers": True,
    "share_by_email": True,
    "share_by_sms": True
  }
}

Nom	Type	Description	Par défaut
tips	Boolean	Indique si les pourboires sont actifs.	True
customer_contacts	Boolean	Indique si les clients de l'entreprise sont actifs.	True
meal_vouchers	Boolean	Indique si les tickets repas sont actifs.	True
share_by_email	Boolean	Indique si partager le lien de paiement avec le client par email. Nécessite un Objet Customer valide avec une adresse email fourni	False
share_by_sms	Boolean	Indique si partager le lien de paiement avec le client par SMS. Nécessite un Objet Customer valide avec un numéro de téléphone fourni	False

ecommerce-Webhook

webhook_data = {
  "cart_id": "12345",
  "payment_link": "https://yav.in/example",
  "requested_amount": 2000,
  "asked_amount": 2500,
  "paid_amount": 2500,
  "gift_amount": 500,
  "status": "ok",
  "transactions": [
    {
      "total_amount": 2500,
      "gift_amount": 500,
      "currency_code": "EUR",
      "date_of_payment": "2023-10-16",
      "gateway": "conecs",
      "issuer": "UP FRANCE (CHÈQUE DÉJEUNER)",
      "transaction_id": "abcd123",
      "pan": "4575******1234",
      "status": "ok"
    }
  ]
}

Si webhook_url est fourni, à chaque transaction (car il est possible qu'un seul panier puisse avoir plusieurs transactions), webhook_url sera appelé via une requête POST avec les informations suivantes :

Clé	Type	Description
cart_id	String	Il s'agit du cart_id que vous avez fourni dans la requête initiale.
payment_link	String	Le lien de paiement pour ce panier
requested_amount	Integer	Le montant demandé dans la demande initiale, en centimes.
asked_amount	Integer	Le montant demandé à être capturé, en centimes. Dans la plupart des cas, il sera identique au requested_amount, cependant cela sera différent dans le cas où un paiement d'autorisation a été demandé, et que l'endpoint /capture_transactions a été appelé avec un montant inférieur à celui demandé initialement.
paid_amount	Integer	Le montant total payé par le client, en centimes.
gift_amount	Integer	Le montant du pourboire laissé par le client (si activé), en centimes.
status	String	Le statut de la commande demandée. Les valeurs possibles sont : "ok" (la commande a été payée), "ko" (la commande a été annulée) et "pending" (la commande est toujours active mais n'a pas encore été entièrement payée).
transactions	Array	Une liste d'Objets Transaction contenant des informations relatives à tout paiement effectué pour cette commande.

Objet Transaction

Paramètres	Type	Description
total_amount	Integer	Montant payé en centimes.
gift_amount	Integer	Montant de pourboires payé, si il y en a, en centimes.
currency_code	String	Le code de devise au format ISO-4217 (c'est-à-dire EUR).
date_of_payment	String	La date et l'heure du paiement. La chaîne de date-heure sera fournie dans le format suivant : AAAA-MM-JJ HH:MM:SS et est en GMT.
gateway	String	La passerelle de la transaction.
issuer	String	Le nom de l'émetteur de la carte.
transaction_id	String	Identifiant unique de cette transaction.
pan	String	Les premiers et derniers chiffres de la carte utilisée, joints par des caractères d'astérisque.
status	String	Le statut de la transaction.

ecommerce-Annuler le lien

Description

Ce endpoint est utilisé pour annuler une demande de paiement. L'annulation est possible uniquement si le panier remplit certaines conditions. La réponse indiquera si l'annulation a réussi ou fournira des informations d'erreurs détaillées.

Requête

Paramètres

request_body = {
  "cart_id": "12345"
}

Nom	Type	Description	Requis
cart_id	String	Identifiant unique du panier.	Oui

Réponses

Succès

{
  "message": "Cart has been cancelled"
}

En cas d'annulation réussie, la réponse comprendra les informations suivantes :

Nom	Type	Description
message	String	Indique que le panier a été annulé.

Erreurs

{
  "error": "Cart contains a non-cancellable transaction",
  "cart_data": {
    "cart_id": "12345",
    "requested_amount": 3000,
    "asked_amount": 3000,
    "amount_paid": 2500,
    "status": "pending",
    "transactions": [
      {
        "total_amount": 2500,
        "gift_amount": 0,
        "currency_code": "EUR",
        "date_of_payment": "2023-10-16",
        "gateway": "conecs",
        "issuer": "UP FRANCE (CHÈQUE DÉJEUNER)",
        "transaction_id": "abcd123",
        "pan": "4575******1234"
      }
    ]
  }
}

Si l'annulation n'est pas possible, le message d'erreur sera construit comme suit :

Nom	Type	Description
error	String	Raison pour laquelle l'annulation n'est pas possible. cart.status == 'ok': "Cart has already been paid in full" cart.status == 'ko': "Cart has already been cancelled". cart contains a non-cancellable transaction: "Cart contains a non-cancellable transaction"
webhook_data	Object	Informations sur le panier et ses transactions. Voir la réponse du webhook dans la page Webhook pour la définition.

ecommerce-Capture Transactions

Description

Cet endpoint est utilisé pour capturer des transactions pour un panier donné. Cet endpoint permet également de capturer une partie du montant si spécifié.

Important - Cet endpoint n'est disponible que pour les liens de paiement générés avec la fonction cb_instant_capture définie sur False.

Requête

{
  "cart_id": "12345",
  "amount_to_capture": 400
}

Paramètres

Nom	Type	Description	Requis
cart_id	String	Identifiant unique du panier.	Oui
amount_to_capture	Integer	Montant à capturer, en centimes.	Non

Validation

• cart_id : Doit être un identifiant de panier valide. Si le statut du panier n'est pas 'authorised', une réponse d'erreur sera fournie.
• amount_to_capture : Facultatif. S'il est fourni, il doit s'agir d'une valeur entière et ne peut pas dépasser le montant initial demandé.

Réponse

success_body = {
  "message": "ok",
  "data": {
    "cart_id": "12345",
    "amount_requested": 400,
    "amount_paid": 400,
    "tip_amount": 0,
    "status": "ok",
    "transactions": [
      {
        "amount_paid": 400,
        "currency_code": "EUR",
        "date_of_payment": "2023-10-16",
        "gateway": "payline",
        "issuer": "CB",
        "transaction_id": "abcd123",
        "pan": "4575******1234"
      }
    ]
  }
}

Succès

En cas de capture réussie, la réponse inclura les informations suivantes :

Nom	Type	Description
message	String	ok Indique que la capture a réussi
data	Object	Objet de données avec la même structure que la réponse de webhook de l'endpoint generate_link.

error_body = {
  "message": "The capture of one or more transaction(s) was not possible",
  "errors": [
    {
      "transaction_id": "abcd123",
      "reason": "The issuer has declined the request"
    }]
}

Erreurs

• Si d'autres erreurs surviennent pendant le traitement (par exemple, refus de la banque/émetteur), la réponse inclura un message indiquant que la capture d'une ou plusieurs transactions n'a pas été possible, ainsi que des informations d'erreur détaillées.

Name	Type	Description
message	String	Message expliquant pourquoi nous n'avons pas pu répondre à votre demande cart.status == 'ok': This link has already been validated and has no transactions that require capturing cart.status == 'ko': This link has already been cancelled and does not have any transactions that require capturing cart.status == 'pending': This link has not yet been paid in full Toute autre erreur sera accompagnée d'un message personnalisé indiquant la raison de l'erreur.
errors	List	Si une erreur est renvoyée par l'émetteur lors de la saisie d'une transaction, les informations relatives à l'erreur s'affichent ici.

ecommerce-Obtenir des informations sur le panier

{
  "cart_id": "12345",
  "payment_link": "https://yav.in/example",
  "requested_amount": 2000,
  "asked_amount": 2500,
  "paid_amount": 2500,
  "gift_amount": 500,
  "status": "ok",
  "transactions": [
    {
      "total_amount": 2500,
      "gift_amount": 500,
      "currency_code": "EUR",
      "date_of_payment": "2023-10-16",
      "gateway": "conecs",
      "issuer": "UP FRANCE (CHÈQUE DÉJEUNER)",
      "transaction_id": "abcd123",
      "pan": "4575******1234"
    }
  ]
}

Description

Cet endpoint est utilisé pour obtenir des informations sur un panier en fonction de son identifiant unique. La réponse fournira des informations détaillées sur le panier.

Requête

Paramètres

Nom	Type	Description	Requis
cart_id	String	Identifiant unique du panier.	Oui

Réponse

La réponse sera identique aux informations fournies dans les webhooks. Veuillez vous référer à la section Webhook pour plus d'informations.