Développement partenaire

Authentification

Afin de permettre à l’API FDJ Services de communiquer avec l’API du Partenaire, deux modes d’authentification sont possibles :

• BasicAuth
• OAuth

Authentification BasicAuth

Dans le cas d’une authentification en BasicAuth, les identifiants sont fournis par le Partenaire.

Principe

L’authentification repose sur l’envoi d’un couple :

• clientId
• clientSecret

Ces informations sont transmises dans le header Authorization des requêtes HTTP, après encodage en Base64.

En-tête d’autorisation

Le header doit être formaté de la manière suivante :

Authorization: Basic {token}

Où {token} correspond à :

base64(clientId:clientSecret)

Exemple de format

Authorization: Basic {token}

Le token doit être calculé avec les valeurs réelles fournies par le Partenaire.

Règles d’utilisation

• Toutes les requêtes doivent inclure le header Authorization
• Les identifiants (clientId / clientSecret) sont fournis par le Partenaire
• Ces identifiants sont statiques, sauf indication contraire

Gestion du renouvellement

En cas de renouvellement des identifiants :

• Les nouvelles valeurs doivent être communiquées aux équipes techniques de FDJ Services
• L’ancien couple doit rester valide jusqu’à confirmation de la prise en compte du nouveau

Gestion des erreurs

Une authentification invalide retourne :

401 Unauthorized

Authentification OAuth

Afin de permettre à l’API FDJ Services de communiquer avec l’API du Partenaire, une authentification OAuth peut être utilisée.

Principe

Les éléments suivants sont fournis par le Partenaire :

• Les adresses de son API
• Le clientId et le clientSecret pour obtenir une autorisation
• Les identifiants nécessaires pour notifier une transaction

En-têtes de requête (headers)

Le header des appels effectués par FDJ Services peut utiliser les formats suivants :

• application/x-www-form-urlencoded
• application/json

Exemple :

Content-Type: application/x-www-form-urlencoded

L’en-tête d’autorisation est de la forme :

Authorization: Basic {token}

Où {token} correspond à :

base64(clientId:clientSecret)

Corps de la requête (body)

Le contenu de la requête peut inclure les paires clé/valeur définies par le Partenaire, notamment :

• grant_type : (client_credentials ou password)
• scope : scope fourni par le Partenaire

Dans le cas d’un resource owner :

• username
• password (fournis par le Partenaire)

Gestion du renouvellement des identifiants

En cas de renouvellement des identifiants :

• Les nouvelles valeurs doivent être communiquées aux équipes techniques de FDJ Services
• L’ancien couple (clientId / clientSecret) doit rester actif jusqu’à confirmation de la mise à jour

Gestion des erreurs

Une authentification invalide retourne :

401 Unauthorized

Demande d'autorisation

Ce callback permet à FDJ Services de vérifier la faisabilité d’un dépôt ou d’un retrait au moment du passage en point de vente.

Principe

• si le partenaire répond autre chose que 200, l’opération est refusée
• si FDJ Services ne peut pas joindre ce endpoint, l’opération n’est pas possible
• si le partenaire répond 200, il garantit la faisabilité de l’opération jusqu’à la date d’expiration fournie

Corps de requête

{
  "customerId": "string", // UUID du client dans le système bancaire
  "amountInCents": "number", // nombre ≥ 0 : montant total en centimes
  "currency": "string", // devise au format ISO 4217 (exemple : "EUR")
  "expirationDate": "string", // date-heure au format ISO 8601 (exemple : "2026-01-19T15:08:34.032Z")
  "operationType": "string", // valeurs autorisées : "DEPOSIT" (dépôt), "WITHDRAWAL" (retrait)
  "requestId": "string", // format UUID
  "authorizationId": "string" // deux UUID concaténés séparés par un "/" serviceResquestId/idQRCode
}

Réponse attendue

200 OK

Gestion des webhooks

Une fois que la transaction a été créé coté Nirio, un évènement transaction.created est envoyé, il faut donc le prendre en compte coté partenaire.

Événement transaction.created

{
  "eventId": "string", // UUID de l'évènement 
  "createdAt": "string", // date-time au format ISO 8601 (exemple : 2026-01-19T15:08:34.032Z)
  "sentDate": "string", // date-time au format ISO 8601 (exemple : 2026-01-19T15:08:34.032Z)
  "eventName": "transaction.created",
  "object": {
    "id": "string", // UUID de la demande de dépôt ou de retrait dans le SIP
    "amount": "number", // nombre ≥ 0 : montant total en centimes
    "authorizationId": "string", // deux UUID concaténés séparés par un "/" serviceResquestId/idQRCode
    "currency": "EUR", // devise au format ISO 4217 (valeur autorisée : "EUR")
    "datamatrixPartnerId": "string",
    "datamatrixProductId": "string",
    "freeFields": {},
    "partnerBillId": "string", // UUID de la demande de dépôt ou de retrait côté partenaire bancaire équivalent au externalId
    "partnerCustomerId": "string", // UUID du client dans le système bancaire du partenaire équivalent au customerExternalId
    "paymentMethod": "string", // Valeurs autorisées : "CSH", "CBA"
    "pointOfSaleId": "string", // UUID du point de vente 
    "processingDateTime": "string", // date-time au format ISO 8601 (exemple : 2026-01-19T15:08:34.032Z)
    "serviceFee": 0, // nombre ≥ 0 : frais de service à payer par le client pour le dépôt ou le retrait équivalent au serviceFeesInCents
    "serviceRequestId": "string", // 
    "expectedSettlementDate": "string" // date-time au format ISO 8601 (exemple : 2026-01-19T15:08:34.032Z)
  }
}