Intégration 1055 - Espaces de loisirs via Obypay

Créer un compte

Contact API POST /cashless/users

Prénom *

Nom *

Email * Mot de passe * 8 à 32 caractères, au moins une majuscule, une minuscule et un chiffre.

Date de naissance

Téléphone

Pays (indicatif tél.)

Langue

Accepter les communications marketing

Déjà un compte ? Se connecter · Mot de passe oublié

Mot de passe oublié

Contact API POST /cashless/users/code

Se connecter · Créer un compte

· ·

Contact API POST /cashless/users/:id/logout

Contact API

Mon profil

Contact API GET /cashless/users/me

Modifier le compte

Contact API PUT /cashless/users/:id

Prénom

Nom

Date de naissance

Téléphone

Pays (indicatif tél.)

Langue

Accepter les communications marketing

Changer le mot de passe

Contact API PUT /cashless/users/:id

Bankroll API

Recharger la cagnotte

Bankroll API POST /locations/bankrolls/accounts/{accountId}/histories

Aucun compte cagnotte détecté. Chargez le profil du contact pour récupérer l'accountId.

Transactions

Bankroll API GET /locations/bankrolls/accounts/{accountId}/histories

Bankroll API PUT /locations/bankrolls/accounts/{accountId}/histories/{historyId}

🔒 Authentification des requêtes

Certains endpoints nécessitent une authentification par token JWT (identifiés par le badge 🔒 Bearer token requis). Le token est obtenu lors du login, de la création de compte, ou de la vérification du code de mot de passe oublié.

1. Obtenir le token

Le token JWT est retourné dans le champ meta.jwt.token de la réponse des endpoints suivants :

POST /cashless/users — Création de compte
POST /auth/users/login — Connexion
POST /cashless/users/code/:code — Vérification code mot de passe oublié

2. Signer les requêtes

Pour chaque requête authentifiée, ajoutez l'en-tête Authorization avec la valeur Bearer {token} :

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfYWJj...

3. Base URL

Toutes les requêtes Contact API utilisent la base URL configurée :

4. Exemple complet (cURL)

Erreurs courantes

Code HTTP	Cause
401	Token manquant, expiré ou invalide — refaire un login pour obtenir un nouveau token
403	Token valide mais l'utilisateur n'a pas les droits pour cette ressource

POST /cashless/users — Créer un compte ▼

Crée un nouveau compte utilisateur sur la plateforme. Un token JWT est retourné directement dans la réponse, permettant une connexion immédiate après l'inscription.

Headers

Header	Valeur
Content-Type	application/json
Accept	application/json

Payload (body JSON)

Champ	Type	Description
email	string requis	Adresse email de l'utilisateur
password	string requis	Mot de passe (8-32 car., 1 maj., 1 min., 1 chiffre)
firstname	string requis	Prénom
lastname	string requis	Nom de famille
birthdate	string optionnel	Date de naissance au format JJ/MM/AAAA
phone	string optionnel	Numéro de téléphone avec indicatif (ex: +33612345678)
dialCountry	string optionnel	Code pays ISO 3166-1 alpha-2 (ex: FR, DE, BE)
lang	string optionnel	Langue (fr, en, es, de, it, da)
optin	boolean optionnel	Acceptation des communications marketing
instance	string requis	Identifiant de l'instance partenaire
g-recaptcha-response	string requis	Token reCAPTCHA v3

Exemple de payload

{
  "email": "jean.dupont@email.com",
  "password": "MonPass123",
  "firstname": "Jean",
  "lastname": "Dupont",
  "birthdate": "15/03/1990",
  "phone": "+33612345678",
  "dialCountry": "FR",
  "lang": "fr",
  "optin": true,
  "instance": "i-Htzf8i200P-1",
  "g-recaptcha-response": "03AGdBq26..."
}

Réponse succès (201)

La réponse contient le token JWT dans meta.jwt.token et l'objet utilisateur complet dans data, identique à celle de GET /cashless/users/me.

{
  "meta": {
    "message": "Compte créé avec succès",
    "jwt": {
      "token": "eyJhbGciOiJIUz..."
    }
  },
  "data": {
    // même structure que GET /cashless/users/me
  }
}

POST /auth/users/login — Connexion ▼

Authentifie un utilisateur existant et retourne un token JWT pour les requêtes ultérieures.

Payload (body JSON)

Champ	Type	Description
email	string requis	Adresse email
password	string requis	Mot de passe
instance	string requis	Identifiant de l'instance partenaire
g-recaptcha-response	string requis	Token reCAPTCHA v3

Réponse succès (200)

La réponse contient le token JWT dans meta.jwt.token et l'objet utilisateur complet dans data, identique à celle de GET /cashless/users/me.

{
  "meta": {
    "message": "Connexion réussie",
    "jwt": {
      "token": "eyJhbGciOiJIUz..."
    }
  },
  "data": {
    // même structure que GET /cashless/users/me
  }
}

GET /cashless/users/me — Récupérer le profil ▼

🔒 Bearer token requis

Récupère les informations complètes du profil de l'utilisateur connecté, incluant les données de fidélité et de cagnotte.

Headers

Header	Valeur
Authorization	Bearer {token}
Accept	application/json

Query parameters

Paramètre	Type	Description
instance	string requis	Identifiant de l'instance partenaire

Réponse succès (200)

{
  "data": {
    "id": "usr_abc123",
    "email": "jean.dupont@email.com",
    "firstname": "Jean",
    "lastname": "Dupont",
    "birthdate": "1990-03-15T00:00:00.000Z",
    "phone": "+33612345678",
    "dialCountry": "FR",
    "lang": "fr",
    "optin": true,
    "loyalty": {
      "points_validated": 150,
      "bankroll": {
        "available_amount": 2500
      }
    }
  }
}

Champs de la réponse

Champ	Type	Description
data.id	string	Identifiant unique de l'utilisateur
data.email	string	Email
data.firstname	string	Prénom
data.lastname	string	Nom
data.birthdate	string\|null	Date de naissance ISO 8601 — afficher en JJ/MM/AAAA
data.phone	string\|null	Numéro de téléphone avec indicatif
data.dialCountry	string\|null	Code pays ISO (FR, DE, etc.)
data.lang	string	Langue
data.optin	boolean	Statut opt-in marketing
data.loyalty.points_validated	number	Nombre de points de fidélité validés
data.loyalty.bankroll.id	string	Identifiant du compte cagnotte du consommateur (à utiliser comme `{accountId}` dans l'API Bankroll)
data.loyalty.bankroll.available_amount	number	Montant de cagnotte en centimes (diviser par 100 pour obtenir des euros)
data.loyalty.bankroll.bankroll.bankroll_products	array	Liste des offres de recharges de cagnotte

PUT /cashless/users/:id — Modifier le compte ▼

🔒 Bearer token requis

Met à jour les informations du profil utilisateur. Seuls les champs envoyés seront modifiés.

Headers

Header	Valeur
Authorization	Bearer {token}
Content-Type	application/json
Accept	application/json

URL Parameters

Paramètre	Type	Description
:id	string requis	ID de l'utilisateur (obtenu lors du login)

Payload (body JSON)

Champ	Type	Description
firstname	string optionnel	Prénom
lastname	string optionnel	Nom de famille
birthdate	string optionnel	Date de naissance (JJ/MM/AAAA)
phone	string optionnel	Numéro de téléphone
dialCountry	string optionnel	Code pays ISO
lang	string optionnel	Langue
optin	boolean optionnel	Opt-in marketing
instance	string requis	Identifiant de l'instance

Réponse succès (200)

La réponse est identique à celle de GET /cashless/users/me : l'objet utilisateur complet avec les données mises à jour, incluant les informations de fidélité.

{
  "meta": {
    "message": "Compte mis à jour"
  },
  "data": {
    "id": "usr_abc123",
    "firstname": "Jean-Pierre",
    ...
    // même structure que GET /cashless/users/me
  }
}

PUT /cashless/users/:id — Changer le mot de passe ▼

🔒 Bearer token requis

Change le mot de passe de l'utilisateur. Utilise le même endpoint que la modification de profil, mais avec uniquement le champ password.

Payload (body JSON)

Champ	Type	Description
password	string requis	Nouveau mot de passe (8-32 car., 1 maj., 1 min., 1 chiffre)
instance	string requis	Identifiant de l'instance

Réponse succès (200)

{
  "meta": {
    "message": "Mot de passe mis à jour"
  }
}

POST /cashless/users/:id/logout — Déconnexion ▼

🔒 Bearer token requis

Invalide le token JWT de l'utilisateur côté serveur.

Payload (body JSON)

Champ	Type	Description
instance	string requis	Identifiant de l'instance

Réponse succès (200)

{
  "meta": {
    "message": "Déconnexion réussie"
  }
}

POST /cashless/users/code — Mot de passe oublié (envoi code) ▼

Envoie un code de vérification par email à l'utilisateur pour la procédure de réinitialisation de mot de passe.

Payload (body JSON)

Champ	Type	Description
email	string requis	Adresse email du compte
instance	string requis	Identifiant de l'instance
g-recaptcha-response	string requis	Token reCAPTCHA v3

Réponse succès (200)

{
  "meta": {
    "message": "Code envoyé par email"
  }
}

POST /cashless/users/code/:code — Mot de passe oublié (vérification) ▼

Vérifie le code reçu par email. Si le code est valide, un nouveau token JWT est retourné et l'utilisateur est automatiquement connecté. Il peut ensuite changer son mot de passe via PUT /cashless/users/:id.

URL Parameters

Paramètre	Type	Description
:code	string requis	Code reçu par email

Payload (body JSON)

Champ	Type	Description
email	string requis	Adresse email du compte
g-recaptcha-response	string requis	Token reCAPTCHA v3

Réponse succès (200)

La réponse contient le token JWT dans meta.jwt.token et l'objet utilisateur complet dans data, identique à celle de GET /cashless/users/me.

{
  "meta": {
    "message": "Code vérifié",
    "jwt": {
      "token": "eyJhbGciOiJIUz..."
    }
  },
  "data": {
    // même structure que GET /cashless/users/me
  }
}

🔒 Authentification des requêtes

L'API Bankroll utilise un token API (et non un token JWT utilisateur). Ce token doit être placé directement dans l'en-tête Authorization de chaque requête. Le middleware location-bankroll valide l'accès.

⚠ ATTENTION — Token secret

Ce token est critique et strictement confidentiel. Il ne doit jamais apparaître dans le code source (HTML, JavaScript, dépôt Git) ni être utilisé dans des appels côté client (navigateur). Toutes les requêtes vers l'API Bankroll doivent transiter par un serveur backend qui injecte le token de manière sécurisée.

Signer les requêtes

Pour chaque requête, ajoutez l'en-tête Authorization avec la valeur du token API fourni :

Authorization: votre-token-api-ici

Base URL

Toutes les requêtes Bankroll API utilisent la base URL configurée :

Exemple complet (cURL)

Notes importantes

Tous les montants sont exprimés en centimes (ex : 1000 = 10,00 €)

POST /locations/bankrolls/accounts/{accountId}/histories — Recharger une cagnotte (montant libre) ▼

Recharge la cagnotte d'un compte avec un montant libre, sans bonus. Le montant crédité est celui envoyé dans le champ price.

Headers

Header	Valeur
Authorization	{token API}
Content-Type	application/json
Accept	application/json

URL Parameters

Paramètre	Type	Description
{accountId}	string requis	ID du compte cagnotte

Payload (body JSON)

Champ	Type	Description
price	int requis	Montant à créditer en centimes (ex : 550 = 5,50 €)
paid_price	int optionnel	Montant réellement payé en centimes
source	string optionnel	Source du paiement (ex : cb, cash)

Exemple de payload

{
  "price": 1000,
  "source": "cb"
}

Réponse succès (201)

{
  "id": "b7f59069-a256-41eb-a7f2-99a46cef8f3f",
  "state": "pending",
  "price": 1000,
  "paid_price": 1000,
  "source": "cb",
  "created_at": "2022-02-15 19:54:08"
}

POST /locations/bankrolls/accounts/{accountId}/histories — Recharger une cagnotte (avec bonus) ▼

Recharge la cagnotte via un produit cagnotte (bankroll_product_id). Le produit définit le montant payé (price_paid) et le montant crédité (price_added, qui inclut le bonus).

Les produits disponibles et leurs bonus sont accessibles dans les informations du Contact, dans la clé data.loyalty.bankroll.bankroll.bankroll_products (voir GET /cashless/users/me).

Headers

Header	Valeur
Authorization	{token API}
Content-Type	application/json
Accept	application/json

URL Parameters

Paramètre	Type	Description
{accountId}	string requis	ID du compte cagnotte

Payload (body JSON)

Champ	Type	Description
bankroll_product_id	string requis	UUID du produit cagnotte
source	string optionnel	Source du paiement

Exemple de payload

Exemple : payer 20 €, recevoir 25 € (bonus de 5 €) :

{
  "bankroll_product_id": "239f28f3-db3c-405b-b850-e2f383091c1b",
  "source": "cb"
}

Réponse succès (201)

{
  "id": "b7f59069-a256-41eb-a7f2-99a46cef8f3f",
  "state": "pending",
  "price": 2500,
  "paid_price": 2000,
  "source": "cb",
  "created_at": "2022-02-15 19:54:08"
}

GET /locations/bankrolls/accounts/{accountId}/histories — Lister les transactions ▼

Récupère l'historique des transactions (recharges et utilisations) d'une cagnotte.

Headers

Header	Valeur
Authorization	{token API}
Accept	application/json

URL Parameters

Paramètre	Type	Description
{accountId}	string requis	ID du compte cagnotte

Réponse succès (200)

[
  {
    "id": "4088bbf8-de54-4aa7-b34b-b2487dcbc89f",
    "state": "validated",
    "price": 2500,
    "paid_price": 2000,
    "source": "cb",
    "created_at": "2022-02-21 19:27:25"
  },
  {
    "id": "876fdbfe-57d0-4abd-887a-cf1025fbc588",
    "state": "validated",
    "price": -550,
    "paid_price": null,
    "source": "connecs",
    "created_at": "2022-02-21 19:28:27"
  }
]

Champs de la réponse

Champ	Type	Description
id	string	UUID de la transaction
state	string	Statut : `pending`, `validated`, `canceled`
price	int	Montant en centimes — positif = recharge, négatif = utilisation
paid_price	int\|null	Montant réellement payé (null pour les utilisations)
source	string	Source/contexte de la transaction
created_at	string	Date de création (YYYY-MM-DD HH:mm:ss)

POST /locations/bankrolls/accounts/{accountId}/histories/use — Utiliser un montant ▼

Débite un montant de la cagnotte d'un compte. L'API vérifie que le solde est suffisant (sinon erreur 409). Les contacts anonymes sont bloqués si is_bankroll_to_anonymous_blocked est activé.

Headers

Header	Valeur
Authorization	{token API}
Content-Type	application/json
Accept	application/json

URL Parameters

Paramètre	Type	Description
{accountId}	string requis	ID du compte cagnotte

Payload (body JSON)

Champ	Type	Description
price	int requis	Montant à débiter en centimes (ex : 550 = 5,50 €)
source	string optionnel	Source/contexte de l'utilisation

Exemple de payload

{
  "price": 550,
  "source": "connecs"
}

Réponse succès (201)

Le price envoyé est positif, mais la réponse le retourne en négatif (débit).

{
  "id": "b7f59069-a256-41eb-a7f2-99a46cef8f3f",
  "state": "pending",
  "price": -550,
  "paid_price": null,
  "source": "connecs",
  "created_at": "2022-02-15 19:54:08"
}

Erreurs courantes

Code HTTP	Cause
409	Solde insuffisant — le montant demandé dépasse le solde disponible

PUT /locations/bankrolls/accounts/{accountId}/histories/{historyId} — Valider ou annuler une transaction ▼

Met à jour le statut d'une transaction cagnotte. Permet de valider (validated) ou annuler (canceled) une transaction existante.

Headers

Header	Valeur
Authorization	{token API}
Content-Type	application/json
Accept	application/json

URL Parameters

Paramètre	Type	Description
{accountId}	string requis	ID du compte cagnotte
{historyId}	string requis	UUID de la transaction à mettre à jour

Payload (body JSON)

Champ	Type	Description
state	string requis	Nouveau statut : `validated` ou `canceled`

Exemple de payload — Valider

{
  "state": "validated"
}

Exemple de payload — Annuler

{
  "state": "canceled"
}

Réponse succès (200)

{
  "id": "b7f59069-a256-41eb-a7f2-99a46cef8f3f",
  "state": "validated",
  "price": -550,
  "paid_price": null,
  "source": "connecs",
  "created_at": "2022-02-15 19:54:08"
}

Champs de la réponse

Champ	Type	Description
id	string	UUID de la transaction
state	string	Nouveau statut de la transaction
price	number	Montant en centimes (positif = crédit, négatif = débit)
paid_price	number\|null	Montant payé (si recharge avec produit)
source	string	Source/contexte de la transaction
created_at	string	Date de création

Google reCAPTCHA v3

L'API exige un token reCAPTCHA v3 (invisible) pour les endpoints d'inscription, de connexion, et de mot de passe oublié. Ce token est envoyé dans le champ g-recaptcha-response du body.

Clé de site (Site Key)

Utilisez la clé suivante pour charger le script reCAPTCHA et exécuter les challenges :

6LfOKB0qAAAAAA6eJ-A4B1z_QS444tUsNdDqfpfj

1. Charger le script

Ajoutez cette balise dans le <head> de votre page :

2. Obtenir un token

Avant chaque appel API nécessitant le reCAPTCHA, exécutez :

grecaptcha.ready(() => { grecaptcha.execute('6LfOKB0qAAAAAA6eJ-A4B1z_QS444tUsNdDqfpfj', { action: 'submit' }) .then(token => { // Envoyer le token dans le body de la requête // champ : "g-recaptcha-response" }); });

3. Endpoints concernés

Le champ g-recaptcha-response est requis sur les endpoints suivants :

Endpoint	Méthode
/cashless/users	POST Création de compte
/auth/users/login	POST Connexion
/cashless/users/code	POST Envoi code mot de passe oublié
/cashless/users/code/:code	POST Vérification code

4. Masquer le badge reCAPTCHA

Le badge reCAPTCHA v3 apparaît par défaut en bas à droite. Pour le masquer, ajoutez ce CSS :

.grecaptcha-badge { visibility: hidden; }

Conformément aux conditions Google, si vous masquez le badge vous devez mentionner l'utilisation de reCAPTCHA dans vos CGU.

Domaines autorisés

Le reCAPTCHA ne fonctionne que sur les domaines enregistrés dans notre console Google reCAPTCHA. Actuellement autorisé :

localhost — pour le développement local

Pour vos environnements de développement, staging et production, vous devez nous fournir la liste complète de vos domaines afin que nous les ajoutions à la configuration reCAPTCHA. Sans cela, le captcha échouera et les appels API seront rejetés.

Non connecté

Configuration ▼

Authentification ▼

—

Endpoints ▼

POST /cashless/users ↗

POST /auth/users/login ↗

GET /cashless/users/me ↗

PUT /cashless/users/:id ↗

PUT /cashless/users/:id (password) ↗

POST /cashless/users/:id/logout ↗

POST /cashless/users/code ↗

POST /cashless/users/code/:code ↗

Request ▼

—

Response ▼

—

Télécharger la collection Postman

Intégration 1055 - Espaces de loisirs via Obypay

Créer un compte

Connexion

Mot de passe oublié

Contact API

Mon profil

Modifier le compte

Changer le mot de passe

Bankroll API

Recharger la cagnotte

Recharge avec bonus

Recharge libre (sans bonus)

Transactions

🔒 Authentification des requêtes

1. Obtenir le token

2. Signer les requêtes

3. Base URL

4. Exemple complet (cURL)

Erreurs courantes

Headers

Payload (body JSON)

Exemple de payload

Réponse succès (201)

Payload (body JSON)

Réponse succès (200)

Headers

Query parameters

Réponse succès (200)

Champs de la réponse

Headers

URL Parameters

Payload (body JSON)

Réponse succès (200)

Payload (body JSON)

Réponse succès (200)

Payload (body JSON)

Réponse succès (200)

Payload (body JSON)

Réponse succès (200)

URL Parameters

Payload (body JSON)

Réponse succès (200)

🔒 Authentification des requêtes

Signer les requêtes

Base URL

Exemple complet (cURL)

Notes importantes

Headers

URL Parameters

Payload (body JSON)

Exemple de payload

Réponse succès (201)

Headers

URL Parameters

Payload (body JSON)

Exemple de payload

Réponse succès (201)

Headers

URL Parameters

Réponse succès (200)

Champs de la réponse

Headers

URL Parameters

Payload (body JSON)

Exemple de payload

Réponse succès (201)

Erreurs courantes

Headers

URL Parameters

Payload (body JSON)

Exemple de payload — Valider

Exemple de payload — Annuler

Réponse succès (200)

Champs de la réponse

Google reCAPTCHA v3

Clé de site (Site Key)

1. Charger le script

2. Obtenir un token

3. Endpoints concernés

4. Masquer le badge reCAPTCHA