Guide de démarrage pour développeurs

Présentation

Comment connecter des TPE sur une borne de commande en API

VoodooKiosk permet l’utilisation de terminaux de paiement compatible CTEP et Concert en mode API.

Vous intégrez notre plateforme à votre système de la même façon qu’un PSP (Stripe, Paypal…)

Passerelle paiement carte bancaire borne commande

En quelques lignes de codes, vous êtes capables de communiquer avec les terminaux de paiement présents dans vos bornes de paiement automatiques.

1

Création un compte développeur

Rendez-vous sur dev.voodookiosk.com
Créez un compte, celui-ci vient avec suffisamment de crédits pour effectuer tous les tests d’intégration.

Rem : Après création de votre compte, vous allez devoir l’activer au moyen d’un lien contenu dans un e-mail envoyé à adresse renseignée.

Créez un compte développeur

2

Création d’une clé d’api pour générer les transactions :

Cliquez sur « API keys » dans le menu et ensuite sur « Create new api key ». Choisissez « pay » comme rôle d’api. Les autres rôles seront utiles dans d’autres cas de figure.

3

Création d’un terminal de paiement de test

Cliquez sur « Payment » , ensuite « Terminals » dans le menu et ensuite sur « New payment terminal »
Il est important de choisir « TEST » comme modèle de terminal.

Rem : Pour un terminal de test, le Numéro de Série (Serial) n’est pas important. Par contre, pour les terminaux de production, c’est un paramètre clé.

4

Réalisation de transactions de test :

a. Le premier call API à faire est un call d’authentification afin de récupérer le JWT nécessaire aux calls ultérieurs.

curl -X POST

-H ‘Content-Type: application/json’
-d ‘{« identifier »:<yourApiID>, »secret » <yourApiSecret>, »authType »: »api »}’
« https://api.voodookiosk.com/v1/auth »

Les identifiants <yourApiID> et <yourApiSecret> sont ceux créés au point 2

La réponse de ce call a cette forme :

{

« status »: »200″,
« jwt »: »<base64_encoded string>« ,
« data »:{
« typ »: »api »,
« id »: »<yourApiID>« ,
« nam »: »<your Api Name>« ,
« acc »: »<yourAccountID>« ,
« rol »: »pay »,
« exp »:1620397986
}

}

C’est la valeur du champ jwt qui devra être utilisée dans l’en-tête HTTP d’authentification du call suivant.

b. Le second call va permettre de créer une transaction.

curl -X POST \

-H ‘Authorization: Bearer <yourJWT>‘ \

-H ‘Content-Type: application/json’ \

-d ‘{

« reference »:<yourReference>,

« terminal »:<terminal_id>,

« amount »:<yourAmount>,

« ipn_url »: »https://<votre.ipn.com>« ,

« return_url »: »https://<votre.returnurl.com>« ,

« cancel_url »: »https://<votre.cancelurl.com>«

}’ \

« https://api.voodookiosk.com/v1/transaction »

“reference” : votre référence interne de la transaction.
“terminal” : l’ID du terminal auquel la transaction doit être envoyée.
“amount” : Montant de la transaction en cents.
“ipn_url” : url auquel notre plateforme va envoyer un message de finalisation de la transaction sur le terminal.
“return_url” : custom url qui sera rendu lors de l’ipn et permet au client d’avoir une indirection en fonction de son/ses clients.
“cancel_url” : custom url qui sera rendu lors de l’ipn et permet au client d’avoir une indirection en fonction de son/ses clients.

La réponse de ce call a cette forme :

{

« status »: »200″,

« msg »: »transaction created »,

« ID »: »<yourNewID>«

}

L’ID de la transaction permet de la retrouver dans le backoffice ou de demander son status au moyen d’un call api.

5

Validation ou annulation de la transaction de test :

Il est possible de simuler les différents scenarii rencontrés avec un terminal physique au moyen du backoffice.

Pour cela, cliquer sur « Payment » et ensuite « Transactions » dans le menu.
Choisissez dans la liste déroulante le terminal de test et au besoin la période de recherche.
Les transactions de tests se présentent dans la liste avec un bouton permettant de modifier leur statut.
Vous pouvez ensuite choisir dans la liste déroulante de la fenêtre modale le statut final de la transaction de test.

Après sauvegarde, l’IPN éventuellement configuré sera envoyé.

6

Envoi de l’IPN :

L’IPN envoyé par notre plateforme à l’URL renseigné au moment de la création de la transaction sera de type POST avec un payload de type Application/json. Le format de ce payload est le suivant :

{

« transaction_id »: »<yourTransactionID>« ,

« transaction_status »: »<ChoosenStatus>« ,

« transaction_reference »: »<yourReference>« ,

« transaction_amount »: »<amount>« ,

« return_url »: »<yourReturnURL>« ,

« cancel_url »: »<yourCancelURL>«

}

7

Vérification du statut d’une transaction :

Dans le cas où le système à intégrer ne supporterait pas la réception d’un call IPN, il est possible de procéder avec une méthode « pull » du statut de la transaction. L’appel api à exécuter est le suivant :

curl -X GET \