NAV Navbar
shell python kotlin

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:

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é.

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.

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"
    },
  "acceptedPayment": {
    "acceptedMediumType": 'all'
  },
    "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 Objet 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
acceptedPayment acceptedPaymentObject Accepted Payment Types. Voir l'objet acceptedPayment

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

cloud-payment-acceptedPayment

Parameters Type Default Description
acceptedMediumType String all Lorsque le medium = card, le champ acceptedMediumType peut être utilisé pour spécifier quelles cartes accepter. En sélectionnant all cards, ou en laissant ce champ vide, le terminal acceptera toutes les cartes autorisées par le commerçant. Sinon, le terminal acceptera soit lunch_vouchers_only, soit bank_cards_only.

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 :

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

acceptedPayment structure

{
  "acceptedPayment": {
    "acceptedPaymentType": "all"
  }
}

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 Objet 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.
acceptedPayment acceptedPaymentObject Accepted Payment Types. Voir l'objet acceptedPayment

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

local-payment-acceptedPayment

Parameters Type Default Description
acceptedMediumType String all Lorsque le medium = card, le champ acceptedMediumType peut être utilisé pour spécifier quelles cartes accepter. En sélectionnant all cards, ou en laissant ce champ vide, le terminal acceptera toutes les cartes autorisées par le commerçant. Sinon, le terminal acceptera soit lunch_vouchers_only, soit bank_cards_only.

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?,
    @SerializedName("acceptedPayment")
    var acceptedPayment: AcceptedPayment?,
)
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.
acceptedPayment acceptedPayment Object Accepted Payment Types. Voir l'objet acceptedPayment

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

acceptedPayment.kt

Check kotlin section

Check kotlin section

data class AcceptedPayment(
    @SerializedName("acceptedMediumType")
    var acceptedMediumType: String?
)

android-payment-AcceptedPayment

Parameters Type Default Description
acceptedPaymentType String all Lorsque le medium = card, le champ acceptedMediumType peut être utilisé pour spécifier quelles cartes accepter. En sélectionnant all cards, ou en laissant ce champ vide, le terminal acceptera toutes les cartes autorisées par le commerçant. Sinon, le terminal acceptera soit lunch_vouchers_only, soit bank_cards_only.

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.

Flux API

ecommerce-Authentification

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

import requests

url = 'https://api.yavin.com/api/v5/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

Durée de validité du lien de paiement

Liens non utilisés:

Les liens de paiement qui n'ont aucun paiement associé resteront actifs pendant un maximum de 72 heures. Passé ce délai, le panier et le lien seront annulés.


Paniers partiellement payés:

Les paniers partiellement payés seront systématiquement annulés lorsque le script s'exécute afin de s'assurer que les fonds sont restitués au client, surtout s'il a payé avec des titres restaurants.


Si un paiement est encore nécessaire après l'annulation d'un lien, un nouveau lien de paiement devra être généré via l'endpoint /generate_link/.

É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 response_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/.

Carts avec auto_capture réglé sur False

Chaque jour à 05:00 GMT, nous exécutons un script qui va :

  • Capturer automatiquement toutes les transactions pour les carts entièrement payés avec un statut de authorised.
  • Annuler toutes les transactions pour les carts partiellement payés (statut de pending). Cela permet de s'assurer que nous libérons les fonds pour les clients ayant des commandes incomplètes (c'est particulièrement utile pour les Titres Restaurants qui ont des limites strictes sur leur plafond de dépenses).

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,
  "gift_amount": 300,
  "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": False,
  "capture_min_delay": 8,
  "order_source": "pay_at_table",
  "order_number": "CB_2",
  "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, il peut s’agir de votre identifiant interne pour suivre la transaction. Veillez à son unicité. 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 initial à payer, excluant les pourboires ou dons (gift_amount) Oui
order_number String Numéro de commande dans le logiciel de caisse, visible au client final et non interne à la caisse. L’objectif est d’associer le paiement à une commande dans la caisse pour simplifier la réconciliation en fin de journée. Oui
gift_amount Integer Le montant du pourboire ou du don, excluant le montant initial (amount). Si vous proposez à vos client de laisser un pourboire/don sur votre plateforme directement, et que vous n’utilisez pas notre fonctionnalité de pourboires intégrée, alors utilisez ce champ afin que nous ayons le bon montant reporté dans notre backoffice (chiffre d’affaires vs pourboires/dons) Non
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
capture_min_delay Integer Default: 0, Spécifie le nombre minimum d'heures à attendre après qu'un panier ait été entièrement payé avant de tenter de capturer le paiement. Ce paramètre est pertinent uniquement si auto_capture est réglé sur False. Le script utilise cette valeur pour s'assurer que le temps spécifié s'est écoulé avant de capturer les transactions. Valeurs acceptées: 0 à 72 heures (toute valeur supérieure à 72 sera par défaut fixée à 72). Non
order_source String Default: ecommerce, Doit être l'une des options suivantes: pay_at_table, click_and_collect, delivery et ecommerce Non
amount_without_tax Integer Le montant initial à payer hors taxes (excluant les pourboires ou dons (gift_amount)) Non
tax_amount Integer Le montant de la taxe (excluant les pourboires ou dons (gift_amount)) Non
webhook_url String URL pour les notifications de webhook. Doit commencer par "http". 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.

Validation

Réponses

Cette API fournit 2 types de réponses :

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

Réponse erreur

éxample + analyse

payment screen example

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_link Boolean Articles imbriqués. Voir Objet Partage Lien. None

Objet Partage Lien

share_link = {
  {
    "method": "email",
    "destination": "luke@yavin.com",
  }
}
Name Type Description Required
method String Indique la méthode pour partager le lien `email sms`
destination String Fournissez une adresse e-mail ou un numéro de téléphone en fonction de la "méthode" définie ci-dessus. Oui

Webhook

Si un webhook_url a été fourni lors de la création d'un nouveau lien, un webhook sera envoyé dès qu'une "action" aura eu lieu. Il peut s'agir de l'une des actions suivantes

webhook_data = {
  "action": "capture",
  "reason": "triggered by daily script",
  "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
action String Ce champ indique quelle action a eu lieu et a déclenché ce webhook.
reason String Ce champ fournit des informations supplémentaires sur l'action en cours. Par exemple, il pourrait expliquer la raison pour laquelle un panier a été annulé. Ce champ est généralement vide si l'action a été déclenchée en appelant l'un des endpoint.
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 total demandé dans la demande initiale (amount + gift_amount (si utilisé)), en centimes.
asked_amount Integer Le montant initial demandé dans la requête originale à capturer (valeur fournie dans le champ amount , sans inclure le gift_amount (si utilisé)), en centimes. Dans la plupart des cas, il s'agira du même montant que requested_amount,
Il pourra être différent dans le cas ou une autorisation a été demandée, et que le endpoint /capture_transactions a été appelé avec un montant inférieur au montant initial demandé (ou lorsque le champ gift_amount a été utilisé).
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 is_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

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

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.

Transactions

Cet endpoint permet de récupérer des informations détaillées sur une transaction spécifique en utilisant son identifiant unique transactionId. La réponse fournit des données complètes, notamment les montants, le statut, les horodatages et les métadonnées associées.

Transaction

Requête

curl -XGET "https://api.yavin.com/api/v5/transaction/?transactionId=123456789" \
  --header 'Yavin-Secret: YAVIN_API_KEY'

import requests

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

params = {
    "transactionId": "123456789"
}

response = requests.get(url=url, params=params, headers=headers)
print(response.json())
Paramètres Type Par Défaut Description
transactionId String (obligatoire) Identifiant unique de la transaction à récupérer.

Réponse

{
  "transactionDetails": {
    "askedAmount": 100,
    "giftAmount": 10,
    "totalAmount": 110,
    "serverDatetime": "2023-01-01T12:00:00Z",
    "deviceDatetime": "2023-01-01T12:00:00Z",
    "issuer": "BankName",
    "scheme": "Visa",
    "status": "Approved",
    "transactionId": "123456789",
    "type": "Payment",
    "serialNumber": "ABC123",
    "clientTicket": "Client ticket details",
    "companyTicket": "Company ticket details",
    "receiptTicket": {
      "data": "Receipt data",
      "format": "text"
    },
    "reference": "REF123"
  }
}
Paramètres Type Description
askedAmount Float Montant demandé en centimes. 1€ => 100
giftAmount Float Pourboire ou don en centimes
totalAmount Float Montant total de la transaction (=gift_amount + asked_amount)
serverDatetime String Date et heure côté serveur de la transaction.
deviceDatetime String Date et heure sur le terminal au moment de la transaction.
issuer String L'émetteur du moyen de paiement (ex. : banque ou institution financière).
scheme String Le schéma de paiement (ex. : Visa, Mastercard).
status String [ok / ko] Indique si la transaction a réussi ou échoué.
transactionId String Identifiant unique de la transaction.
type String Le type de transaction.
debit = transaction classique par carte bancaire.
reversal = annulation d'un paiement.
[debit, reversal, credit, refund, preauthorisation, closingbatch]
serialNumber String Numéro de série du terminal utilisé pour la transaction.
clientTicket String Détails du ticket client.
companyTicket String Détails du ticket entreprise.
receiptTicket Object Le ticket de reçu, contenant ses données et son format (ex. : texte).
reference String Référence ou métadonnée associée à la transaction.

receiptTicket objet

L'object receiptTicket contient les informations du reçu de paiement, incluant les données et le format.

Champ Type Description
data String Contenu du reçu.
format String Format du reçu. Valeur possible : text.
shell python kotlin