# Préface

Cette section contient des informations sur la manière d'utiliser ce document.

# Conventions utilisées dans ce document

Les conventions suivantes sont utilisées dans ce document pour identifier les types d'informations spécifiés.

# Informations sur la version du document

# Introduction

Ce document introduit et décrit l’API ouverte (Interface de Programmation Applicative) pour l’interopérabilité des Fournisseurs de Services Financiers (FSP), appelée ci-après « l’API ». L'objectif de l'API est de permettre des transactions financières interopérables entre un Payeur (un payeur de fonds électroniques dans une transaction de paiement) situé dans un FSP (une entité qui fournit un service financier numérique à un utilisateur final) et un Bénéficiaire (un destinataire de fonds électroniques dans une opération de paiement) situé dans un autre FSP. L'API ne précise aucun service frontal entre un Payeur ou un Bénéficiaire et son propre FSP ; tous les services définis dans l'API sont entre FSPs. Les FSPs sont connectés soit (a) directement entre eux, soit (b) par un Switch placé entre les FSPs pour router les transactions financières vers le FSP approprié.

Le transfert de fonds d'un Payeur à un Bénéficiaire doit être effectué en quasi temps réel. Dès qu'une transaction financière a été acceptée par les deux parties, elle est réputée irrévocable. Cela signifie qu'une transaction terminée ne peut pas être annulée dans l'API. Pour annuler une transaction, une nouvelle transaction de remboursement inverse doit être créée à partir du Bénéficiaire de la transaction d'origine.

L'API est conçue pour être suffisamment générique pour prendre en charge de nombreux cas d'utilisation et l’extensibilité de ceux-ci. Cependant, elle doit contenir suffisamment de détails pour permettre une implémentation sans ambiguïté.

La version 1.0 de l'API est conçue pour être utilisée dans un pays ou une région ; les envois internationaux nécessitant des opérations de change ne sont pas pris en charge. Cette version contient également une prise en charge de base du protocole Interledger, qui sera utilisé dans les futures versions de l’API pour gérer les transactions multi-devises et multi-intermédiaires.

Ce document :

• Définit une liaison REST asynchrone de l'API logique introduite dans Modèles de transactions génériques.
• Complète et développe les informations fournies dans Spécification Open API pour l’Interopérabilité FSP.

# Spécification Open API pour l’Interopérabilité FSP

La spécification Open API pour l’Interopérabilité FSP inclut les documents suivants.

# Documents logiques

• Modèle de données logique

• Modèles de transaction génériques

• Cas d’utilisation

# Documents de liaison REST asynchrone

• Définition de l’API

• Règles de liaison JSON

• Règles du scheme

# Intégrité des données, confidentialité et non-répudiation

• Meilleures pratiques PKI

• Signature

• Chiffrement

# Documents généraux

• Glossaire

# Définition de l’API

Cette section introduit la technologie utilisée par l’API, incluant :

• Caractéristiques générales
• Détails HTTP
• Gestion des versions de l'API

# Caractéristiques générales

Cette section décrit les caractéristiques générales de l’API.

# Style architectural

L’API est basée sur le style architectural REST (REpresentational State Transfer¹). Il existe cependant quelques différences avec une implémentation REST typique. Ces différences incluent :

• API totalement asynchrone : pour pouvoir gérer de nombreux processus longs concurrents et avoir un mécanisme unique de gestion des requêtes, tous les services API sont asynchrones. Exemples :

  • Transactions financières en lots
  • Une transaction financière nécessitant une interaction utilisateur

• Décentralisée : les services sont décentralisés, il n’existe pas d’autorité centrale pour piloter une transaction.

• Orientée service : les ressources proposées par l’API sont relativement orientées service comparées à une API REST classique.

• Pas entièrement sans état : certaines informations d’état doivent être conservées à la fois côté client et côté serveur durant le processus de transaction.

• Le client détermine l’identifiant commun : dans une implémentation REST typique (avec distinction claire client/serveur), c’est le serveur qui génère l’ID lors de la création de l’objet. Dans cette API, un devis ou une transaction financière réside à la fois dans le FSP du Payeur et du Bénéficiaire, car les services sont décentralisés. Il est donc nécessaire d’avoir un identifiant commun pour l’objet. Les raisons en sont doubles :

  • L’ID commun est utilisé dans l’URI du callback asynchrone vers le client. Le client sait donc à quelle URI écouter pour le callback correspondant à la requête.
  • Le client peut utiliser l’ID commun dans une requête HTTP GET directement s’il ne reçoit pas de callback depuis le serveur (voir Détails HTTP pour plus d’informations).

  Pour maintenir l’unicité des IDs communs, chacun est défini comme un UUID (Identifiant Universel Unique²). Pour garantir encore plus l’unicité, il est recommandé au serveur d’associer chaque ID d’objet à l’ID FSP du client. Si un serveur reçoit tout de même un ID commun non unique lors d’une requête HTTP POST (voir Détails HTTP pour plus de détails), la requête doit être gérée comme indiqué dans la section Services idempotents côté serveur.

# Protocole de niveau applicatif

HTTP, tel que défini dans RFC 7230³, est utilisé comme protocole de niveau applicatif dans l’API. Toute communication en environnement de production doit être sécurisée en utilisant HTTPS (HTTP sur TLS⁴). Pour plus de détails, voir Détails HTTP.

# Syntaxe URI

La syntaxe des URIs suit la RFC 3986⁵ pour identifier les ressources et services proposés par l’API. Cette section introduit et précise les sujets d’implémentation propres à chaque partie de la syntaxe.

Une URI générique a la forme présentée dans Exemple 1, où la partie [user:password@]host[:port] correspond à la partie Authority décrite dans la section Authority. {resource}.

# Exemple 1

scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]

Exemple 1 -- Format générique d’URI

# Scheme

Conformément à la section Protocole de niveau applicatif, le scheme sera toujours soit http, soit https.

# Autorité

La partie d’autorité consiste en une partie d’authentification optionnelle (User Information), une partie hôte obligatoire, suivie d’un port optionnel.

# Informations utilisateur

Les informations utilisateur ne devraient généralement pas être utilisées par les déploiements API ; les mesures de sécurité détaillées dans Signature API et Chiffrement API doivent être utilisées à la place.

# Hôte

L’hôte correspond à l’adresse du serveur. Il peut s’agir d’une adresse IP ou d’un nom d’hôte. Elle variera (généralement) selon le déploiement.

# Port

Le numéro de port est optionnel ; par défaut, le port HTTP est 80 et HTTPS 443, mais d’autres ports peuvent être utilisés. Le port à utiliser peut différer selon le déploiement.

# Chemin (Path)

Le chemin pointe vers une ressource ou un service effectif de l’API. Les ressources de l’API sont :

• participants
• parties
• quotes
• transactionRequests
• authorizations
• transfers
• transactions
• bulkQuotes
• bulkTransfers

Toutes les ressources ci-dessus sont également organisées de façon hiérarchique, séparées par un ou plusieurs slash ('/'). Les ressources supportent différents services selon la méthode HTTP utilisée. Toutes les ressources et services API supportés, avec URI et méthode HTTP, figurent dans le tableau 6.

# Query

La partie query est optionnelle ; elle n’est actuellement utilisée et prise en charge que par certains services de l’API. Voir les ressources API dans la section Services API pour plus de détails sur les services qui prennent en charge les chaînes de requête. Tous les autres services doivent ignorer toute chaîne de requête reçue, car des chaînes de requête pourront être ajoutées dans de futures versions mineures de l’API (voir Méthodes HTTP).

S’il y a plusieurs paires clé-valeur dans la chaîne de requête, celles-ci doivent être séparées par l’esperluette ('&').

L'exemple 2 montre un exemple d’URI issue de la ressource /authorization, où quatre paires clé-valeur différentes sont présentes, séparées par l’esperluette.

# Exemple 2

/authorization/3d492671-b7af-4f3f-88de-76169b1bdf88?authenticationType=OTP&retriesLeft=2&amount=102&currency=USD

Exemple 2 -- URI contenant plusieurs paires clé-valeur dans la chaîne de requête

# Fragment

Le fragment est une partie optionnelle d’une URI. Il n’est pris en charge par aucun service de l’API et doit donc être ignoré s’il est reçu.

# Normalisation et comparaison d’URI

Comme précisé dans la RFC 7230⁶, les parties scheme) et hôte) de l’URI doivent être considérées comme insensibles à la casse. Toutes les autres parties doivent être traitées en tenant compte de la casse.

# Jeu de caractères

Le jeu de caractères doit toujours être supposé UTF-8, défini dans 3629⁷. Il n’est donc pas nécessaire de l’indiquer dans les en-têtes HTTP (voir Champs d’en-tête HTTP). Aucun autre jeu de caractères que UTF-8 n’est pris en charge par l’API.

# Format d’échange de données

L’API utilise JSON (JavaScript Object Notation), défini dans RFC 7159⁸, comme format d’échange. JSON est ouvert, léger, lisible et indépendant de la plateforme, bien adapté pour l’échange de données entre systèmes.

# Détails HTTP

Cette section contient des informations détaillées concernant l’utilisation du protocole HTTP dans l’API.

# Champs d’en-tête HTTP

Les en-têtes HTTP sont généralement décrits dans la RFC 72309. Les deux sections suivantes décrivent les champs d’en-tête HTTP qui doivent être attendus et mis en œuvre dans l’API.

L’API prend en charge une taille maximale de 65536 octets (64 kilooctets) dans l’en-tête HTTP.

# Champs d’en-tête HTTP de requête

Le tableau 1 contient les champs d’en-tête HTTP de requête qui doivent être supportés par les implémentations de l’API. Une implémentation doit également s’attendre à d’autres champs d’en-tête HTTP standards et non standards non listés ici.

# Tableau 1

Tableau 1 -- Champs d’en-tête HTTP de requête obligatoires

Le tableau 2 liste les champs d’en-tête de requête HTTP dont la prise en charge par les implémentations de l’API est optionnelle.

# Tableau 2

Tableau 2 -- Champs d’en-tête HTTP de requête optionnels

# Champs d’en-tête HTTP de réponse

Le tableau 3 contient les champs d’en-tête HTTP de réponse obligatoires. Une implémentation peut aussi recevoir d’autres en-têtes HTTP standards ou non standards non listés ici.

# Tableau 3

Tableau 3 -- Champs d’en-tête HTTP de réponse

# Méthodes HTTP

Les méthodes HTTP suivantes, telles que définies dans RFC 7231¹⁸, sont supportées par l’API :

• GET : utilisée par le client pour demander des informations sur un objet précédemment créé côté serveur. Comme tous les services API sont asynchrones, la réponse directe à la requête GET ne contient pas l’objet demandé : cet objet viendra en callback dans une requête PUT.

• PUT : utilisée comme callback à une précédente requête GET, POST ou DELETE émise par le client. Le callback contient soit :

  • Informations sur l’objet précédemment créé (POST) ou informations demandées (GET)
  • Accusé de réception de suppression d’un objet (DELETE)
  • Informations d’erreur si la requête POST ou GET n’a pu être traitée côté serveur

• POST : utilisée par le client pour demander la création d’un objet côté serveur. Comme l’API est asynchrone, la réponse directe ne contient pas l’objet : celui-ci viendra en callback via un PUT.

• DELETE : utilisée pour demander la suppression d’un objet côté serveur. DELETE ne doit être supporté qu’au sein d’un système commun Account Lookup System (ALS) pour supprimer des informations sur une Party (détenteur de compte chez un FSP) précédemment ajoutée ; aucun autre type d’objet ne peut être supprimé. Comme tous les services sont asynchrones, la réponse à DELETE ne contient pas l’accusé de réception final : celui-ci viendra via un callback en PUT.

• PATCH : utilisée pour notifier une mise à jour d’un objet existant. Comme l’API est asynchrone, la réponse à PATCH ne contient pas de corps : cette méthode sert de notification et ne génère pas de callback.

# Séquencement HTTP

Tous les séquences et services sont asynchrones. Aucun service ne supporte le mode synchrone.

# Appel POST HTTP

La figure 1 montre le cas normal de création d’un objet dans un FSP pair via HTTP POST. Le service /service du schéma doit être remplacé par n’importe lequel des services du Tableau 6 supportant POST.

# Figure 1

Figure 1 — Séquence d’appel POST HTTP

# Appel GET HTTP

La figure 2 montre le cas d’obtention d’informations sur un objet dans un FSP pair via HTTP GET. Le service /service/{ID} doit être remplacé par n’importe quel service listé dans Tableau 6 prenant en charge GET.

# Figure 2

Figure 2 — Séquence d’appel GET HTTP

# Appel DELETE HTTP

La figure 3 décrit l’appel d’API pour supprimer des informations FSP sur une Party via HTTP DELETE dans un ALS. Le service /service/{ID} doit être remplacé par un service du Tableau 6 prenant en charge DELETE. DELETE n’est géré que par un ALS commun (c’est pourquoi l’ALS n’apparaît que côté serveur dans la figure).

# Figure 3

Figure 3 — Séquence d’appel DELETE HTTP

Remarque : il est également possible que les requêtes vers l’ALS passent par un Switch, ou que l’ALS et le Switch soient le même serveur.

# Callback PUT HTTP

Le PUT HTTP est toujours utilisé comme callback sur une requête POST, GET ou DELETE.

Le flux d’appel d’une requête PUT et de la réponse peut être observé dans les figures 1, 2 et 3 indiquées précédemment.

# Séquence PATCH HTTP

La figure 4 montre un exemple de séquence pour le PATCH HTTP, utilisé pour envoyer une notification. D’abord, un objet est créé via un POST depuis le Switch. L’objet est créé dans le FSP à l’état non finalisé. Le FSP demande ensuite à être notifié de l’état final par le Switch via un callback PUT avec l’état non finalisé. Le Switch gère le callback et envoie la notification d’état finalisé via un PATCH. La seule ressource supportant PATCH est /transfers.

# Figure 4

Figure 4 — Séquence PATCH HTTP

Remarque : les requêtes vers l’ALS peuvent aussi être routées via un Switch, voire ALS et Switch peuvent être le même serveur.

# Routage des flux d'appels avec FSPIOP-Destination et FSPIOP-Source

Les en-têtes HTTP non standard FSPIOP-Destination et FSPIOP-Source servent au routage et à la vérification de signature (voir Signature API). La figure 5 montre l’usage de ces en-têtes dans un appel POST /service abstrait, lorsque le FSP de destination est connu.

# Figure 5

Figure 5 — Usage des en-têtes HTTP personnalisés FSPIOP-Destination et FSPIOP-Source

Pour certains services avec un Switch, la destination n’est pas connue. Par exemple, un FSP envoie un GET /parties au Switch sans savoir quel autre FSP détient la Party (voir Section 6.3.2). FSPIOP-Destination sera alors vide (ou défini à l’ID du Switch) émis depuis le FSP, et renseigné à sa vraie valeur par le Switch lors du routage. Voir Figure 6 pour illustration.

# Figure 6

Figure 6 — Exemple : FSPIOP-Destination inconnu pour le FSP

# Codes de statut HTTP de réponse

L’API prend en charge les codes HTTP de réponse indiqués dans le tableau 4 :

# Tableau 4

Tableau 4 — Codes de statut HTTP supportés dans l’API

Tout code de statut HTTP 3xx²⁰ retourné côté serveur ne doit pas faire l'objet d'une nouvelle tentative et requiert une investigation manuelle.

Une implémentation de l’API doit aussi savoir gérer d’autres erreurs non listées, en particulier si la requête passe par des proxies.

Comme toutes les requêtes API sont asynchrones, les codes d’erreur HTTP serveur supplémentaires (5xx²¹ non définis au tableau 4) ne sont pas utilisés par l’API elle-même. Toute erreur serveur lors du traitement réel sera notifiée via un callback d’erreur au client (voir Section 9.2).

# Informations d’erreur en réponse HTTP

En plus du code HTTP, toutes les réponses d’erreur HTTP (4xx et 5xx) peuvent contenir un élément ErrorInformation, défini dans la section ErrorInformation. Cet élément doit, si possible, permettre de fournir plus d’informations au client.

# Services idempotents côté serveur

Tout service supportant GET doit être idempotent : la même requête peut être envoyée plusieurs fois sans changer l’objet. (L’état de l’objet côté serveur peut toutefois évoluer : par exemple, l’état d’une transaction peut changer, mais le FSP envoyant GET ne peut changer l’état).

Tout service supportant POST doit aussi être idempotent si le client réutilise le même identifiant. Le serveur ne doit pas créer un nouvel objet s’il reçoit à nouveau la même requête POST. Ceci facilite la gestion de la reprise après erreur côté client, mais impose des contraintes au serveur — voir l’exemple ici.

# Analyse des duplicats côté serveur lors de la réception d’un POST

Lors de la réception d’une requête côté serveur, il doit vérifier si un objet de service portant le même identifiant existe déjà : par exemple, si le client a déjà envoyé POST /transfers avec le même transferId. Si l’objet existe déjà, le serveur vérifie si ses paramètres correspondent à ceux de la nouvelle requête.

• Si l’objet existant a les mêmes paramètres que la nouvelle requête, on considère qu’il s’agit d’un renvoi de la part du client.

  • Si le serveur n’a pas encore traité la requête précédente/créée et n’a donc pas envoyé de callback, la nouvelle requête peut être ignorée (un callback va être envoyé de toute façon).
  • Si le serveur a fini de traiter l’ancienne requête et a déjà envoyé un callback, un nouveau callback doit être envoyé, comme si une requête GET avait été reçue.

• Si l’ancien objet n’a pas les mêmes paramètres que la requête, un callback d’erreur expliquant qu’un objet avec le même identifiant existe déjà mais avec des paramètres différents doit être envoyé au client.

Pour simplifier cette analyse, il est recommandé de stocker un hash de toutes les requêtes POST reçues côté serveur afin de les comparer facilement lors de réceptions ultérieures.

# Gestion des versions de l’API

La stratégie de développement de l’API est de maintenir la compatibilité ascendante entre l’API et ses ressources/services au maximum, cependant des changements doivent être attendus par les parties qui implémentent. La gestion des versions de l’API est propre à chaque ressource (par exemple : /participants, /quotes, /transfers).

Il existe deux types de versions de ressource API : les versions mineures (rétrocompatibles), et majeures (non rétrocompatibles).

• À chaque changement des caractéristiques de l’API impactant un service, la ressource concernée voit sa version augmentée (mineure ou majeure selon la compatibilité).
• Un changement dans un service spécifique voit sa ressource correspondante recevoir une nouvelle version.

Le format de la version de ressource est x.y où x est le numéro majeur, y le mineur. À chaque nouvelle version majeure, la version mineure repart à 0. La version initiale de chaque ressource est 1.0.

# Changements n’affectant pas la version de ressource API

Certains changements n’affecteront pas la version, par exemple : modification de l’ordre des paramètres d’une requête ou d’un callback.

# Changement mineur de version de ressource

Les modifications suivantes sont considérées comme rétrocompatibles. Les implémenteurs doivent concevoir client/serveur pour les accepter d’emblée sans casse fonctionnelle :

• Ajout de paramètres d’entrée facultatifs (chaînes de requête, etc.)
• Ajout de paramètres facultatifs dans une requête ou un callback
• Ajout de codes d’erreur

Ces changements affectent la version mineure.

# Changement majeur de version de ressource

Les modifications ci-après sont considérées comme rétro-incompatibles. L’implémenteur n’a PAS à garantir la prise en charge automatique :

• Suppression ou ajout de paramètres obligatoires
• Paramètres facultatifs devenant obligatoires
• Renommage de paramètres
• Changement de types de données
• Changement de logique métier
• Modification des URI de ressource/service

Cette liste n’est pas exhaustive.

# Négociation de version entre client et serveur

L’API prend en charge une négociation basique par HTTP content negotiation. Un client doit envoyer la version de ressource API souhaitée dans l’en-tête Accept (voir En-tête Accept HTTP). Si le serveur supporte cette version, elle est utilisée au callback (Version acceptable…). Si le serveur ne la supporte pas, il doit répondre HTTP 406²² avec une liste des versions supportées (Version non acceptable…).

# En-tête Accept HTTP

Voir ci-dessous un exemple de requête HTTP simplifiée avec seulement l’en-tête Accept²³. Il convient de l’utiliser pour un client souhaitant une version majeure précise d’une ressource. Exemple 3 : « Je souhaite la version majeure 1, sinon donne la dernière ».

# Exemple 3

POST /service HTTP/1.1
Accept: application/vnd.interoperability.{resource}+json;version=1,
application/vnd.interoperability.{resource}+json

{
    ...
}

Exemple 3 — En-tête HTTP Accept : requête pour la version 1 ou la dernière supportée

Pour l’exemple de l’exemple 3 :

• POST /service doit être remplacé par n’importe quelle méthode HTTP et le service associé (voir Tableau 6).
• L’en-tête Accept indique la version de ressource API que le client souhaite utiliser.
  • Le type d’application est toujours application/vnd.interoperability.{resource} où {resource} est la vraie ressource (participants, quotes, ...).
  • Le seul format d’échange de données actuellement supporté est json.
  • Pour n’importe quelle version mineure d’une version majeure : envoyer uniquement la version majeure : version=1 ou version=2.
  • Pour une version mineure précise : utiliser version=1.2 ou version=2.8. L’utilisation d’une version majeure.mineure spécifique est à éviter habituellement (les versions mineures étant rétrocompatibles).

# Version acceptable demandée par le client

Si le serveur supporte la version API demandée via Accept, il doit utiliser cette version dans le callback. La version majeure.mineure utilisée doit toujours être indiquée dans l’en-tête Content-Type, même si le client n’a demandé que la majeure. Par exemple (voir exemple 4) : version 1.0 utilisée :

# Exemple 4

Content-Type: application/vnd.interoperability.resource+json;version=1.0

Exemple 4 — Champ HTTP Content-Type

# Version non acceptable demandée par le client

Si le serveur ne supporte pas la version demandée dans Accept, il doit répondre HTTP 406 pour signifier l’absence de support.

Remarque : il est aussi possible que cette information soit envoyée via un callback d’erreur et non directement — par exemple si la requête passe via un Switch qui supporte la version, mais que le FSP de destination non.

En plus du HTTP 406, les versions supportées doivent figurer dans la liste des extensions de l’erreur, avec le numéro majeur comme clé et le mineur comme valeur. Voir exemple 5 : « Je ne supporte pas la version demandée, mais je supporte 1.0, 2.1 et 4.2. »

# Exemple 5

{
    "errorInformation": {
        "errorCode": "3001",
        "errorDescription": "Le client a demandé une version non supportée, voir la liste d'extensions pour les versions supportées.",
        "extensionList": {
            "extension":
            [
                { "key": "1", "value": "0"},
                { "key": "2", "value": "1"},
                { "key": "4", "value": "2"}
            ]
        }
    }
}

Exemple 5 — Message d’erreur : la version demandée n’est pas supportée

# Protocole Interledger

La version actuelle de l’API introduit une prise en charge basique du protocole Interledger (ILP), à travers l’implémentation concrète du protocole Interledger Payment Request²⁴ dans la ressource API /quotes et /transfers.

# Plus d’informations

Ce document contient les informations ILP utiles à l’API. Pour davantage d’informations, consultez le site du projet Interledger²⁵, le livre blanc Interledger²⁶, et la spécification Interledger architecture²⁷.

# Introduction à Interledger

ILP est une norme pour l’interconnexion des réseaux de paiement. De la même façon que le protocole IP constitue les bases pour la transmission et l’adressage entre réseaux de données différents, ILP définit des bases pour l’adressage des transactions financières et le transfert de valeur entre comptes sur différents réseaux de paiement.

ILP n’est pas un scheme en soi. C’est un ensemble de standards qui, s’il est mis en œuvre par plusieurs schemes de paiement, permettra leur interopérabilité. Par conséquent, implémenter ILP implique d’adapter un scheme existant à ces standards. Cela implique notamment que les transferts se fassent en deux phases (réserve et validation) et la définition d’une correspondance entre les comptes du scheme et le système d’adressage mondial ILP. Cela peut se faire en modifiant le scheme lui-même, ou via des entités qui fournissent une compatibilité ILP via des adaptateurs.

Les prérequis pour un paiement ILP sont l’adresse ILP du Bénéficiaire (voir Adressage ILP) et la condition (voir Transferts conditionnels). Dans la version actuelle de l’API, ces deux informations doivent être renvoyées par le FSP Bénéficiaire lors d’un devis (/quotes).

# Adressage ILP

Un composant clé du standard ILP est le système d’adressage²⁸. Il s’agit d’un système hiérarchique définissant une ou plusieurs adresses pour chaque compte d’un registre.

Le tableau 5 donne des exemples d’adresses ILP dans différents scénarios. À noter : la structure est standardisée, le contenu non, sauf pour le premier segment (avant le premier point).

# Tableau 5

Tableau 5 — Exemples d’adresses ILP

Le but principal d’une adresse ILP est d’identifier un compte et de router une transaction financière vers ce compte.

Remarque : Une adresse ILP ne doit pas servir à identifier une contrepartie dans l’API d’interopérabilité. Voir la section Remboursement pour l’adressage d’une Party dans l’API.

Penser à une adresse ILP comme à une adresse IP : jamais vue par l’utilisateur final, mais utilisée côté système pour router une transaction et identifier un compte. Un même compte aura souvent plusieurs adresses ILP. Le système qui tient le compte peut suivre toutes ou seulement une partie si elles partagent un préfixe commun.

# Transferts conditionnels

ILP se base sur les transferts conditionnels, où tous les registres impliqués dans une transaction financière peuvent d’abord réserver des fonds du compte Payeur puis, plus tard, les déposer dans celui du Bénéficiaire. Le transfert du Payeur au Bénéficiaire dépend de la présentation d’un accomplissement (fulfilment) qui respecte la condition associée à la requête d’origine.

Pour supporter les transferts conditionnels, un registre doit permettre d’attacher une condition et une expiration à chaque transfert. Le registre doit réserver les fonds du compte Payeur, puis attendre l’un des événements suivants :

• L’accomplissement de la condition est soumis au registre : les fonds sont crédités sur le compte du Bénéficiaire.
• L’expiration est atteinte, ou la transaction est rejetée (par le Bénéficiaire, son FSP…). Le transfert est alors annulé et les fonds remis au Payeur.

Lorsqu’un accomplissement est soumis, le registre doit s’assurer qu’il satisfait bien la condition associée à la requête. Si oui, le transfert est validé ; sinon, il est refusé, et reste en attente jusqu’à obtention d’un accomplissement valide ou expiration.

ILP supporte différentes conditions, mais les implémenteurs de l’API doivent utiliser le hash SHA-256 d’un pré-image de 32 octets. La condition jointe au transfert est le SHA-256, l’accomplissement étant le pré-image. Ainsi, quand la condition jointe est un SHA-256, une fois un accomplissement soumis, le registre le valide en calculant son SHA-256 et vérifiant qu’il correspond.

Voir Interledger Payment Request pour des informations concrètes sur la génération de l’accomplissement (fulfilment) et de la condition.

# Paquet ILP

Le paquet ILP sert à emballer des données de bout en bout pouvant être transmises service par service. Il est inclus comme champ dans les requêtes « hop by hop » et ne doit jamais être modifié par un intermédiaire. L'intégrité du paquet est liée à celle du transfert de fonds, car le déclencheur de validation (fulfilment) est généré à partir d'un hash du paquet.

Le paquet a un format binaire strict, car il peut transiter par des systèmes à haut débit/volume, qui doivent lire l’adresse ILP et le montant depuis les headers, sans avoir à interpréter le champ data du paquet (voir Exemple 6). Comme ils ne doivent pas l’interpréter, ce champ reste au format octet variable dans la définition. Voir Interledger Payment Request pour le détail sur la manière de peupler ce champ dans l’API.

Le paquet ILP relie les transferts livre à livre qui composent tout paiement ILP. Il est parsé par le destinataire du premier transfert, utilisé pour savoir vers où router le suivant et pour quel montant, lui est passé, etc., jusqu’au Bénéficiaire final qui fournit l’accomplissement, ce qui valide les transferts en chaîne, du dernier au premier.

Le format du paquet ILP est défini en ASN.1²⁹ (Abstract Syntax Notation One), voir Exemple 6. L’encodage se fait avec les règles canoniques Octet Encoding Rules.

# Exemple 6

InterledgerProtocolPaymentMessage ::= SEQUENCE {
    -- Montant qui doit être reçu à destination : amount UInt64,
    -- Adresse ILP destinataire : account Address,
    -- Information pour le destinataire (couche de transport) : data OCTET STRING (SIZE (0..32767)),
    -- Extensibilité ASN.1
    extensions SEQUENCE {
        ...
    }
}

Exemple 6 — Format du paquet ILP en ASN.1

Remarque : Les seuls éléments obligatoires sont le montant à transférer au Bénéficiaire et son adresse ILP.

# Fonctionnalités courantes de l'API

Cette section décrit les fonctionnalités communes utilisées par l'API, incluant :

• Devis (Quoting)
• Adressage des Parties
• Mapping de cas d’utilisation vers les types de transactions

# Devis (Quoting)

Le devis est le processus qui détermine les frais et les commissions nécessaires pour effectuer une transaction financière entre deux FSP. Il est toujours initié par le FSP Payeur vers le FSP Bénéficiaire, ce qui signifie que le devis circule dans le même sens qu'une transaction financière.

Deux modes différents pour établir un devis entre FSP sont pris en charge dans l’API : Non-divulgation des frais et Divulgation des frais.

• La Non-divulgation des frais doit être utilisée lorsque le FSP Payeur ne souhaite pas montrer sa structure de frais au FSP Bénéficiaire, ou lorsqu’il souhaite avoir plus de contrôle sur les frais payés par le Payeur une fois le devis établi (ce dernier cas s’applique uniquement pour le montant à recevoir ; voir la liste suivante).

• La Divulgation des frais peut être utilisée dans des cas où le FSP Bénéficiaire souhaite subventionner la transaction ; par exemple, lors d'un dépôt d'espèces chez un agent d’un autre FSP.

La Non-divulgation des frais doit être le mode standard de devis supporté dans la plupart des schémas. La Divulgation des frais peut être utilisée dans certains schémas, par exemple lorsqu’une structure de frais dynamique est utilisée et qu’un FSP souhaite pouvoir subventionner le cas d’usage de dépôt d’espèces sur la base d’un coût dynamique.

En outre, le Payeur peut décider si le montant doit être un montant à recevoir ou montant à envoyer.

• Montant à envoyer doit être interprété comme le montant réel à déduire du compte du Payeur, frais inclus.

• Montant à recevoir doit être interprété comme le montant qui doit être crédité sur le compte du Bénéficiaire, indépendamment des frais de transaction interopérables. Ce montant exclut d’éventuels frais internes ajoutés par le FSP Bénéficiaire.

Le FSP Bénéficiaire peut choisir d’envoyer ou non le montant réellement reçu par le Bénéficiaire dans la réponse au FSP Payeur. Ce montant doit inclure les éventuels frais internes appliqués par le FSP Bénéficiaire au Bénéficiaire.

Toutes les taxes sont supposées être internes au FSP, ce qui signifie qu'elles ne sont pas transmises via l'API. Consultez Informations fiscales pour plus de détails sur la fiscalité.

Remarque : Les frais dynamiques mis en œuvre via un Switch ou tout autre intermédiaire ne sont pas pris en charge dans cette version de l’API.

# Non-divulgation des frais

Les paiements de frais et de commissions relatifs à une transaction interopérable lorsque les frais ne sont pas divulgués sont illustrés dans la Figure 7. Les frais et commissions faisant directement partie de l’API sont identifiés en texte vert. Les éléments internes (frais, commissions, bonus internes) sont identifiés en texte rouge—et ne font pas partie de la transaction entre un FSP Payeur et un FSP Bénéficiaire, mais le montant reçu par le Bénéficiaire après déduction de frais internes peut être communiqué à titre informatif par le FSP Bénéficiaire.

Pour un montant à envoyer (voir Montant à envoyer sans divulgation), des frais internes du FSP Payeur appliqués au Payeur vont affecter le montant envoyé par ce FSP (ex : pour une transaction de 100 USD avec 1 USD de frais, 99 USD sont envoyés). Pour un montant à recevoir (voir Montant à recevoir sans divulgation), ces frais internes n'ont pas d'effet sur le montant envoyé. Les bonus ou commissions internes du FSP Payeur doivent être cachés, quel que soit le mode (envoi/réception).

# Figure 7

Figure 7 -- Frais et commissions liés à l’interopérabilité lorsque les frais ne sont pas divulgués

Voir Types de frais pour plus d’informations sur les types de frais envoyés via l’API.

# Montant à recevoir sans divulgation

Figure 8 présente un exemple de montant à recevoir sans divulgation, où le Payeur souhaite que le Bénéficiaire reçoive exactement 100 USD. Dans ce cas, le FSP Payeur ne fixe pas nécessairement les frais internes avant d’avoir reçu le devis, puisque le FSP Bénéficiaire connaît déjà le montant qu’il recevra.

Dans cet exemple, le FSP Bénéficiaire décide de verser une commission au FSP Payeur, car les fonds sont injectés dans le système du FSP Bénéficiaire et seront ultérieurement dépensés, ce qui représente un gain futur pour le FSP Bénéficiaire. Le FSP Payeur décide ensuite des frais à facturer au Payeur. Par exemple, s'il veut percevoir 1 USD de frais du Payeur (et reçoit aussi 1 USD de commission), il gagne au total 2 USD.

# Figure 8

Figure 8 -- Exemple de montant à recevoir sans divulgation

# Figure 9

Figure 9 -- Vue simplifiée du mouvement de fonds pour l’exemple précédent

Pour calculer l’élément transferAmount dans le FSP Bénéficiaire pour un devis à montant à recevoir sans divulgation, appliquer l’équation Listing 9, où le Montant de transfert correspond à transferAmount (Tableau 24), le Montant du devis à amount (Tableau 23), les frais FSP Bénéficiaire à payeeFspFee (Tableau 24), et la commission FSP Bénéficiaire à payeeFspCommission (Tableau 24).

# Listing 7

Montant de transfert = Montant du devis + Frais FSP Bénéficiaire – Commission FSP Bénéficiaire

Listing 7 -- Relation entre le montant de transfert et le montant du devis pour ce cas

# Montant à envoyer sans divulgation

Figure 10 montre un exemple où le Payeur souhaite envoyer 100 USD. Ici, le FSP Payeur doit déterminer les frais, commissions ou les deux avant d’envoyer le devis, pour que le FSP Bénéficiaire connaisse le montant qui sera reçu. Le montant retiré du compte du Payeur n’est pas communiqué, ni les frais.

Dans cet exemple, le FSP Payeur et le FSP Bénéficiaire veulent chacun 1 USD de frais, donc le Bénéficiaire recevra 98 USD. Le montant reçu peut être indiqué dans la réponse sous l’élément payeeReceiveAmount, mais ce n’est pas obligatoire.

# Figure 10

Figure 10 -- Exemple de montant à envoyer sans divulgation

# Figure 11

Figure 11 : vue simplifiée du mouvement d’argent.

Figure 11 -- Vue simplifiée du mouvement de fonds pour cet exemple

Pour calculer transferAmount, utiliser l’équation du Listing 8 : Montant du transfert = transferAmount (Tableau 24), Montant du devis = amount, commission = payeeFspCommission.

# Listing 8

Montant de transfert = Montant du devis – Commission FSP Bénéficiaire

Listing 8 -- Relation entre le montant de transfert et le montant du devis pour ce cas

La raison pour laquelle les frais FSP Bénéficiaire sont absents de l’équation : le Payeur veut envoyer un certain montant de son compte, le Bénéficiaire reçoit donc moins au lieu que des frais soient ajoutés au montant.

# Divulgation des frais

Les paiements de frais et de commissions relatifs à une transaction interopérable lorsque les frais sont divulgués se trouvent en Figure 12. Ce qui est directement lié à l’API est indiqué en vert. Les frais, bonus, et commissions internes sont en rouge : ils impactent le montant envoyé/reçu mais ne sont pas transmis dans la transaction interopérable. Le montant net reçu par le Bénéficiaire (après frais internes) peut être transmis à titre d’information.

Quand la divulgation des frais est utilisée, la commission envoyée par le FSP Bénéficiaire doit subventionner tout ou partie du coût de la transaction pour le Payeur. Si la commission est supérieure aux frais pour le Payeur, l’excédent doit être traité comme un frais payé du Bénéficiaire au Payeur. Un exemple : ici.

# Figure 12

Figure 12 -- Frais et commissions liés à l’interopérabilité lorsque les frais sont divulgués

Voir Types de frais pour plus d'informations.

# Montant à recevoir avec divulgation

Figure 13 : le Payeur veut que le Bénéficiaire reçoive 100 USD. Le FSP Payeur doit évaluer la transaction en interne avant d’envoyer la demande de devis, car les frais sont divulgués. Exemple : le FSP Payeur veut 1 USD de frais, le FSP Bénéficiaire attribue 1 USD de commission pour subventionner, rendant la transaction gratuite pour le Payeur.

# Figure 13

Figure 13 -- Exemple avec montant à recevoir en divulgation

Figure 14 : vue simplifiée.

# Figure 14

Figure 14 -- Vue simplifiée du mouvement de fonds

Pour calculer transferAmount côté FSP Bénéficiaire pour ce type de devis, appliquer l'équation du Listing 9, où Montant transfert = transferAmount, Montant devis = amount, frais FSP Bénéficiaire = payeeFspFee, commission FSP Bénéficiaire = payeeFspCommission.

# Listing 9

Montant de transfert = Montant du devis + Frais FSP Bénéficiaire – Commission FSP Bénéficiaire

Listing 9 -- Relation pour ce cas

# Montant à envoyer avec divulgation

Figure 15 : le Payeur souhaite envoyer 100 USD au Bénéficiaire. Les frais doivent être calculés avant la demande de devis, car ils sont divulgués. Exemple : chaque FSP souhaite 1 USD de frais.

# Figure 15

Figure 15 -- Exemple avec montant à envoyer en divulgation

# Figure 16

Figure 16 : vue simplifiée du mouvement de fonds.

Figure 16 -- Vue simplifiée pour ce cas

Pour calculer transferAmount (côté FSP Bénéficiaire), l’équation du Listing 10 doit être utilisée :

# Listing 10

Si (Frais Payeur <= Commission FSP Bénéficiaire)
    Montant de transfert = Montant du devis
Sinon
    Montant de transfert = Montant du devis – (Frais Payeur – Commission FSP Bénéficiaire)

Listing 10 -- Relation pour ce cas

Les frais FSP Bénéficiaire sont absents : on souhaite envoyer un montant précis, le Bénéficiaire reçoit donc moins, plutôt que d’ajouter les frais « par-dessus ».

# Exemple d’excédent de commission FSP

Figure 17 : excédent de commission FSP avec divulgation du montant à envoyer : le Payeur souhaite envoyer 100 USD, le FSP Payeur veut 1 USD de frais, le FSP Bénéficiaire donne 3 USD de commission. Sur les 3 USD, 1 USD couvre les frais Payeur, 2 USD reviennent au FSP Payeur.

# Figure 17

Figure 17 -- Exemple d’excédent de commission

# Figure 18

Figure 18 : vue simplifiée du mouvement de fonds.

Figure 18 -- Vue simplifiée pour ce cas

# Types de frais

Comme vu en Figure 7 et Figure 12, il existe deux types de frais et commissions dans l’objet Quote entre FSP :

1. Frais FSP Bénéficiaire : frais de transaction que le FSP Bénéficiaire souhaite obtenir pour la gestion de la transaction.
2. Commission FSP Bénéficiaire : commission que le FSP Bénéficiaire veut verser au FSP Payeur (non-divulgation) ou subventionner la transaction en payant à la place du FSP Payeur (divulgation). Si excédent, il est traité comme frais payé du Bénéficiaire vers le Payeur, voir l’exemple d’excès de commission.

# Équations de devis

Section contenant des formules utiles pour les devis qui n’ont pas encore été mentionnées.

# Relation entre montant reçu par le Bénéficiaire et montant de transfert

Le montant que doit recevoir le Bénéficiaire, hors frais internes, bonus ou commission FSP Bénéficiaire, peut être calculé par le FSP Payeur via Listing 11. Montant de transfert = transferAmount, frais FSP Bénéficiaire = payeeFspFee, commission = payeeFspCommission.

# Listing 11

Montant reçu Bénéficiaire = Montant de transfert - Frais FSP Bénéficiaire + Commission FSP Bénéficiaire

Listing 11 -- Relation entre montant de transfert et montant reçu

Le montant reçu peut optionnellement être transmis lors du retour du devis sous payeeReceiveAmount.

# Informations fiscales

Aucune information de taxe n’est transmise via l’API (toute la fiscalité est considérée comme interne). Les sections suivantes détaillent les cas les plus courants.

# Taxe sur la commission des agents

Taxe sur la commission d’un agent (en tant que revenu). C’est l’agent ou son FSP qui gère la relation avec l’administration fiscale, selon le cas. Toutes les commissions agent étant internes, rien n’est transmis dans l’API.

# Taxe sur les frais internes FSP

Un FSP peut être taxé sur certains frais internes reçus : ex : frais Payeur vers son FSP, ou frais Bénéficiaire vers son FSP. Cette taxe doit être gérée et collectée en interne par le FSP concerné.

# Taxe sur le montant (TVA, taxe de vente, ... )

La TVA ou les taxes de vente sont des taxes sur un montant, typiquement supportées par le consommateur lors d’un achat marchand. Le marchand collecte la taxe et reverse à l’administration. Si la TVA s’applique, elle doit être incluse dans la somme demandée au client, et le montant reçu par le FSP Bénéficiaire est taxé en conséquence.

# Taxe sur frais FSP

Dans l’API, un FSP Bénéficiaire peut ajouter un frais à payer par le Payeur ou son FSP. Il doit gérer la fiscalité conformément à la pratique locale, en interne et sans transmettre de détail via l’API.

# Taxe sur la commission FSP

Un FSP Bénéficiaire peut ajouter une commission, soit pour subventionner la transaction (divulgation), soit pour inciter le FSP Payeur (non-divulgation).

# Non-divulgation des frais

Dans ce cas, toute commission FSP Bénéficiaire doit être considérée comme un frais reçu par le FSP Payeur. La taxe correspondante est gérée en interne comme tout frais reçu.

# Divulgation des frais

Si le montant de commission est inférieur ou égal aux frais à la charge du Payeur, la commission sert à couvrir ces frais. Si elle les dépasse, l’excédent est traité comme dans la non-divulgation.

# Exemples pour chaque cas d’usage

Cette section présente un ou plusieurs exemples pour chaque cas.

# Virement P2P

Un virement P2P est typiquement un montant à recevoir, sans aucune divulgation de frais côté Bénéficiaire (Figure 19). Ex : le Payeur veut que le Bénéficiaire reçoive 100 USD. Le FSP Bénéficiaire offre une commission au FSP Payeur. Le FSP Payeur prend 1 USD de frais à son client : il gagne donc 2 USD (1 USD venant du client, 1 USD en commission). 99 USD sont transférés après déduction de la commission.

# Figure 19

Figure 19 -- Exemple virement P2P avec montant à recevoir

# Vue simplifiée du mouvement de fonds

# Figure 20

Voir Figure 20 pour une vue très simplifiée du mouvement.

Figure 20 -- Vue simplifiée virement P2P

# Dépôt d’espèces initié par l’agent (Montant à envoyer)

Figure 21 : dépôt avec divulgation des frais. Le Bénéficiaire veut savoir les frais avant d’accepter l’opération. Exemple : le client souhaite déposer 100 USD chez un agent du FSP Payeur. Celui-ci prend 2 USD de frais, le FSP Bénéficiaire subventionne la transaction avec 2 USD de commission pour couvrir ces frais. 98 USD sont transférés après déduction de la commission.

# Figure 21

Figure 21 -- Exemple dépôt agent, montant à envoyer

# Vue simplifiée

Voir Figure 22.

# Figure 22

Figure 22 -- Vue simplifiée dépôt agent

# Dépôt d’espèces initié par l’agent (Montant à recevoir)

Figure 23 : dépôt avec divulgation des frais, client souhaite recevoir exactement 100 USD. Le FSP Payeur souhaite 2 USD de frais pour la commission agent ; le FSP Bénéficiaire subventionne 1 USD en commission (50 % des frais). 99 USD transférés après déduction de la commission.

# Figure 23

Figure 23 -- Exemple dépôt agent, montant à recevoir

# Vue simplifiée

# Figure 24

Voir Figure 24.

Figure 24 -- Vue simplifiée dépôt agent montant à recevoir

# Paiement marchand initié par le client

Typiquement un montant à recevoir sans divulgation des frais. Ex : achat de biens/ services pour 100 USD auprès d’un marchand dans le FSP Bénéficiaire. Le FSP Bénéficiaire ne facture pas le client mais prend un frais caché d’1 USD au marchand. Le FSP Payeur prélève 1 USD au client. 100 USD sont transférés.

# Figure 25

Figure 25 -- Exemple paiement marchand client

# Vue simplifiée

Voir Figure 26.

# Figure 26

Figure 26 -- Vue simplifiée paiement marchand client

# Retrait d’espèces initié par le client (Montant à recevoir)

Typiquement, montant à recevoir sans divulgation des frais. Ex : le client veut retirer 100 USD en espèces. Le FSP Bénéficiaire prend 2 USD de frais (commission agent), le FSP Payeur prend 1 USD. 102 USD transférés.

# Figure 27

Figure 27 -- Exemple retrait client (montant à recevoir)

# Vue simplifiée

Voir Figure 28.

# Figure 28

Figure 28 -- Vue simplifiée retrait client (montant à recevoir)

# Retrait d’espèces initié par le client (Montant à envoyer)

Normalement, typiquement montant à recevoir, mais ici exemple avec montant à envoyer : voir Figure 29. Le client veut retirer 100 USD de son compte. Le FSP Bénéficiaire prend 2 USD (commission agent), le FSP Payeur prend 1 USD. 99 USD transférés.

# Figure 29

Figure 29 -- Exemple retrait client (montant à envoyer)

# Vue simplifiée

Voir Figure 30.

# Figure 30

Figure 30 -- Vue simplifiée retrait client (montant à envoyer)

# Retrait initié par agent

Montant à recevoir, pas de divulgation des frais côté FSP Payeur. Ex : le client veut recevoir 100 USD en liquide. Frais : 2 USD côté FSP Bénéficiaire ; 1 USD côté FSP Payeur. 102 USD transférés.

# Figure 31

Figure 31 -- Exemple retrait agent

# Vue simplifiée

Voir Figure 32.

# Figure 32

Figure 32 -- Vue simplifiée retrait agent

# Paiement marchand initié par le marchand

Montant à recevoir, pas de divulgation des frais. Ex : achat de 100 USD, aucun frais Bénéficiaire, mais 1 USD de frais côté Payeur. 100 USD transférés.

# Figure 33

Figure 33 -- Exemple paiement marchand initié par marchand

# Vue simplifiée

Voir Figure 34.

# Figure 34

Figure 34 -- Vue simplifiée paiement marchand initié par marchand

# Retrait initié par ATM

Montant à recevoir, pas de divulgation. Ex : retrait de 100 USD en espèces, 1 USD de frais côté FSP Bénéficiaire (frais ATM), 1 USD côté FSP Payeur. 101 USD transférés.

# Figure 35

Figure 35 -- Exemple retrait ATM

# Vue simplifiée

Voir Figure 36.

# Figure 36

Figure 36 -- Vue simplifiée retrait ATM

# Paiement marchand initié par le marchand autorisé sur un TPE

Montant à recevoir, pas de divulgation des frais. Ex : achat de 100 USD, le FSP Bénéficiaire accorde 1 USD de commission, le FSP Payeur l’utilise comme frais. 100 USD transférés.

# Figure 37

Figure 37 -- Exemple paiement marchand sur TPE

# Vue simplifiée

Voir Figure 38.

# Figure 38

Figure 38 -- Vue simplifiée paiement marchand sur TPE

# Remboursement

Figure 39 présente un exemple de remboursement du montant entier d’un dépôt d’espèces (voir exemple plus haut).

# Figure 39

Figure 39 -- Exemple de remboursement

# 5.1.6.11.1 Vue simplifiée du mouvement de fonds

Voir Figure 40.

# Figure 40

Figure 40 -- Vue simplifiée du remboursement

# Adressage des Parties

Les deux parties d’une transaction financière (le Payeur et le Bénéficiaire) sont identifiées dans l’API par un Type d’ID de Partie (PartyIdType), un ID de Partie (PartyIdentifier), et, éventuellement, un Sous-ID ou Type de Partie (PartySubIdOrType). Certains sous-types sont prévus en standard pour des identifiants personnels (PersonalIdentifierType), par ex. pour le numéro de passeport ou le permis de conduire.

Exemples de base d’utilisation des éléments Party ID Type et Party ID :

• Pour utiliser le numéro de téléphone mobile +123456789 comme contrepartie, mettre Party ID Type à MSISDN et Party ID à +123456789.

  • Exemple de service pour obtenir le FSP :

    **GET /participants/MSISDN/+123456789**
    

• Pour utiliser l'adresse email john@doe.com, mettre Party ID Type à EMAIL et Party ID à john@doe.com.

  • Exemple :

    **GET /participants/EMAIL/john\@doe.com**
    

• Pour utiliser l’IBAN SE45 5000 0000 0583 9825 7466 : Party ID Type = IBAN, Party ID = SE4550000000058398257466 (sans espaces).

  • Exemple :

    **GET /participants/IBAN/SE4550000000058398257466**
    

Exemples avancés :

• Pour une personne dont le numéro de passeport est 12345678 : Party ID Type = PERSONAL_ID, Party ID = 12345678, Party Sub ID or Type = PASSPORT.

  • Exemple :

    **GET /participants/PERSONAL_ID/123456789/PASSPORT**
    

• Pour employeeId1 travaillant chez Shoe-company : Party ID Type = BUSINESS, Party ID = Shoe-company, Party Sub ID or Type = employeeId1

  • Exemple :

    **GET /participants/BUSINESS/Shoe-company/employeeId1**
    

5.2.1 Caractères interdits dans Party ID et Party Sub ID or Type

Le Party ID et Party Sub ID or Type font partie de l’URI (voir Syntaxe URI), donc certaines restrictions existent :

• Barre oblique (/) interdite (utilisée dans le Path pour la séparation).
• Point d’interrogation (?) interdit (identifie la Query dans l’URI).

# Correspondance des cas d’usage et des types de transaction

Cette section décrit comment mapper les cas d’usage non-bulk actuellement supportés dans l’API vers le type complexe TransactionType), en utilisant les éléments TransactionScenario), et TransactionInitiator).

Plus de détails dans Cas d’usage de l’API.

# Virement P2P

Pour effectuer un virement P2P :

• TransactionScenario = TRANSFER
• TransactionInitiator = PAYER
• TransactionInitiatorType = CONSUMER

# Dépôt d’espèces initié par agent

• TransactionScenario = DEPOSIT
• TransactionInitiator = PAYER
• TransactionInitiatorType = AGENT

# Retrait d’espèces initié par agent

• TransactionScenario = WITHDRAWAL
• TransactionInitiator = PAYEE
• TransactionInitiatorType = AGENT

# Retrait d’espèces par agent sur TPE

• TransactionScenario = WITHDRAWAL
• TransactionInitiator = PAYEE
• TransactionInitiatorType = AGENT

# Retrait d’espèces initié par client

• TransactionScenario = WITHDRAWAL
• TransactionInitiator = PAYER
• TransactionInitiatorType = CONSUMER

# Paiement marchand initié par client

• TransactionScenario = PAYMENT
• TransactionInitiator = PAYER
• TransactionInitiatorType = CONSUMER

# Paiement marchand initié par marchand

• TransactionScenario = PAYMENT
• TransactionInitiator = PAYEE
• TransactionInitiatorType = BUSINESS

# Paiement marchand initié par marchand sur TPE

• TransactionScenario = PAYMENT
• TransactionInitiator = PAYEE
• TransactionInitiatorType = DEVICE

# Retrait initié par ATM

• TransactionScenario = WITHDRAWAL
• TransactionInitiator = PAYEE
• TransactionInitiatorType = DEVICE

# Remboursement

Pour effectuer un remboursement, configurez les éléments comme suit :

• TransactionScenario à REFUND
• TransactionInitiator à PAYER
• TransactionInitiatorType dépend de l’initiateur du remboursement.

De plus, le type complexe Refund doit être renseigné avec l’identifiant de la transaction d’origine à rembourser.

# Services de l’API

Cette section présente et détaille tous les services que l’API prend en charge pour chaque ressource et méthode HTTP. Chaque ressource et service de l’API est également mappé à une ressource et un service logique décrits dans les Modèles génériques de transaction.

# Services API de haut niveau

À un niveau élevé, l’API peut être utilisée pour réaliser les actions suivantes :

• Recherche d’informations sur un participant — Déterminer dans quel FSP se situe la contrepartie d’une transaction financière.

  • Utilisez les services fournis par la ressource API /participants.

• Recherche d’informations sur une partie — Obtenir des informations sur la contrepartie d’une transaction financière.

  • Utilisez les services fournis par la ressource API /parties.

• Demande de transaction — Demander à un payeur de transférer des fonds électroniques au bénéficiaire, à la demande du bénéficiaire. Le payeur peut approuver ou refuser la demande. Une approbation initiera effectivement la transaction financière.

  • Utilisez les services fournis par la ressource API /transactionRequests.

• Calculer une devis — Calculer tous les éléments d’une transaction qui influenceront le montant de la transaction, c’est-à-dire les frais et la commission du FSP.

  • Utilisez les services fournis par la ressource API /quotes pour le devis d’une transaction individuelle (un payeur vers un bénéficiaire).
  • Utilisez les services fournis par la ressource API /bulkQuotes pour le devis d’une transaction groupée (un payeur vers plusieurs bénéficiaires).

• Réaliser une autorisation — Demander au payeur de saisir les identifiants requis lorsqu’il a initié la transaction depuis un terminal de paiement, un DAB, ou un appareil similaire dans le système FSP du bénéficiaire.

  • Utilisez les services fournis par la ressource API /authorizations.

• Effectuer un transfert — Réaliser effectivement la transaction financière en transférant les fonds électroniques du payeur au bénéficiaire, éventuellement via des registres intermédiaires.

  • Utilisez les services fournis par la ressource API /transfers pour une transaction unique (un payeur vers un bénéficiaire).
  • Utilisez les services fournis par la ressource API /bulkTransfers pour une transaction groupée (un payeur vers plusieurs bénéficiaires).

• Récupérer les informations de transaction — Obtenir les informations relatives à la transaction financière ; par exemple, un jeton créé en cas de transaction réussie.

  • Utilisez les services fournis par la ressource API /transactions.

# Services API pris en charge

Tableau 6 inclut des descriptions de haut niveau des services que l’API propose. Pour plus d’informations détaillées, consultez les sections suivantes.

# Tableau 6

Tableau 6 – Services fournis par l’API

# Versions actuelles des ressources

Tableau 7 contient la version de chaque ressource décrite dans ce document.

# Tableau 7

Tableau 7 – Versions actuelles des ressources

# Ressource API /participants

Cette section définit la ressource API logique Participants, décrite dans les Modèles génériques de transaction.

Les services fournis par la ressource /participants servent principalement à déterminer dans quel FSP se trouve la contrepartie d’une transaction financière. Selon le schéma, ces services doivent être pris en charge, au minimum, soit par les FSP individuels soit par un service commun.

Si un service commun (par exemple, un ALS) est pris en charge dans le schéma, les services de la ressource /participants peuvent aussi être utilisés par les FSP pour ajouter et supprimer des informations dans ce système.

# Historique des versions de la ressource

Tableau 8 fournit une description de chaque version différente de la ressource /participants.

# Tableau 8

Tableau 8 – Historique des versions pour la ressource /participants

# Détails des services

Différents modèles sont utilisés pour la recherche de compte, selon qu’un ALS existe ou non. Les sections suivantes décrivent chaque modèle à tour de rôle.

# Système sans service commun de recherche de comptes

Figure 41 montre comment effectuer une recherche de compte s’il n’existe pas d’ALS commun dans un schéma. Le processus consiste à demander aux autres FSP (en séquence) s’ils « possèdent » la partie avec le couple identité/type délivré jusqu’à trouver la partie.

Si ce modèle est utilisé, tous les FSP doivent prendre en charge à la fois la partie cliente et serveur des différents services HTTP GET de la ressource /participants. Les services HTTP POST ou DELETE de la ressource /participants ne doivent pas être utilisés, car les FSP sont directement sollicités pour récupérer les informations (au lieu d’un ALS commun).

# Figure 41

Figure 41 — Comment utiliser les services fournis par /participants s’il n’existe pas de système commun de recherche de comptes

# Système de recherche de comptes commun

Figure 42 montre comment une recherche de compte peut être effectuée s’il existe un ALS commun dans un schéma. Le processus consiste à demander au service commun de recherche de comptes quel FSP détient la partie avec l’identité fournie. Le service commun est représenté comme « Account Lookup » dans les flux ; ce service peut être mis en œuvre par le Switch ou comme un service séparé, selon le marché.

Les FSP n’ont pas besoin de prendre en charge la partie serveur des différents services HTTP GET sous la ressource /participants ; cette partie doit être assurée par l’ALS. À la place, les FSP (clients) doivent fournir des informations FSP concernant leurs comptes et titulaires de comptes (parties) à l’ALS (serveur) en utilisant les méthodes HTTP POST (pour créer ou mettre à jour les informations FSP, voir POST /participants et POST /participants/{Type}/{ID}) et HTTP DELETE (pour supprimer les informations FSP existantes, voir DELETE /participants/{Type}/{ID}).

# Figure 42

Figure 42 — Comment utiliser les services fournis par /participants s’il existe un système commun de recherche de comptes

# Requêtes

Cette section décrit les services qu’un client peut demander sur la ressource /participants.

# GET /participants/{Type}/{ID}

URI alternative : GET /participants/{Type}/{ID}/{SubId}

Service logique API : Recherche d’informations sur un participant

La requête HTTP GET /participants/{Type}/{ID} (ou GET /participants/{Type}/{ID}/{SubId}) sert à déterminer dans quel FSP se trouve la partie demandée, définie par {Type}, {ID} et éventuellement {SubId} (par exemple, GET /participants/MSISDN/123456789, ou GET /participants/BUSINESS/shoecompany/employee1). Voir Remboursement pour plus d’informations sur l’adressage d’une partie.

Cette requête HTTP doit prendre en charge une chaîne de requête (voir Syntaxe URI pour plus d’informations sur la syntaxe URI) pour filtrer par devise. Pour utiliser le filtrage par devise, la requête HTTP GET /participants/{Type}/{ID}?currency=XYZ doit être utilisée, où XYZ est la devise demandée.

Informations de callback et de modèle de données pour GET /participants/{Type}/{ID} (alternative GET /participants/{Type}/{ID}/{SubId}):

• Callback – PUT /participants/{Type}/{ID}
• Callback d’erreur – PUT /participants/{Type}/{ID}/error
• Modèle de données — Corps vide

# POST /participants

URI alternative : N/A

Service logique API : Création d’informations bulk sur un participant

La requête HTTP POST /participants est utilisée pour créer des informations sur le serveur concernant la liste d’identités fournie. Cette requête doit être utilisée pour la création groupée d’informations FSP pour plusieurs parties. Le paramètre de devise optionnel doit indiquer que chaque partie fournie prend en charge la devise.

Callback et modèle de données pour POST /participants :

• Callback – PUT /participants/{ID}
• Callback d’erreur – PUT /participants/{ID} /error
• Modèle de données – Voir Tableau 9

# Tableau 9

Tableau 9 — Modèle de données POST /participants

# POST /participants/{Type}/{ID}

URI alternative : POST /participants/{Type}/{ID}/{SubId}

Service logique API : Création d’informations sur un participant

La requête HTTP POST /participants/{Type}/{ID} (ou POST /participants/{Type}/{ID}/{SubId}) est utilisée pour créer sur le serveur les informations concernant l’identité fournie, définie par {Type}, {ID} et éventuellement {SubId} (par exemple, POST /participants/MSISDN/123456789 ou POST /participants/BUSINESS/shoecompany/employee1). Voir Remboursement pour plus d’informations sur l’adressage d’une partie.

Callback et modèle de données pour POST /participants/{Type}/{ID} (alternative POST /participants/{Type}/{ID}/{SubId}):

• Callback – PUT /participants/{Type}/{ID}
• Callback d’erreur — PUT /participants/{Type}/{ID}/error
• Modèle de données – Voir Tableau 10

# Tableau 10

Tableau 10 — Modèle de données POST /participants/{Type}/{ID} (ou POST /participants/{Type}/{ID}/{SubId})

# DELETE /participants/{Type}/{ID}

URI alternative : DELETE /participants/{Type}/{ID}/{SubId}

Service logique API : Suppression d’informations sur un participant

La requête HTTP DELETE /participants/{Type}/{ID} (ou DELETE /participants/{Type}/{ID}/{SubId}) est utilisée pour supprimer les informations sur le serveur concernant l’identité fournie, définie par {Type} et {ID} (par exemple, DELETE /participants/MSISDN/123456789) et éventuellement {SubId}. Voir Remboursement pour plus d’informations sur l’adressage d’une partie.

Cette requête HTTP doit prendre en charge une chaîne de requête (voir Syntaxe URI) pour supprimer les informations FSP concernant uniquement une devise spécifique. Pour supprimer uniquement une devise spécifique, la requête HTTP DELETE /participants/{Type}/{ID}?currency=XYZ doit être utilisée, où XYZ est la devise demandée.

Note : L’ALS doit vérifier que c’est bien le FSP actuel de la partie qui supprime l’information FSP.

Callback et modèle de données pour DELETE /participants/{Type}/{ID} (alternative GET /participants/{Type}/{ID}/{SubId}):

• Callback – PUT /participants/{Type}/{ID}
• Callback d’erreur – PUT /participants/{Type}/{ID}/error
• Modèle de données — Corps vide

# Callbacks

Cette section décrit les callbacks utilisés par le serveur pour les services fournis par la ressource /participants.

# PUT /participants/{Type}/{ID}

URI alternative : PUT /participants/{Type}/{ID}/{SubId}

Service logique API : Retour d’information sur un participant

Le callback PUT /participants/{Type}/{ID} (ou PUT /participants/{Type}/{ID}/{SubId}) est utilisé pour informer le client d’un succès à la suite d’une recherche, création ou suppression des informations FSP liées à la partie. Si l’information FSP a été supprimée, l’élément fspId doit être vide ; sinon il doit contenir l’information FSP de la partie.

Voir Tableau 11 pour le modèle de données.

# Tableau 11

Tableau 11 — Modèle de données PUT /participants/{Type}/{ID} (ou PUT /participants/{Type}/{ID}/{SubId})

# PUT /participants/{ID}

URI alternative : N/A

Service logique API : Retour d’informations groupées sur les participants

Le callback PUT /participants/{ID} est utilisé pour informer le client du résultat de la création de la liste d’identités fournie.

Voir Tableau 12 pour le modèle de données.

# Tableau 12

Tableau 12 — Modèle de données PUT /participants/{ID}

####Callbacks d’erreur

Cette section décrit les callbacks d’erreur utilisés par le serveur pour la ressource /participants.

# PUT /participants/{Type}/{ID}/error

URI alternative : PUT /participants/{Type}/{ID}/{SubId}/error

Service logique API : Erreur de retour d’information sur un participant

Si le serveur ne parvient pas à trouver, créer ou supprimer l’association FSP pour l’identité fournie, ou si une autre erreur de traitement est survenue, le callback d’erreur PUT /participants/{Type}/{ID}/error (ou PUT /participants/{Type}/{ID}/{SubId}/error) est utilisé. Voir Tableau 13 pour le modèle de données.

# Tableau 13

Tableau 13 — Modèle de données PUT /participants/{Type}/{ID}/error (ou PUT /participants/{Type}/{ID}/{SubId}/error)

# PUT /participants/{ID}/error

URI alternative : N/A

Service logique API : Erreur de retour d’informations sur des participants groupés

En cas d’erreur lors de la création des informations FSP sur le serveur, le callback d’erreur PUT /participants/{ID}/error est utilisé. L’{ID} de l’URI doit contenir le requestId (voir Tableau 9) qui a servi à la création de l’information du participant. Voir Tableau 14 pour le modèle de données.

# Tableau 14

Tableau 14 — Modèle de données PUT /participants/{ID}/error

# États

Aucun état n’est défini pour la ressource /participants ; soit le serveur détient des informations FSP pour l’identité demandée, soit il n’en détient pas.

# Ressource API /parties

Cette section définit la ressource API logique Parties, décrite dans les Modèles génériques de transaction.

Les services fournis par la ressource /parties servent à obtenir des informations concernant une partie détenue par un FSP pair.

# Historique des versions de la ressource

Tableau 15 présente une description de chaque version de la ressource /parties.

# Tableau 15

Tableau 15 — Historique des versions de la ressource /parties

# Détails des services

Figure 43 contient un exemple de processus pour la ressource /parties. D’autres déploiements sont possibles, par exemple un où le Switch et l’ALS sont sur le même serveur, ou un où le FSP de l’utilisateur interroge directement le FSP 1 pour obtenir les informations sur la partie.

# Figure 43

Figure 43 — Exemple de processus pour la ressource /parties

# Requêtes

Cette section décrit les services qui peuvent être demandés par un client sur la ressource /parties de l’API.

# GET /parties/{Type}/{ID}

URI alternative : GET /parties/{Type}/{ID}/{SubId}

Service logique API : Recherche d’informations sur une partie

La requête HTTP GET /parties/{Type}/{ID} (ou GET /parties/{Type}/{ID}/{SubId}) est utilisée pour rechercher des informations sur la partie demandée, définie par {Type}, {ID} et éventuellement {SubId} (par exemple, GET /parties/MSISDN/123456789 ou GET /parties/BUSINESS/shoecompany/employee1). Voir Remboursement pour plus d’informations sur l’adressage d’une partie.

Callback et modèle de données pour GET /parties/{Type}/{ID} (alternative GET /parties/{Type}/{ID}/{SubId}):

• Callback – PUT /parties/{Type}/{ID}
• Callback d’erreur – PUT /parties/{Type}/{ID}/error
• Modèle de données — Corps vide

# Callbacks

Cette section décrit les callbacks utilisés par le serveur pour les services fournis par la ressource /parties.

# PUT /parties/{Type}/{ID}

URI alternative : PUT /parties/{Type}/{ID}/{SubId}

Service logique API : Retour d’informations sur une partie

Le callback PUT /parties/{Type}/{ID} (ou PUT /parties/{Type}/{ID}/{SubId}) est utilisé pour informer le client d’un succès à la suite de la recherche d’une partie. Voir Tableau 16 pour le modèle de données.

# Tableau 16

Tableau 16 — Modèle de données PUT /parties/{Type}/{ID} (ou PUT /parties/{Type}/{ID}/{SubId})

# Callbacks d’erreur

Cette section décrit les callbacks d’erreur utilisés par le serveur pour la ressource /parties.

# PUT /parties/{Type}/{ID}/error

URI alternative : PUT /parties/{Type}/{ID}/{SubId}/error

Service logique API : Erreur de retour d’informations sur une partie

Si le serveur ne peut pas trouver les informations de la partie pour l’identité fournie, ou si une autre erreur de traitement est survenue, le callback d’erreur PUT /parties/{Type}/{ID}/error (ou PUT /parties/{Type}/{ID}/{SubId}/error) est utilisé. Voir Tableau 17 pour le modèle de données.

# Tableau 17

Tableau 17 — Modèle de données PUT /parties/{Type}/{ID}/error (ou PUT /parties/{Type}/{ID}/{SubId}/error)

# États

Aucun état n’est défini pour la ressource /parties ; soit un FSP dispose d’informations sur l’identité demandée, soit il n’en a pas.

# Ressource API /transactionRequests

Cette section définit la ressource API logique Transaction Requests (« demandes de transaction »), décrite dans les Modèles génériques de transaction.

Le service principal qu’offre la ressource /transactionRequests permet à un bénéficiaire de demander à un payeur de lui transférer des fonds électroniques. Le payeur peut approuver ou refuser la demande émise par le bénéficiaire. La décision du payeur peut être prise de manière programmatique si :

• Le bénéficiaire est de confiance (c’est-à-dire que le payeur l’a pré-approuvé dans son FSP), ou
• Une valeur d’autorisation — c’est-à-dire un mot de passe à usage unique (OTP) — a été vérifiée correctement à l’aide de la ressource API /authorizations (voir Section 6.6).

Alternativement, le payeur peut prendre la décision manuellement.

# Historique des versions de la ressource

Tableau 18 présente une description de chaque version de la ressource /transactionRequests.

# Tableau 18

Tableau 18 — Historique des versions de la ressource /transactionRequests

# Détails des services

Figure 44 montre comment fonctionne le processus de demande de transaction à l’aide de la ressource /transactionRequests. L’approbation ou le refus n’est pas montré dans la figure. Un refus est un callback PUT /transactionRequests/{ID} avec un état REJECTED, similaire au callback de la figure avec l’état RECEIVED, tel que décrit dans la Section 6.4.2.1. Une approbation du payeur n’est pas envoyée en tant que callback ; à la place, une devis et un transfert sont envoyés contenant une référence à la demande de transaction.

# Figure 44

Figure 44 — Comment utiliser le service /transactionRequests

# Demande de transaction rejetée par le payeur

Figure 45 montre le processus par lequel une demande de transaction est rejetée. Les raisons possibles du refus incluent :

• Le payeur a rejeté la demande manuellement.
• Un dépassement de limite automatique s’est produit.
• Le payeur a saisi un OTP de façon erronée plus que le nombre de fois autorisé.

# Figure 45

Figure 45 — Exemple de processus dans lequel une demande de transaction est rejetée

# Requêtes

Cette section décrit les services qu’un client peut demander pour la ressource /transactionRequests.

# GET /transactionRequests/{ID}

URI alternative : N/A

Service logique API : Récupérer les informations de demande de transaction

La requête HTTP GET /transactionRequests/{ID} est utilisée pour obtenir des informations sur une demande de transaction préalablement créée ou sollicitée. L’{ID} dans l’URI doit contenir le transactionRequestId (voir Tableau 15) qui a été utilisé lors de la création de la demande de transaction.

Callback et modèle de données pour GET /transactionRequests/{ID} :

• Callback — PUT /transactionRequests/{ID}
• Callback d’erreur — PUT /transactionRequests/{ID}/error
• Modèle de données — Corps vide

# POST /transactionRequests

URI alternative : N/A

Service logique API : Effectuer une demande de transaction

La requête HTTP POST /transactionRequests est utilisée pour demander la création d’une demande de transaction financière sur le serveur.

Callback et modèle de données pour POST /transactionRequests :

• Callback — PUT /transactionRequests/{ID}
• Callback d’erreur — PUT /transactionRequests/{ID}/error
• Modèle de données — Voir Tableau 19

# Tableau 19

Tableau 19 — Modèle de données POST /transactionRequests

# Callbacks

Cette section décrit les callbacks utilisés par le serveur pour la ressource /transactionRequests.

# PUT /transactionRequests/{ID}

URI alternative : N/A

Service logique API : Retour d’informations de demande de transaction

Le callback PUT /transactionRequests/{ID} est utilisé pour informer le client d’une demande de transaction créée ou sollicitée. L’{ID} dans l’URI doit contenir le transactionRequestId (voir Tableau 19) utilisé lors de la création de la demande, ou l’{ID} utilisé dans le GET /transactionRequests/{ID}. Voir Tableau 20 pour le modèle de données.

# Tableau 20

Tableau 20 — Modèle de données PUT /transactionRequests/{ID}

# Callbacks d’erreur

Cette section décrit les callbacks d’erreur utilisés par le serveur pour la ressource /transactionRequests.

# PUT /transactionRequests/{ID}/error

URI alternative : N/A

Service logique API : Erreur de retour d’informations sur une demande de transaction

Si le serveur ne parvient pas à trouver ou créer une demande de transaction, ou si une autre erreur de traitement survient, le callback d’erreur PUT /transactionRequests/{ID}/error est utilisé. L’{ID} de l’URI doit contenir le transactionRequestId (voir Tableau 19) utilisé lors de la création de la demande, ou l’{ID} utilisé dans le GET /transactionRequests/{ID}. Voir Tableau 21 pour le modèle de données.

# Tableau 21

Tableau 21 — Modèle de données PUT /transactionRequests/{ID}/error

# 6.4.6 États

Les états possibles d’une demande de transaction sont représentés dans la Figure 46.

Note : Un serveur n’a pas besoin de conserver les objets de demande de transaction qui ont été rejetés dans sa base de données. Cela signifie qu’un client doit s’attendre à recevoir un callback d’erreur pour une demande de transaction rejetée.

# Figure 46

Figure 46 — États possibles d’une demande de transaction

# Ressource API /quotes

Cette section définit la ressource API logique Quotes (« Devis »), décrite dans les Modèles génériques de transaction.

Le principal service proposé par la ressource /quotes est le calcul des frais éventuels et des commissions FSP liés à la réalisation d’une transaction financière interopérable. Les FSP payeur et bénéficiaire doivent chacun calculer leur part du devis pour obtenir une vue globale de tous les frais et commissions applicables à la transaction.

Une devis est irrévocable ; elle ne peut pas être modifiée après sa création. Elle peut cependant expirer (toutes les devis sont valables uniquement jusqu’à leur date d’expiration).

Note : Une devis n’est pas une garantie que la transaction financière réussira. La transaction peut toujours échouer ultérieurement. Une devis garantit uniquement que les frais et commissions appliqués à la transaction spécifiée restent valables jusqu’à expiration du devis.

Pour plus d’informations, voir la section Devis.

# Historique des versions de la ressource

Tableau 22 présente une description de chaque version de la ressource /quotes.

# Tableau 22

Tableau 22 – Historique des versions de la ressource /quotes

# Détails des services

Figure 47 présente un exemple de processus pour la ressource API /quotes. Cet exemple montre une transaction initiée par le payeur, mais elle peut aussi être initiée par le bénéficiaire, en utilisant la ressource API /transactionRequests. Dans ce cas, la recherche sera effectuée par le FSP du bénéficiaire.

# Figure 47

Figure 47 — Exemple de processus pour la ressource /quotes

# Détails de l’expiration du devis

La demande de devis du FSP payeur peut contenir une date d’expiration, si le FSP payeur souhaite indiquer à partir de quand il n’est plus utile pour le FSP bénéficiaire de renvoyer une devis. Par exemple, la transaction peut expirer ou sa devis peut expirer.

Le FSP bénéficiaire doit définir une expiration dans le callback du devis pour indiquer à partir de quand elle n’est plus valable pour le FSP payeur.

# Rejet d’une devis

Le FSP bénéficiaire peut rejeter une demande de devis émise par le FSP payeur en envoyant le callback d’erreur PUT /quotes/{ID}/error plutôt que le callback PUT /quotes/{ID}. Selon le modèle générique de transaction utilisé (voir Section 8 pour plus d’informations), le FSP payeur peut rejeter une devis en utilisant l’une des méthodes suivantes :

• Si la transaction est initiée par le payeur (voir Section 8.1), le FSP payeur ne doit pas informer le FSP bénéficiaire du rejet. La devis créée chez le FSP bénéficiaire doit avoir une date d’expiration, après laquelle elle est automatiquement supprimée.
• Si la transaction est initiée par le bénéficiaire (voir Section 8.2 et 8.3), le FSP payeur doit informer le FSP bénéficiaire du rejet par le callback PUT /transactionRequests/{ID} avec un état « rejected ». Le processus est décrit plus en détail à la Section 6.4.2.1.

# Demande de paiement Interledger

Dans le cadre de la prise en charge d’Interledger et de l’implémentation concrète de la demande de paiement Interledger (voir Protocole Interledger), le FSP bénéficiaire doit :

• Déterminer l’adresse ILP (voir Adresses ILP pour plus d’informations) du bénéficiaire et le montant qu’il recevra. Notez que puisque l’élément amount dans le paquet ILP est défini comme un UInt64 (donc valeur entière), le montant doit être multiplié par l’exposant du devise (par exemple, l’exposant de l’USD est 2, donc le montant doit être multiplié par 10², et celui du JPY est 0, donc multiplié par 10⁰). L’adresse ILP et le montant doivent être renseignés dans le paquet ILP (voir ILP Packet pour plus d’informations).

• Renseigner l’élément data dans le paquet ILP par le modèle de données Transaction.

• Générer la fulfilment et la condition (voir Transferts conditionnels pour plus de détails). Renseigner l’élément condition dans le PUT /quotes/**{ID}). Le Tableau 19 montre le modèle de données avec la condition générée.

La fulfilment est un secret temporaire généré pour chaque transaction financière par le FSP bénéficiaire et utilisé comme déclencheur pour valider les transferts constituant un paiement ILP.

Le FSP bénéficiaire utilise un secret local pour générer un HMAC SHA-256 du paquet ILP. Le même secret peut être utilisé pour toutes les transactions financières, ou le FSP bénéficiaire peut stocker un secret différent par bénéficiaire ou selon une autre segmentation.

Le choix et la cardinalité du secret local sont une décision d’implémentation, qui peut être dictée par les règles du système. Le seul prérequis est que le FSP bénéficiaire puisse déterminer à quel secret correspond un paquet ILP reçu ultérieurement dans le cadre d’un transfert entrant (voir Ressource API Transfers).

La fulfilment et la condition sont générées conformément à l’algorithme défini dans le Listing 12. Une fois que le FSP bénéficiaire a dérivé la condition, la fulfilment peut être supprimée puisqu’elle peut être régénérée plus tard.

# Listing 12

Génération du fulfilment (accomplissement) et de la condition

Entrées :

• Secret local (chaîne binaire de 32 octets)
• Paquet ILP

Algorithme :

1. Le fulfilment est obtenu en exécutant l’algorithme HMAC SHA-256 sur le paquet ILP en utilisant le secret local comme clé.

2. La condition est obtenue en exécutant l’algorithme de hachage SHA-256 sur le fulfilment.

Sorties :

• Fulfilment (chaîne binaire de 32 octets)
• Condition (chaîne binaire de 32 octets)

Listing 12 -- Algorithme pour générer le fulfilment et la condition

# Requêtes

Cette section décrit les services pouvant être demandés par un client de l’API sur la ressource /quotes.

# GET /quotes/{ID}

URI alternative : N/A

Service logique de l’API : Récupérer les informations du devis

La requête HTTP GET /quotes/{ID} permet d’obtenir des informations sur une devis préalablement créée ou demandée. Le {ID} dans l’URI doit contenir le quoteId (voir Tableau 23) qui a été utilisé pour la création du devis.

Informations sur les callbacks et le modèle de données pour GET /quotes/{ID} :

• Callback -- PUT /quotes/{ID}
• Callback d’erreur -- PUT /quotes/{ID}/error
• Modèle de données -- Corps vide

# POST /quotes

URI alternative : N/A

Service logique de l’API : Calculer les informations du devis

La requête HTTP POST /quotes est utilisée pour demander la création d’une devis pour la transaction financière fournie sur le serveur.

Informations sur les callbacks et le modèle de données pour POST /quotes :

• Callback -- PUT /quotes/{ID}
• Callback d’erreur -- PUT /quotes/{ID}/error
• Modèle de données -- Voir Tableau 23

# Tableau 23

Tableau 23 -- Modèle de données POST /quotes

# Callbacks

Cette section décrit les callbacks utilisés par le serveur sous la ressource /quotes.

# PUT /quotes/{ID}

URI alternative : N/A

Service logique de l’API : Retourner les informations du devis

Le callback PUT /quotes/{ID} est utilisé pour informer le client d’une devis demandée ou créée. Le {ID} dans l’URI doit contenir le quoteId (voir Tableau 23) qui a été utilisé pour la création du devis, ou le {ID} utilisé dans le GET /quotes/{ID}. Voir Tableau 24 pour le modèle de données.

# Tableau 24

Tableau 24 -- Modèle de données PUT /quotes/{ID}

# Callbacks d’erreur

Cette section décrit les callbacks d’erreur utilisés par le serveur sous la ressource /quotes.

# PUT /quotes/{ID}/error

URI alternative : N/A

Service logique de l’API : Retourner une erreur d’information de devis

Si le serveur ne parvient pas à trouver ou créer une devis, ou qu’une autre erreur de traitement se produit, le callback d’erreur PUT /quotes/{ID}/error est utilisé. Le {ID} dans l’URI doit contenir le quoteId (voir Tableau 23) utilisé pour la création du devis, ou le {ID} utilisé dans le GET /quotes/{ID}. Voir Tableau 25 pour le modèle de données.

# Tableau 25

Tableau 25 -- Modèle de données PUT /quotes/{ID}/error

# États

# Figure 48

Figure 48 contient la machine à états UML (Unified Modeling Language) pour les états possibles d’un objet devis.

Remarque : Un serveur n’a pas besoin de conserver en base les objets devis ayant été rejetés ou expirés. Cela signifie qu’un client doit s’attendre à ce qu’un callback d’erreur puisse être retourné pour une devis expirée ou rejetée.

Figure 48 -- États possibles d’une devis

# Ressource d’API /authorizations

Cette section définit la ressource logique d’API Authorizations, décrite dans Modèles de transaction génériques.

La ressource /authorizations est utilisée pour demander au payeur de saisir les identifiants applicables dans le système du FSP bénéficiaire pour approuver la transaction financière, lorsqu’il a initié la transaction depuis un POS, un DAB ou similaire, dans le système du FSP bénéficiaire et souhaite autoriser via un OTP.

# Historique des versions de la ressource

Tableau 26 décrit les différentes versions de la ressource /authorizations.

# Tableau 26

Tableau 26 – Historique des versions de la ressource /authorizations

# Détails des services

Figure 49 présente un exemple de processus pour la ressource API /authorizations. Le FSP bénéficiaire envoie d’abord une demande de transaction) qui est autorisée via OTP. Le FSP payeur réalise ensuite le devis (voir Ressource API Quotes) avant qu’une demande d’autorisation soit envoyée au système du FSP bénéficiaire pour que le payeur approuve via la saisie de l’OTP. Si l’OTP est correct, le processus de transfert doit être initié (voir Ressource API Transfers).

# Figure 49

Figure 49 -- Exemple de processus pour la ressource /authorizations

# Renvoi de la valeur d’autorisation

Si la notification contenant la valeur d’autorisation n’atteint pas le payeur, celui-ci peut demander le renvoi de la valeur d’autorisation si le POS, le DAB ou appareil similaire propose cette option. Voir Figure 50 pour un exemple où le payeur demande un renvoi de l’OTP.

# Figure 50

Figure 50 -- Le payeur demande le renvoi de la valeur d’autorisation (OTP)

# Tentative de saisie de la valeur d’autorisation

Le FSP payeur doit décider du nombre de tentatives autorisées pour la saisie de la valeur d’autorisation sur le POS, DAB ou appareil similaire. Ce nombre est fixé dans la chaîne de requête retriesLeft (voir Syntaxe URI pour plus de détails) dans le service GET /authorizations/{ID}. Si le FSP payeur envoie retriesLeft=1, cela signifie qu’il s’agit de la dernière tentative autorisée par le payeur. Voir Figure 51 pour un exemple où le payeur saisit un OTP incorrect et où la valeur retriesLeft est alors décrémentée.

# Figure 51

Figure 51 -- Le payeur saisit une valeur d’autorisation incorrecte (OTP)

# Échec de l’autorisation OTP

Si l’utilisateur échoue à saisir le bon OTP dans le nombre de tentatives autorisées, le processus décrit dans Demande de transaction rejetée par le payeur est suivi.

# Requêtes

Cette section décrit les services pouvant être demandés par un client de l’API sur la ressource /authorizations.

# GET /authorizations/{ID}

URI alternative : N/A

Service logique d’API : Réaliser l’autorisation

La requête HTTP GET /authorizations/{ID} est utilisée pour demander au payeur de saisir les identifiants dans le système du FSP bénéficiaire. Le {ID} dans l’URI doit contenir le transactionRequestID (voir Tableau 15), obtenu via le service POST /transactionRequests) plus tôt dans le processus.

Cette requête nécessite que la chaîne de requête (voir Syntaxe URI pour plus d’infos) contienne les paires clé-valeur suivantes :

• authenticationType={Type}, où {Type} est une valeur valide de l’énumération AuthenticationType.
• retriesLeft={NrOfRetries}, où {NrOfRetries} est le nombre de tentatives restantes avant le rejet de la transaction financière. {NrOfRetries} doit être exprimé via le type de données Integer). retriesLeft=1 signifie qu’il s’agit de la dernière tentative.
• amount={Amount}, où {Amount} est le montant de la transaction qui sera prélevé du compte du payeur. {Amount} doit être de type Amount.
• currency={Currency}, où {Currency} est la devise de la transaction. La valeur {Currency} doit être conforme à l’énumération CurrencyCode).

Exemple d’URI contenant toutes les clés requises :

GET /authorization/3d492671-b7af-4f3f-88de-76169b1bdf88?authenticationType=OTP&retriesLeft=2&amount=102&currency=USD

Informations sur les callbacks et le modèle de données pour GET /authorization/{ID} :

• Callback - PUT /authorizations/{ID}
• Callback d’erreur - PUT /authorizations/{ID}/error
• Modèle de données -- Corps vide

# 6.6.4 Callbacks

Cette section décrit les callbacks utilisés par le serveur sous la ressource /authorizations.

# 6.6.4.1 PUT /authorizations/{ID}

URI alternative : N/A

Service logique d’API : Retourner le résultat de l’autorisation

Le callback PUT /authorizations/ {ID} est utilisé pour informer le client du résultat d’une autorisation précédemment demandée. Le {ID} dans l’URI doit contenir l’identifiant utilisé dans le GET /authorizations/{ID}. Voir Tableau 27 pour le modèle de données.

# Tableau 27

Tableau 27 – Modèle de données PUT /authorizations/{ID}

# Callbacks d’erreur

Cette section décrit les callbacks d’erreur utilisés par le serveur sous la ressource /authorizations.

# PUT /authorizations/{ID}/error

URI alternative : N/A

Service logique d’API : Retourner une erreur d’autorisation

Si le serveur ne trouve pas la demande de transaction, ou une autre erreur de traitement survient, le callback d’erreur PUT /authorizations/{ID} /error est utilisé. Le {ID} dans l’URI doit être celui utilisé dans le GET /authorizations/{ID}. Voir Tableau 28 pour le modèle de données.

# Tableau 28

Tableau 28 -- Modèle de données PUT /authorizations/{ID}/error

# États

Aucun état n’est défini pour la ressource /authorizations.

# Ressource d’API /transfers

Cette section définit la ressource logique d’API Transfers, décrite dans Modèles de transaction génériques.

Les services fournis par la ressource d’API /transfers servent à effectuer le(s) transfert(s) ILP hop-by-hop et à réaliser la transaction financière de bout en bout en envoyant les détails de transaction du FSP payeur au FSP bénéficiaire. Les détails de la transaction sont envoyés en tant que partie du modèle de données de transfert dans le paquet ILP.

Le protocole Interledger suppose que la mise en place d’une transaction financière se fait via un protocole de bout en bout, mais qu’un transfert ILP est réalisé via des protocoles hop-by-hop entre FSPs connectés au même registre. Dans la version actuelle de l’API, la ressource /quotes établit la transaction financière. Avant de réaliser un transfert, le devis doit être effectuée pour préparer la transaction. Voir Ressource API Quotes pour plus d’informations.

Un transfert ILP s’effectue entre deux détenteurs de comptes sur chaque côté d’un registre commun. Il s’exprime généralement par une demande d’exécution d’un transfert sur le registre et une notification au bénéficiaire que le transfert est réservé en sa faveur, incluant une condition devant être remplie pour commettre le transfert.

Quand le FSP bénéficiaire présente le fulfilment au registre commun, le transfert est commis sur le registre. Simultanément, le FSP payeur est notifié que le transfert a été commis ainsi que du fulfilment.

# Historique des versions de la ressource

Le Tableau 29 décrit les différentes versions de la ressource /transfers.

Tableau 29 –- Historique des versions pour la ressource /transfers

# Détails des services

Cette section fournit des détails concernant les transferts hop-by-hop et les transactions financières de bout en bout.

# Processus

Figure 52 illustre le fonctionnement du processus transactionnel utilisant le service POST /transfers.

# Figure 52

Figure 52 -- Utilisation du service POST /transfers

# Irrévocabilité des transactions

L’API est conçue pour ne supporter que les transactions financières irrévocables ; c’est-à-dire qu’une transaction ne peut pas être modifiée, annulée ou inversée après sa création. Cela vise à simplifier et réduire les coûts pour les FSPs utilisant l’API. Une grande partie du coût opérationnel des systèmes financiers est due à l’inversion des transactions.

Dès qu’un FSP payeur envoie une transaction au FSP bénéficiaire (via POST /transfers incluant la transaction de bout en bout), la transaction est irrévocable côté FSP payeur. Elle peut toutefois encore être rejetée côté FSP bénéficiaire, mais le payeur ne peut plus modifier ou rejeter la transaction. Une exception à cela serait si le délai d’expiration du transfert est dépassé avant que le FSP bénéficiaire ne réponde (voir Quote expirée et Client recevant un transfert expiré pour plus d’informations). Dès que la transaction a été acceptée par le FSP bénéficiaire, elle est irrévocable pour toutes les parties.

# Devis expirée

Si un serveur reçoit une transaction utilisant une devis expirée, il doit refuser le transfert ou la transaction.

# Timeout et expiration

Le FSP payeur doit toujours définir un temps d’expiration pour le transfert afin de permettre les cas d’utilisation nécessitant un traitement ou un échec rapide. Si le cas d’utilisation ne nécessite pas de réponse rapide, un délai d’expiration plus long peut être fixé. Si le FSP bénéficiaire ne répond pas avant le temps d’expiration, la transaction est annulée côté FSP payeur. Ce dernier doit cependant s’attendre à un callback du bénéficiaire.

Les délais d’expiration courts sont souvent requis dans le commerce de détail, où un client se trouve devant un commerçant ; les deux parties doivent savoir si la transaction a réussi avant la remise d’un produit ou service.

Dans Figure 52, un délai d’expiration de 30 secondes à partir de l’heure courante a été défini dans la requête du FSP payeur, et de 20 secondes dans la requête du Switch au FSP bénéficiaire. Cette stratégie de réduction du délai à chaque maillon de la chaîne du FSP payeur au bénéficiaire doit toujours être utilisée pour permettre un délai de communication supplémentaire.

Remarque : Il est possible qu’un callback de succès soit reçu par le FSP payeur après l’expiration, par exemple lors d’une congestion réseau. Le FSP payeur devrait laisser un délai supplémentaire après l’expiration avant d’annuler la transaction dans le système. Si un callback de succès arrive après annulation, la transaction doit être marquée pour rapprochement et traitée à part.

# Client recevant un transfert expiré

Figure 53 illustre un scénario d’erreur lié à l’expiration et au timeout. Pour une raison quelconque, le callback du FSP bénéficiaire prend plus de temps à arriver que le délai d’expiration dans le Switch. Cela conduit le Switch à annuler le transfert réservé et à envoyer un callback d’erreur au FSP payeur. Ainsi, FSP payeur et bénéficiaire ont deux visions différentes du résultat de la transaction ; celle-ci doit être marquée pour rapprochement.

# Figure 53

Figure 53 -- Client recevant un transfert expiré

Pour limiter ce type d’erreur, les clients (FSP payeur et Switch optionnel dans la Figure 52) participant au transfert ILP doivent permettre un délai supplémentaire post expiration permettant de recevoir le callback du serveur. Le(s) client(s) doivent aussi interroger le serveur après expiration et avant la fin du délai supplémentaire en cas de perte du callback. Un rapprochement pourrait néanmoins rester nécessaire, même avec ce délai et une interrogation du serveur.

# Notification de commit

Comme alternative pour éviter le scénario d’erreur décrit dans Client recevant un transfert expiré, pour les cas où il est compliqué d’effectuer un remboursement, un FSP bénéficiaire peut (si le schéma le permet) réserver le transfert puis attendre la notification de commit émise par le Switch. Demander une notification de commit plutôt qu’un commit direct relève de la décision métier du FSP bénéficiaire (si le schéma l’autorise), selon le contexte de la transaction. Par exemple, un retrait cash ou un paiement commerçant est plus risqué qu’un transfert P2P du fait de la difficulté de remboursement a posteriori. Pour demander la notification de commit depuis le Switch, le FSP bénéficiaire doit marquer l’état du transfert (voir Section 6.7.6) comme réservé (reserved) au lieu de commis (committed) dans le callback PUT /transfers/{ID} . Selon l’état, le Switch doit alors effectuer :

• Si le transfert est commis, le Switch n’envoie pas de notification de commit puisque le FSP bénéficiaire a déjà accepté le risque. C’est la méthode de commit par défaut décrite dans Processus.
• Si le transfert est réservé, le Switch doit envoyer une notification de commit au FSP bénéficiaire à la fin du traitement (commit ou annulation).

La notification de commit est envoyée avec la requête PATCH /transfers/{ID} du Switch au FSP bénéficiaire. Si ce dernier ne reçoit pas la notification dans un délai raisonnable, il doit renvoyer le callback PUT /transfers/{ID} au Switch. Le FSP bénéficiaire doit recevoir la notification de commit du Switch avant de commettre le transfert, ou accepter le risque que le transfert ait échoué côté Switch. Il n’a pas le droit de rollbacker sans avoir reçu un état "aborted" (voir Section 6.7.6) du Switch, car il a déjà envoyé le fulfilment (déclencheur du commit). Figure 54 illustre un cas où une notification de commit est demandée. Ici, le commit a réussi côté Switch.

# Figure 54

Figure 54 -- Notification de commit après succès du transfert dans le Switch

Figure 55 montre un exemple où le commit dans le Switch a échoué (par exemple expiration du délai dans le Switch à cause d’un incident réseau). C’est le même scénario que Figure 53, mais sans rapprochement à réaliser car le FSP bénéficiaire reçoit la notification de commit avant de réaliser effectivement le transfert.

# Figure 55

Figure 55 -- Notification de commit après échec du commit dans le Switch

# Remboursements

Au lieu de supporter les inversions, l’API supporte les remboursements. Pour rembourser une transaction via l’API, une nouvelle transaction doit être créée par le bénéficiaire initial. Celle-ci doit annuler la transaction originale (en totalité ou partiellement) ; par exemple, si le client X a envoyé 100 USD au commerçant Y, celui-ci crée une nouvelle transaction pour reverser 100 USD à X. Il existe un type de transaction spécifique pour indiquer un remboursement ; cela permet de gérer différemment le devis. L’ID de la transaction d’origine doit être inclus dans la nouvelle transaction à des fins d’information et de rapprochement.

# Demande de paiement Interledger

Dans le cadre du support d’Interledger et de la demande de paiement Interledger (voir Protocole Interledger), le FSP payeur doit joindre au transfert le paquet ILP, la condition ainsi qu’une date d’expiration. La condition et le paquet ILP sont les mêmes que ceux envoyés par le FSP bénéficiaire dans le callback du devis ; voir Demande de paiement Interledger pour plus d’informations.

Le paiement ILP de bout en bout est une chaîne d’un ou plusieurs transferts conditionnels tous dépendants de la même condition. La condition est fournie par le FSP payeur lors de l’initiation du transfert vers le prochain ledger.

Le récepteur du transfert extrait l’adresse ILP du bénéficiaire dans le paquet ILP et effectue un autre transfert sur le ledger suivant, en joignant le même paquet ILP et condition et en fixant une expiration plus courte que celle du transfert entrant.

Quand le FSP bénéficiaire reçoit le dernier transfert entrant pour le compte du bénéficiaire, il extrait le paquet ILP et procède ainsi :

1. Valide que l’adresse ILP du bénéficiaire dans le paquet ILP correspond au compte bénéficiaire de destination.
2. Valide que le montant dans le paquet ILP correspond au montant du transfert et déclenche la réservation sur le registre local (moins les éventuels frais cachés au bénéficiaire, voir Devis).
3. Si la réservation est un succès, le FSP bénéficiaire génère le fulfilment à l’aide du même algorithme que celui utilisé pour générer la condition envoyée dans le callback du devis (voir Demande de paiement Interledger).
4. Le fulfilment est soumis au registre du FSP bénéficiaire pour engager la réservation en faveur du bénéficiaire. Le registre valide que le hash SHA-256 du fulfilment correspond à la condition du transfert. Si oui, il valide la transaction. Sinon, il la rejette, et le FSP bénéficiaire annule la réservation préalablement effectuée.

Le fulfilment est ensuite transmis au FSP payeur via la même chaîne de registres dans le callback du transfert. Chaque ledger engage les fonds après validation du fulfilment, et l’entité initiatrice est notifiée que ses fonds ont été libérés et reçoit le fulfilment.

Le dernier transfert à engager est celui sur le registre du FSP payeur, où la réservation est déduite de son compte. Le FSP payeur notifie alors le payeur du succès de la transaction.

# Requêtes

Cette section décrit les services pouvant être demandés par un client de l’API sur la ressource /transfers.

# GET /transfers/{ID}

URI alternative : N/A

Service logique d’API : Retourner le résultat de l’autorisation

La requête HTTP GET /transfers/{ID} est utilisée pour obtenir des informations sur un transfert créé ou demandé précédemment. Le {ID} dans l’URI doit contenir le transferId (voir Tableau 23) utilisé lors de la création du transfert.

Informations sur les callbacks et modèle de données pour GET /transfers/{ID} :

• Callback -- PUT /transfers/{ID}
• Callback d’erreur -- PUT /transfers/{ID}/error
• Modèle de données -- Corps vide

# POST /transfers

URI alternative : N/A

Service logique d’API : Effectuer le transfert

La requête HTTP POST /transfers est utilisée pour demander la création d’un transfert pour le prochain ledger, et une transaction financière pour le FSP bénéficiaire.

Informations sur les callbacks et modèle de données pour POST /transfers :

• Callback -- PUT /transfers/{ID}
• Callback d’erreur -- PUT /transfers/{ID}/error
• Modèle de données -- Voir Tableau 30

# Tableau 30

Tableau 30 – Modèle de données POST /transfers

# PATCH /transfers/{ID}

URI alternative : N/A

Service logique d’API : Notification de commit

La requête HTTP PATCH /transfers/{ID} est utilisée par un Switch pour mettre à jour l’état d’un transfert réservé si le FSP bénéficiaire a demandé une notification de commit, une fois le traitement terminé côté Switch. Le {ID} doit contenir le transferId (voir Tableau 30) utilisé pour la création du transfert. Notez que cette requête ne génère pas de callback. Voir Tableau 31 pour le modèle de données.

# Tableau 31

Tableau 31 – Modèle de données PATCH /transfers/{ID}

# Callbacks

Cette section décrit les callbacks utilisés par le serveur sous la ressource /transfers.

# PUT /transfers/{ID}

URI alternative : N/A

Service logique d’API : Retourner les informations du transfert

Le callback PUT /transfers/{ID} est utilisé pour informer le client d’un transfert demandé ou créé. Le {ID} dans l’URI doit contenir le transferId (voir Tableau 30) utilisé à la création ou celui utilisé dans le GET /transfers/{ID}. Voir Tableau 32 pour le modèle de données.

Remarque : pour les callbacks PUT /transfers/{ID} , l’état ABORTED n’est pas une option valide pour le champ transferState en Tableau 32. Si un transfert doit être rejeté, l’émetteur du callback doit utiliser un callback d’erreur, c’est-à-dire callback sur l’endpoint /error. Cependant, l’état ‘ABORTED’ est valide en réponse à un appel GET /transfers/{ID} .

# Tableau 32

Tableau 32 -- Modèle de données PUT /transfers/{ID}

# Callbacks d’erreur

Cette section décrit les callbacks d’erreur utilisés par le serveur sous la ressource /transfers.

# PUT /transfers/{ID}/error

URI alternative : N/A

Service logique d’API : Retourner une erreur d’information de transfert

Si le serveur ne trouve pas ou ne crée pas un transfert, ou qu’une autre erreur de traitement survient, le callback d’erreur PUT

/transfers/{ID}/error est utilisé. Le {ID} dans l’URI doit être le transferId (voir Tableau 30) utilisé lors de la création du transfert, ou celui utilisé dans le GET /transfers/{ID}. Voir Tableau 33 pour le modèle de données.

# Tableau 33

Tableau 33 -- Modèle de données PUT /transfers/{ID}/error

6.7.6 États

# Figure 56

Les états possibles d’un transfert sont représentés dans Figure 56.

Figure 56 -- États possibles d’un transfert

# Ressource d’API /transactions

Cette section définit la ressource logique d’API Transactions, décrite dans Modèles de transaction génériques.

Les services fournis par la ressource /transactions permettent d’obtenir des informations sur la transaction financière de bout en bout exécutée ; par exemple, obtenir les détails d’un éventuel code/ticket généré lors de la transaction.

La transaction financière réelle est exécutée via la ressource d’API /transfers, qui inclut la transaction de bout en bout entre le FSP payeur et le FSP bénéficiaire.

# Historique des versions de la ressource

Tableau 34 décrit les différentes versions de la ressource /transactions.

# Tableau 34

Tableau 34 – Historique des versions de la ressource /transactions

# Détails des services

Figure 57 montre un exemple du processus de transaction. La transaction réelle sera exécutée lors du processus de transfert. Le service GET /transactions/{TransactionID} peut ensuite être utilisé pour obtenir plus d’informations sur la transaction financière exécutée lors du transfert.

# Figure 57

Figure 57 -- Exemple de processus de transaction

# Requêtes

Cette section décrit les services pouvant être demandés par un client sur la ressource /transactions.

# GET /transactions/{ID}

URI alternative : N/A

Service logique d’API : Récupérer les informations sur la transaction

La requête HTTP GET /transactions/{ID} est utilisée pour obtenir des informations sur une transaction financière précédemment créée. Le {ID} doit correspondre au transactionId utilisé lors de la création du devis (voir Tableau 23), car la transaction est créée dans le cadre d’un autre processus (le transfert, voir API Resource Transfers).

Informations sur les callbacks et modèles de données pour GET /transactions/{ID} :

• Callback -- PUT /transactions/{ID}
• Callback d’erreur -- PUT /transactions/{ID}/error
• Modèle de données -- Corps vide

# Callbacks

Cette section décrit les callbacks utilisés par le serveur sous la ressource /transactions.

# PUT /transactions/{ID}

URI alternative : N/A

Service logique d’API : Retourner les informations de la transaction

Le callback PUT /transactions/{ID} est utilisé pour informer le client d’une transaction demandée. Le {ID} doit être celui utilisé dans le GET /transactions/{ID}. Voir Tableau 35 pour le modèle de données.

# Tableau 35

Tableau 35 -- Modèle de données PUT /transactions/{ID}

# Callbacks d’erreur

Cette section décrit les callbacks d’erreur utilisés par le serveur sous la ressource /transactions.

# PUT /transactions/{ID}/error

URI alternative : N/A

Service logique d’API : Retourner une erreur concernant la transaction

Si le serveur ne parvient pas à trouver ou créer une transaction, ou en cas d’erreur de traitement, le callback d’erreur PUT /transactions/{ID}/error est utilisé. Le {ID} doit être celui utilisé dans le GET /transactions/{ID}. Voir Tableau 36 pour le modèle de données.

# Tableau 36

Tableau 36 -- Modèle de données PUT /transactions/{ID}/error

# États

# Figure 58

Les états possibles d'une transaction sont illustrés à la Figure 58.

Remarque : À des fins de rapprochement, un serveur doit conserver dans sa base de données, pendant une période définie par le système, les objets transactionnels ayant été rejetés. Cela signifie qu’un client peut s’attendre à recevoir un callback approprié concernant une transaction (si celle-ci a bien été reçue par le serveur) lorsqu’il demande des informations à son sujet.

Figure 58 -- États possibles d'une transaction

# Ressource API /bulkQuotes

Cette section définit la ressource logique d'API Bulk Quotes (Devis en lot), comme décrit dans Modèles de transactions génériques.

Les services fournis par la ressource API /bulkQuotes sont utilisés pour demander la création d’un devis en lot, c’est-à-dire un devis pour plus d’une transaction financière. Pour plus d’informations concernant un devis unique pour une transaction, voir la ressource API /quotes.

Un objet de devis en lot créé contient un devis pour chaque transaction individuelle du lot au sein d’un FSP Pair. Un devis en lot est irrévocable ; il ne peut pas être modifié après sa création. Toutefois, il peut expirer (tous les devis en lot ne sont valables que jusqu’à leur expiration).

Remarque : Un devis en lot n’est pas une garantie de réussite de la transaction financière. La transaction en lot peut toujours échouer ultérieurement dans le processus. Un devis en lot garantit seulement que les frais et commissions FSP applicables à l'opération spécifiée restent valables tant que le devis n’est pas expiré.

# Historique des versions de la ressource

Le Tableau 37 présente une description de chaque version différente de la ressource /bulkQuotes.

Tableau 37 –- Historique des versions pour la ressource /bulkQuotes

# Détails du service

La Figure 59 illustre le fonctionnement du processus de devis en lot, utilisant le service POST /bulkQuotes. À la réception d’un lot de transactions de la part du Payeur, le FSP du Payeur doit :

1. Rechercher à quel FSP appartient chaque Bénéficiaire ; par exemple, en utilisant la ressource API /participants.

2. Diviser le lot selon le FSP du Bénéficiaire. Le service POST /bulkQuotes est alors utilisé pour chaque FSP de Bénéficiaire pour obtenir les devis en lot de chacun. Chaque résultat de devis contiendra le paquet ILP et la condition (voir Paquet ILP et Transferts conditionnels) nécessaires pour effectuer chaque transfert dans le transfert en lot (voir la ressource API /bulkTransfers), qui réalisera effectivement la transaction financière du Payeur vers chaque Bénéficiaire.

# Figure 59

Figure 59 -- Exemple de processus de devis en lot

# Requêtes

Cette section décrit les services pouvant être demandés par un client sur la ressource API /bulkQuotes.

# GET /bulkQuotes/{ID}

URI alternative : N/A

Service logique d’API : Récupérer les informations du devis en lot

La requête HTTP GET /bulkQuotes/{ID} est utilisée pour obtenir des informations concernant un devis en lot préalablement créé ou demandé.

Le {ID} de l’URI doit contenir le bulkQuoteId (voir Tableau 38) utilisé pour la création du devis en lot.

Informations sur les callbacks et le modèle de données pour GET /bulkQuotes/{ID} :

• Callback -- PUT /bulkQuotes/**{ID}
• Callback d’erreur -- PUT /bulkQuotes/{ID}/error**
• Modèle de données -- Corps vide

# POST /bulkQuotes

URI alternative : N/A

Service logique d’API : Calculer un devis en lot

La requête HTTP POST /bulkQuotes est utilisée pour demander la création d’un devis en lot pour les transactions financières fournies sur le serveur.

Informations sur les callbacks et le modèle de données pour POST /bulkQuotes :

• Callback -- PUT /bulkQuotes/{ID}
• Callback d’erreur -- PUT /bulkQuotes/{ID}/error
• Modèle de données -- Voir Tableau 38

# Tableau 38

Tableau 38 -- Modèle de données POST /bulkQuotes

# Callbacks

Cette section décrit les callbacks utilisés par le serveur sous la ressource /bulkQuotes.

# PUT /bulkQuotes/{ID}

URI alternative : N/A

Service logique d’API : Retourner les informations du devis en lot

Le callback PUT /bulkQuotes/{ID} est utilisé pour informer le client d’un devis en lot demandé ou créé. Le {ID} de l’URI doit contenir le bulkQuoteId (voir Tableau 38) utilisé pour la création du devis en lot, ou le {ID} qui a été utilisé dans le GET /bulkQuotes/{ID}. Voir Tableau 39 pour le modèle de données.

# Tableau 39

Tableau 39 -- Modèle de données PUT /bulkQuotes/{ID}

# Callbacks d’erreur

Cette section décrit les callbacks d’erreur utilisés par le serveur sous la ressource /bulkQuotes.

# PUT /bulkQuotes/{ID}/error

URI alternative : N/A

Service logique d’API : Retourner une erreur concernant le devis en lot

Si le serveur ne parvient pas à trouver ou créer un devis en lot, ou en cas d’erreur de traitement, le callback d’erreur PUT /bulkQuotes/{ID}/error est utilisé. Le {ID} de l’URI doit contenir le bulkQuoteId (voir Tableau 38) utilisé pour la création du devis, ou le {ID} utilisé dans le GET /bulkQuotes/{ID}. Voir Tableau 40 pour le modèle de données.

# Tableau 40

Tableau 40 -- Modèle de données PUT /bulkQuotes/{ID}/error

# États

# Figure 60

Les états possibles d’un devis en lot sont illustrés à la Figure 60.

Remarque : Un serveur n’a pas besoin de conserver dans sa base de données les objets de devis en lot qui ont été rejetés ou expirés. Cela signifie qu’un client doit s’attendre à recevoir un callback d’erreur pour un devis en lot rejeté ou expiré.

Figure 60 -- États possibles d’un devis en lot

# Ressource API /bulkTransfers

Cette section définit la ressource logique d'API Bulk Transfers (Transferts en lot), comme décrit dans Modèles de transactions génériques.

Les services fournis par la ressource API /bulkTransfers sont utilisés pour demander la création d’un transfert en lot ou pour obtenir des informations sur un transfert en lot précédemment demandé. Pour plus d'informations sur un transfert individuel, voir la ressource API /transfers. Avant qu’un transfert en lot ne puisse être demandé, un devis en lot doit être réalisé. Voir la ressource API /bulkQuotes pour plus d’informations.

Un transfert en lot est irrévocable ; il ne peut pas être modifié, annulé ou inversé après avoir été envoyé par le FSP du Payeur.

# Historique des versions de la ressource

Le Tableau 41 présente une description de chaque version différente de la ressource /bulkTransfers.

Tableau 41 –- Historique des versions pour la ressource /bulkTransfers

# Détails du service

La Figure 61 illustre le fonctionnement du processus de transfert en lot utilisant le service POST /bulkTransfers. Lors de la réception des transactions groupées du Payeur, le FSP du Payeur doit effectuer les étapes suivantes :

1. Rechercher à quel FSP appartient chaque Bénéficiaire ; par exemple, en utilisant la ressource API /participants, Section 6.2.
2. Effectuer le processus de devis en lot en utilisant la ressource API /bulkQuotes, Section 6.9. Le callback du devis en lot doit contenir les paquets ILP requis et les conditions nécessaires à l’exécution de chaque transfert.
3. Effectuer le processus de transfert en lot comme dans la Figure 61 en utilisant POST /bulkTransfers. Ceci réalise chaque transfert “hop-to-hop” et la transaction financière de bout en bout. Pour plus d’informations sur les transferts “hop-to-hop” versus les transactions financières de bout en bout, voir Section 6.7.

# Figure 61

Figure 61 -- Exemple de processus de transfert en lot

# Requêtes

Cette section décrit les services pouvant être demandés par un client sur la ressource /bulkTransfers.

# GET /bulkTransfers/{ID}

URI alternative : N/A

Service logique d’API : Récupérer les informations du transfert en lot

La requête HTTP GET /bulkTransfers/{ID} est utilisée pour obtenir des informations concernant un transfert en lot préalablement créé ou demandé. Le {ID} de l’URI doit contenir le bulkTransferId (voir Tableau 42) utilisé pour la création du transfert.

Informations sur les callbacks et le modèle de données pour GET /bulkTransfers/{ID} :

• Callback -- PUT /bulkTransfers/{ID}
• Callback d’erreur -- PUT /bulkTransfers/{ID}/error
• Modèle de données -- Corps vide

# POST /bulkTransfers

URI alternative : N/A

Service logique d’API : Exécuter un transfert en lot

La requête HTTP POST /bulkTransfers est utilisée pour demander la création d’un transfert en lot sur le serveur.

• Callback - PUT /bulkTransfers/{ID}
• Callback d’erreur - PUT /bulkTransfers/{ID}/error
• Modèle de données -- Voir Tableau 42

# Tableau 42

Tableau 42 -- Modèle de données POST /bulkTransfers

# Callbacks

Cette section décrit les callbacks utilisés par le serveur sous la ressource /bulkTransfers.

# PUT /bulkTransfers/{ID}

URI alternative : N/A

Service logique d’API : Récupérer les informations du transfert en lot

Le callback PUT /bulkTransfers/{ID} est utilisé pour informer le client d’un transfert en lot demandé ou créé. Le {ID} de l’URI doit contenir le bulkTransferId (voir Tableau 42) utilisé pour la création du transfert (POST /bulkTransfers), ou le {ID} utilisé dans le GET /bulkTransfers/{ID}. Voir Tableau 43 pour le modèle de données.

# Tableau 43

Tableau 43 -- Modèle de données PUT /bulkTransfers/{ID}

# Callbacks d’erreur

Cette section décrit les callbacks d’erreur utilisés par le serveur sous la ressource /bulkTransfers.

# PUT /bulkTransfers/{ID}/error

URI alternative : N/A

Service logique d’API : Retourner une erreur concernant le transfert en lot

Si le serveur ne parvient pas à trouver ou créer un transfert en lot, ou en cas d’erreur de traitement, le callback d’erreur PUT /bulkTransfers/{ID}/error est utilisé. Le {ID} de l’URI doit contenir le bulkTransferId (voir Tableau 42) utilisé pour la création du transfert (POST /bulkTransfers), ou le {ID} utilisé dans le GET /bulkTransfers/{ID}. Voir Tableau 44 pour le modèle de données.

# Tableau 44

Tableau 44 -- Modèle de données PUT /bulkTransfers/{ID}/error

# États

# Figure 62

Les états possibles d’un transfert en lot sont illustrés à la Figure 62.

Remarque : À des fins de rapprochement, un serveur doit conserver dans sa base de données les objets de transfert en lot ayant été rejetés durant une période définie par le marché. Cela signifie qu’un client peut s’attendre à recevoir un callback approprié concernant un transfert en lot (si celui-ci a bien été reçu par le serveur) lorsqu’il demande des informations à son sujet.

Figure 62 -- États possibles d’un transfert en lot

# Modèles de données de support de l’API

Cette section fournit des informations sur des modèles de données complémentaires utilisés par l’API.

# Introduction sur le format

Cette section introduit les formats utilisés pour les types de données des éléments employés par l’API.

Tous les types de données d’élément ont à la fois une longueur minimale et maximale. Ces longueurs sont indiquées de l’une des façons suivantes :

• Une longueur minimale et maximale
• Une longueur exacte
• Une expression régulière limitant l’élément de façon à n’autoriser qu’une ou plusieurs longueurs spécifiques.

# Longueur minimale et maximale

Lorsqu’une longueur minimale et maximale est utilisée, cela sera indiqué après le type de données entre parenthèses : d’abord la valeur minimale (incluse), suivie de deux points consécutifs, puis la valeur maximale (incluse).

Exemples :

• String(1..32) – Une chaîne de caractères d’au moins un caractère et au maximum 32 caractères.
• Integer(3..10) - Un entier d’au moins 3 chiffres et au maximum 10 chiffres.

# Longueur exacte

Lorsqu’une longueur exacte est utilisée, cela sera indiqué après le type de données entre parenthèses contenant une seule valeur exacte. Les autres longueurs ne sont pas permises.

Exemples :

• String(3) – Une chaîne de caractères d’exactement trois caractères.
• Integer(4) – Un entier d’exactement quatre chiffres.

# Expressions régulières

Certains types de données d’élément sont limités par des expressions régulières. Les expressions régulières dans ce document utilisent la norme de syntaxe et les classes de caractères établies par le langage de programmation Perl^{30 (opens new window)}.

# Formats des types de données d’éléments

Cette section définit les types de données d’éléments utilisés par l’API.

# String

Le type de données API String est une chaîne JSON normale^{31 (opens new window)}, limitée par un nombre maximum et minimum de caractères.

# Exemple de format I

String(1..32) – Une chaîne de caractères d’au moins 1 caractère et au maximum 32 caractères.

Un exemple de String(1..32) apparaît ci-dessous :

• Cette chaîne fait 28 caractères

# Exemple de format II

String(1..128) – Une chaîne de caractères d’au moins 1 caractère et au maximum 128 caractères.

Un exemple de String(32..128) apparaît ci-dessous :

• Cette chaîne est plus longue que 32 caractères, mais inférieure à 128

# Enum

Le type de données API Enum est une liste restreinte de valeurs JSON String) autorisées ; une énumération de valeurs. D’autres valeurs que celles définies dans la liste ne sont pas autorisées.

# Exemple de format

Enum of String(1..32) – Une chaîne de caractères d’au moins un caractère et au maximum 32 caractères restreinte par la liste des valeurs autorisées. La description de l’élément contient un lien vers l’énumération.

# UndefinedEnum

Le type de données d’API UndefinedEnum est une chaîne JSON constituée de 1 à 32 caractères en majuscule, incluant le caractère de soulignement (**_****).

# Expression régulière

L’expression régulière limitant le type UndefinedEnum apparaît dans Liste 13.

# Liste 13

^[A-Z_]{1,32}$

Liste 13 -- Expression régulière pour le type de données UndefinedEnum

# Name

Le type de données API Name est une chaîne JSON, restreinte par une expression régulière pour éviter les caractères généralement non utilisés dans un nom.

# Expression régulière

L’expression régulière limitant le type Name apparaît dans la Liste 14 ci-dessous. La contrainte n’autorise pas une chaîne constituée uniquement d’espaces, tous les caractères Unicode32 sont autorisés, ainsi que le point (.), l’apostrophe ('), le tiret (-), la virgule (,) et l’espace ( ). Le nombre maximal de caractères pour Name est 128.

Remarque : Dans certains langages de programmation, le support Unicode doit être explicitement activé. Par exemple, si Java est utilisé, il faut activer le flag UNICODE_CHARACTER_CLASS pour permettre les caractères Unicode.

# Liste 14

^(?!\s*$)[\w .,'-]{1,128}$

Liste 14 -- Expression régulière pour le type de données Name

# Integer

Le type de données API Integer est une chaîne JSON composée uniquement de chiffres. Les nombres négatifs et les zéros initiaux ne sont pas autorisés. Le type de données est toujours limité par un nombre de chiffres.

# 7.2.5.1 Expression régulière

L’expression régulière restreignant le type Integer apparaît à la Liste 15.

# Liste 15

^[1-9]\d*$

Liste 15 -- Expression régulière pour le type de données Integer

# Exemple de format

Integer(1..6) – Un Integer d’au moins un chiffre et de six chiffres au maximum.

Un exemple de Integer(1..6) apparaît ci-dessous :

• 123456

# OtpValue

Le type de données API OtpValue est une chaîne JSON de trois à dix caractères composée uniquement de chiffres. Les nombres négatifs ne sont pas autorisés. Un ou plusieurs zéros initiaux sont autorisés.

# Expression régulière

L’expression régulière limitant le type OtpValue apparaît dans la Liste 16.

# Liste 16

^\d{3,10}$

Liste 16 -- Expression régulière pour le type de données OtpValue

# BopCode

Le type de données API BopCode est une chaîne JSON de trois caractères, composée uniquement de chiffres. Les nombres négatifs ne sont pas autorisés. Un zéro initial n’est pas permis.

# Expression régulière

L’expression régulière limitant le type BopCode apparaît à la Liste 17.

# Liste 17

^[1-9]\d{2}$

Liste 17 -- Expression régulière pour le type de données BopCode

# ErrorCode

Le type de données API ErrorCode est une chaîne JSON de quatre caractères, composée uniquement de chiffres. Les nombres négatifs ne sont pas autorisés. Un zéro initial n’est pas permis.

# Expression régulière

L’expression régulière limitant le type ErrorCode apparaît à la Liste 18.

# Liste 18

^[1-9]\d{3}$

Liste 18 -- Expression régulière pour le type de données ErrorCode

# TokenCode

Le type de données API TokenCode est une chaîne JSON comprise entre quatre et 32 caractères. Elle peut être composée de chiffres, de lettres majuscules (A à Z), de lettres minuscules (a à z), ou d’une combinaison des trois.

# 7.2.9.1 Expression régulière

L’expression régulière limitant le type TokenCode apparaît à la Liste 19.

# Liste 19

^[0-9a-zA-Z]{4,32}$

Liste 19 -- Expression régulière pour le type de données TokenCode

# MerchantClassificationCode

Le type de données API MerchantClassificationCode est une chaîne JSON composée de un à quatre chiffres.

# 7.2.10.1 Expression régulière

L’expression régulière limitant le type MerchantClassificationCode apparaît à la Liste 20.

# Liste 20

^[\d]{1,4}$

Liste 20 -- Expression régulière pour le type de données MerchantClassificationCode

# Latitude

Le type de données API Latitude est une chaîne JSON au format lexical restreinte par une expression régulière pour des raisons d’interopérabilité.

# 7.2.11.1 Expression régulière

L’expression régulière limitant le type Latitude apparaît à la Liste 21.

# Liste 21

^(\+|-)?(?:90(?:(?:\.0{1,6})?)|(?:[0-9]|[1-8][0-9])(?:(?:\.[0-9]{1,6})?))$

Liste 21 -- Expression régulière pour le type de données Latitude

# Longitude

Le type de données API Longitude est une chaîne JSON au format lexical restreinte par une expression régulière pour des raisons d’interopérabilité.

# 7.2.12.1 Expression régulière

L’expression régulière limitant le type Longitude apparaît à la Liste 22.

# Liste 22

^(\+|-)?(?:180(?:(?:\.0{1,6})?)|(?:[0-9]|[1-9][0-9]|1[0-7][0-9])(?:(?:\.[0-9]{1,6})?))$

Liste 22 -- Expression régulière pour le type de données Longitude

# Amount

Le type de données API Amount est une chaîne JSON au format canonique restreinte par une expression régulière pour des raisons d’interopérabilité.

# Expression régulière

L’expression régulière limitant le type Amount apparaît à la Liste 23. Ce motif n’autorise aucune décimale finale à zéro, mais autorise un montant sans unité monétaire mineure. Il permet également uniquement quatre chiffres dans l’unité monétaire mineure ; une valeur négative n’est pas acceptée. L’utilisation de plus de 18 chiffres dans l’unité monétaire majeure n’est pas acceptée.

# Liste 23

^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])?$

Liste 23 -- Expression régulière pour le type de données Amount

# Exemples de valeurs

Consultez le Tableau 45 pour les résultats de validation pour quelques exemples de valeurs Amount à l’aide de l’expression régulière.

# Tableau 45

Tableau 45 -- Exemples de résultats pour différentes valeurs du type Amount

# DateTime

Le type de données API DateTime est une chaîne JSON au format lexical qui est restreinte par une expression régulière pour des raisons d’interopérabilité.

# 7.2.14.1 Expression Régulière

L’expression régulière limitant le type DateTime apparaît à la Liste 24. Le format est conforme à l’ISO 8601, exprimé en une date, une heure et un fuseau horaire combinés. Une version plus lisible du format est :

aaaa-MM-jjTHH:mm:ss.SSS[-HH:MM]

# Liste 24

^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468\][048]|[13579][26])00)-02-29)T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:(\.\d{3}))(?:Z|[+-][01]\d:[0-5]\d)$

Liste 24 -- Expression régulière pour le type de données DateTime

# Exemples

Deux exemples du type DateTime apparaissent ci-dessous :

2016-05-24T08:38:08.699-04:00

2016-05-24T08:38:08.699Z (où Z indique le fuseau horaire Zulu, identique à UTC).

# Date

Le type de données API Date est une chaîne JSON au format lexical restreinte par une expression régulière pour garantir l’interopérabilité.

# Expression Régulière

L’expression régulière restreignant le type Date apparaît à la Liste 25. Ce format, tel que spécifié dans la norme ISO 8601, contient uniquement une date. Une version plus lisible est aaaa-MM-jj.

# Liste 25

^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$

Liste 25 -- Expression régulière pour le type de données Date

# Exemples

Deux exemples de type Date apparaissent ci-dessous :

• 1982-05-23

• 1987-08-05

# UUID

Le type de données API UUID (Identifiant Unique Universel) est une chaîne JSON au format canonique, conforme à la RFC 4122, restreinte par une expression régulière pour garantir l’interopérabilité. Un UUID fait toujours 36 caractères de long, soit 32 caractères hexadécimaux et quatre tirets (« - »).

# 7.2.16.1 Expression Régulière

L’expression régulière restreignant le type UUID figure à la Liste 26.

# Liste 26

^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Liste 26 -- Expression régulière pour le type de données UUID

# Exemple

Un exemple de type UUID :

• a8323bc6-c228-4df2-ae82-e5a997baf898

# BinaryString

Le type de données API BinaryString est une chaîne JSON. La chaîne est un encodage base64url d’une séquence d’octets bruts, où un caractère de bourrage (‘=’) est ajouté à la fin des données si besoin afin de garantir que la chaîne est un multiple de quatre caractères. La contrainte de longueur indique le nombre de caractères autorisés.

# Expression Régulière

L’expression régulière limitant le type BinaryString apparaît à la Liste 27.

# Liste 27

^[A-Za-z0-9-_]+[=]{0,2}$

Liste 27 -- Expression régulière pour le type de données BinaryString

# Exemple de format

BinaryString(32) – 32 octets de données encodés en base64url.

Un exemple de BinaryString(32..256) figure ci-dessous. Notez qu’un caractère de bourrage '=' a été ajouté pour garantir que la chaîne soit un multiple de quatre caractères.

• QmlsbCAmIE1lbGluZGEgR2F0ZXMgRm91bmRhdGlvbiE=

# BinaryString32

Le type de données API BinaryString32 est une version à taille fixe du type de données API BinaryString défini plus haut, où les données sont toujours de 32 octets. BinaryString32 ne doit pas utiliser de caractère de bourrage puisque la taille des données sous-jacentes est fixe.

# Expression Régulière

L’expression régulière limitant le type BinaryString32 apparaît à la Liste 28.

# Liste 28

^[A-Za-z0-9-_]{43}$

Liste 28 -- Expression régulière pour le type de données BinaryString32

# Exemple de format

BinaryString(32) – 32 octets de données encodés en base64url.

Un exemple de BinaryString32 figure ci-dessous. Il s’agit des mêmes données binaires que dans l’exemple du format d’exemple du type BinaryString, mais comme la taille sous-jacente est fixe, le caractère de bourrage '=' est exclu.

QmlsbCAmIE1lbGluZGEgR2F0ZXMgRm91bmRhdGlvbiE

# Définitions des éléments

Cette section définit les types d’éléments utilisés par l’API.

# Élément AmountType

Le tableau 46 ci-dessous présente le modèle de données pour l’élément AmountType.

# Tableau 46

Tableau 46 – Élément AmountType

# Élément AuthenticationType

Le tableau 47 ci-dessous présente le modèle de données pour l’élément AuthenticationType.

# Tableau 47

Tableau 47 – Élément AuthenticationType

# Élément AuthenticationValue

Le tableau 48 ci-dessous présente le modèle de données pour l’élément AuthenticationValue.

# Tableau 48

Tableau 48 – Élément AuthenticationValue

# Élément AuthorizationResponse

Le tableau 49 ci-dessous présente le modèle de données pour l’élément AuthorizationResponse.

# Tableau 49

Tableau 49 – Élément AuthorizationResponse

# Élément BalanceOfPayments

Le tableau 50 ci-dessous présente le modèle de données pour l’élément BalanceOfPayment.

# Tableau 50

Tableau 50 – Élément BalanceOfPayments

# Élément BulkTransferState

Le tableau 51 ci-dessous présente le modèle de données pour l’élément BulkTransferState.

# Tableau 51

Tableau 51 – Élément BulkTransferState

# Élément Code

Le tableau 52 ci-dessous présente le modèle de données pour l’élément Code.

# Tableau 52

Tableau 52 – Élément Code

# Élément CorrelationId

Le tableau 53 ci-dessous présente le modèle de données pour l’élément CorrelationId.

# Tableau 53

Tableau 53 – Élément CorrelationId

# Élément Currency

Le tableau 54 ci-dessous présente le modèle de données pour l’élément Currency.

# Tableau 54

Tableau 54 – Élément Currency

# Élément DateOfBirth

Le tableau 55 ci-dessous présente le modèle de données pour l’élément DateOfBirth.

# Tableau 55

Tableau 55 – Élément DateOfBirth

# Élément ErrorCode

Le tableau 56 ci-dessous présente le modèle de données pour l’élément ErrorCode.

# Tableau 56

Tableau 56 – Élément ErrorCode

# Élément ErrorDescription

Le tableau 57 ci-dessous présente le modèle de données pour l’élément ErrorDescription.

# Tableau 57

Tableau 57 – Élément ErrorDescription

# Élément ExtensionKey

Le tableau 58 ci-dessous présente le modèle de données pour l’élément ExtensionKey.

# Tableau 58

Tableau 58 – Élément ExtensionKey

# Élément ExtensionValue

Le tableau 59 ci-dessous présente le modèle de données pour l’élément ExtensionValue.

# Tableau 59

Tableau 59 – Élément ExtensionValue

# Élément FirstName

Le tableau 60 ci-dessous présente le modèle de données pour l’élément FirstName.

# Tableau 60

Tableau 60 – Élément FirstName

# Élément FspId

Le tableau 61 ci-dessous présente le modèle de données pour l’élément FspId.

# Tableau 61

Tableau 61 – Élément FspId

# Élément IlpCondition

Le tableau 62 ci-dessous présente le modèle de données pour l’élément IlpCondition.

# Tableau 62

Tableau 62 – Élément IlpCondition

# Élément IlpFulfilment

Le tableau 63 ci-dessous présente le modèle de données pour l’élément IlpFulfilment.

# Tableau 63

Tableau 63 – Élément IlpFulfilment

# Élément IlpPacket

Le tableau 64 ci-dessous présente le modèle de données pour l’élément IlpPacket.

# Tableau 64

Tableau 64 – Élément IlpPacket

# Élément LastName

Le tableau 65 ci-dessous présente le modèle de données pour l’élément LastName.

# Tableau 65

Tableau 65 – Élément LastName

# Élément MerchantClassificationCode

Le tableau 66 ci-dessous présente le modèle de données pour l’élément MerchantClassificationCode.

# Tableau 66

Tableau 66 – Élément MerchantClassificationCode

# Élément MiddleName

Le tableau 67 ci-dessous présente le modèle de données pour l’élément MiddleName.

# Tableau 67

Tableau 67 – Élément MiddleName

# Élément Note

Le tableau 68 ci-dessous présente le modèle de données pour l’élément Note.

# Tableau 68

Tableau 68 – Élément Note

# Élément PartyIdentifier

Le tableau 69 ci-dessous présente le modèle de données pour l’élément PartyIdentifier.

# Tableau 69

Tableau 69 – Élément PartyIdentifier

# Élément PartyIdType

Le tableau 70 ci-dessous présente le modèle de données pour l’élément PartyIdType.

# Tableau 70

Tableau 70 – Élément PartyIdType

# Élément PartyName

Le tableau 71 ci-dessous présente le modèle de données pour l’élément PartyName.

# Tableau 71

Tableau 71 – Élément PartyName

# Élément PartySubIdOrType

Le tableau 72 ci-dessous présente le modèle de données pour l’élément PartySubIdOrType.

# Tableau 72

Tableau 72 – Élément PartySubIdOrType

# Élément RefundReason

Le tableau 73 ci-dessous présente le modèle de données pour l’élément RefundReason.

# Tableau 73

Tableau 73 – Élément RefundReason

# Élément TransactionInitiator

Le tableau 74 ci-dessous présente le modèle de données pour l’élément TransactionInitiator.

# Tableau 74

Tableau 74 – Élément TransactionInitiator

# Élément TransactionInitiatorType

Le tableau 75 ci-dessous présente le modèle de données pour l’élément TransactionInitiatorType.

# Tableau 75

Tableau 75 – Élément TransactionInitiatorType

# Élément TransactionRequestState

Le tableau 76 ci-dessous présente le modèle de données pour l’élément TransactionRequestState.

# Tableau 76

Tableau 76 – Élément TransactionRequestState

# Élément TransactionScenario

Le tableau 77 ci-dessous présente le modèle de données pour l’élément TransactionScenario.

# Tableau 77

Tableau 77 – Élément TransactionScenario

# Élément TransactionState

Le tableau 78 ci-dessous présente le modèle de données pour l’élément TransactionState.

# Tableau 78

Tableau 78 – Élément TransactionState

# Élément TransactionSubScenario

Le tableau 79 ci-dessous présente le modèle de données pour l’élément TransactionSubScenario.

# Tableau 79

Tableau 79 – Élément TransactionSubScenario

# Élément TransferState

Le tableau 80 ci-dessous présente le modèle de données pour l’élément TransferState.

# Tableau 80

Tableau 80 – Élément TransferState

# Types Complexes

Cette section décrit les types complexes utilisés par l’API.

# AuthenticationInfo

Le tableau 81 présente le modèle de données pour le type complexe AuthenticationInfo.

# Tableau 81

Tableau 81 -- Type complexe AuthenticationInfo

# ErrorInformation

Le tableau 82 présente le modèle de données pour le type complexe ErrorInformation.

# Tableau 82

Tableau 82 -- Type complexe ErrorInformation

# Extension

Le tableau 83 présente le modèle de données pour le type complexe Extension.

# Tableau 83

Tableau 83 -- Type complexe Extension

# ExtensionList

Le tableau 84 présente le modèle de données pour le type complexe ExtensionList.

# Tableau 84

Tableau 84 -- Type complexe ExtensionList

# IndividualQuote

Le tableau 85 présente le modèle de données pour le type complexe IndividualQuote.

# Tableau 85

Tableau 85 -- Type complexe IndividualQuote

# IndividualQuoteResult

Le tableau 86 présente le modèle de données pour le type complexe IndividualQuoteResult.

# Tableau 86

Tableau 86 -- Type complexe IndividualQuoteResult

# IndividualTransfer

Le tableau 87 présente le modèle de données pour le type complexe IndividualTransfer.

# Tableau 87

Tableau 87 -- Type complexe IndividualTransfer

# IndividualTransferResult

Le tableau 88 présente le modèle de données pour le type complexe IndividualTransferResult.

# Tableau 88

Tableau 88 -- Type complexe IndividualTransferResult

# GeoCode

Le tableau 89 présente le modèle de données pour le type complexe GeoCode.

# Tableau 89

Tableau 89 -- Type complexe GeoCode

# Money

Le tableau 90 présente le modèle de données pour le type complexe Money.

# Tableau 90

Tableau 90 -- Type complexe Money

# Party

Le tableau 91 présente le modèle de données pour le type complexe Party.

# Tableau 91

Tableau 91 -- Type complexe Party

# PartyComplexName

Le tableau 92 présente le modèle de données pour le type complexe PartyComplexName.

# Tableau 92

Tableau 92 -- Type complexe PartyComplexName

# PartyIdInfo

Le tableau 93 présente le modèle de données pour le type complexe PartyIdInfo.

# Tableau 93

Tableau 93 -- Type complexe PartyIdInfo

# PartyPersonalInfo

Le tableau 94 présente le modèle de données pour le type complexe PartyPersonalInfo.

# Tableau 94

Tableau 94 -- Type complexe PartyPersonalInfo

# PartyResult

Le tableau 95 présente le modèle de données pour le type complexe PartyResult.

# Tableau 95

Tableau 95 -- Type complexe PartyResult

# Refund

Le tableau 96 présente le modèle de données pour le type complexe Refund.

# Tableau 96

Tableau 96 -- Type complexe Refund

# Transaction

Le tableau 97 présente le modèle de données pour le type complexe Transaction. Le type Transaction sert à véhiculer des données de bout en bout entre le FSP Payeur et le FSP Bénéficiaire dans le paquet ILP, voir IlpPacket. Les champs transactionId et quoteId sont décidés par le FSP Payeur lors du POST /quotes, voir Tableau 23.

# Tableau 97

Tableau 97 -- Type complexe Transaction

# TransactionType

Le tableau 98 présente le modèle de données pour le type complexe TransactionType.

# Tableau 98

Tableau 98 -- Type complexe TransactionType

# Énumérations

Cette section présente les énumérations utilisées par l’API.

# AmountType enum

Le tableau 99 présente les valeurs autorisées pour l’énumération AmountType.

# Tableau 99

Tableau 99 -- Énumération AmountType

# AuthenticationType enum

Le tableau 100 présente les valeurs autorisées pour l’énumération AuthenticationType.

# Tableau 100

Tableau 100 -- Énumération AuthenticationType

# AuthorizationResponse enum

Le tableau 101 présente les valeurs autorisées pour l’énumération AuthorizationResponse.

# Tableau 101

Tableau 101 -- Énumération AuthorizationResponse

# BulkTransferState enum

Le tableau 102 présente les valeurs autorisées pour l’énumération BulkTransferState.

# Tableau 102

Tableau 102 -- Énumération BulkTransferState

# Code devise (CurrencyCode) enum

Les codes de devise définis par la norme ISO 421736 sous forme de codes alphabétiques à trois lettres sont utilisés comme représentation standard des devises. Les codes ISO 4217 ne sont pas listés ici, les implémenteurs sont invités à se référer directement à la norme ISO 4217.

# PartyIdType enum

Le tableau 103 présente les valeurs autorisées pour l’énumération PartyIdType.

# Tableau 103

Tableau 103 -- Énumération PartyIdType

# PersonalIdentifierType enum

Le tableau 104 présente les valeurs autorisées pour l’énumération PersonalIdentifierType.

# Tableau 104

Tableau 104 -- Énumération PersonalIdentifierType

# TransactionInitiator

Le tableau 105 décrit les valeurs autorisées pour l’énumération TransactionInitiator.

# Tableau 105

Tableau 105 -- Énumération TransactionInitiator

# TransactionInitiatorType

Le tableau 106 présente les valeurs autorisées pour l’énumération TransactionInitiatorType.

# Tableau 106

Tableau 106 -- Énumération TransactionInitiatorType

# TransactionRequestState

Le tableau 107 présente les valeurs autorisées pour l’énumération TransactionRequestState.

# Tableau 107

Tableau 107 -- Énumération TransactionRequestState

# TransactionScenario

Le tableau 108 présente les valeurs autorisées pour l’énumération TransactionScenario.

# Tableau 108

Tableau 108 -- Énumération TransactionScenario

# TransactionState

Le tableau 109 présente les valeurs autorisées pour l’énumération TransactionState.

# Tableau 109

Tableau 109 -- Énumération TransactionState

# TransferState

Le tableau 110 présente les valeurs autorisées pour l’énumération TransferState.

# Tableau 110

Tableau 110 -- Énumération TransferState

# Codes d’erreur

# Figure 63

Chaque code d’erreur de l’API est un nombre à quatre chiffres, par exemple 1234, où le premier chiffre (1 ici) indique la catégorie d’erreur principale, le deuxième (2) la sous-catégorie, et les deux derniers (34) l’erreur spécifique. Figure 63 montre la structure d’un code d’erreur. Les sections suivantes détaillent les codes d’erreur définis pour chaque catégorie.

Figure 63 -- Structure des codes d’erreur

Chaque combinaison de catégories principale et secondaire possède une erreur générique (x0xx), utilisable s’il n’existe pas d’erreur plus spécifique, ou si le serveur ne souhaite pas communiquer plus d’information.

Toutes les erreurs spécifiques inférieures à xx40 (c’est-à-dire de xx00 à xx39) sont réservées à un usage ultérieur de l’API. Celles à partir de xx40 peuvent servir pour des besoins propres à un schéma. Si un client reçoit une erreur inconnue propre à un schéma, elle devra être traitée comme une erreur générique de la catégorie (xx00).

# Erreurs de communication -- 1_xxx_

Toutes les erreurs de communication ou réseau n’étant pas couvertes par un code HTTP doivent utiliser le code d’erreur principal 1 (codes 1xxx). Comme tous les services de l’API sont asynchrones, ces erreurs sont généralement émises par le Switch au client FSP si le FSP pair est injoignable ou si aucun callback n’est reçu dans le délai convenu.

Sous-catégories pour les erreurs de communication :

• Erreur de communication générique -- 10xx

Voir Tableau 111 pour la liste des erreurs de ce type.

# Tableau 111

Tableau 111 -- Erreurs de communication -- 1_xxx_

# Erreurs serveur -- 2_xxx_

Toutes les erreurs survenues côté serveur où ce dernier n’a pas pu satisfaire une requête apparemment valide du client utilisent la catégorie 2 (codes 2xxx). Ces erreurs signifient que le serveur est conscient d’avoir rencontré une erreur ou d’être incapable de traiter la demande.

Sous-catégories pour les erreurs serveur :

• Erreur serveur générique -- 20xx

Voir Tableau 112 pour les erreurs serveur définies.

# Tableau 112