iDEAL |
---|
Guide d'intégration |
Version 6.2.3 |
Date 07/06/2018 |
Table des matières
Historique des versions
Date | Nom | Modification |
---|---|---|
07/06/2018 | Peter Posse | Version originale |
iDEAL
Informations générales sur iDEAL
À l'instar de giropay en Allemagne, les banques néerlandaises ont établi la norme de virement iDEAL. Environ 50% de tous les paiements e-commerce aux Pays-Bas sont réalisés avec iDEAL. Proposer iDEAL est un facteur essentiel de réussite pour les entreprises de e-commerce souhaitant vendre aux Pays-Bas. Le client utilise la banque en ligne familière et fiable de son propre établissement bancaire, de la même manière qu'avec une banque en ligne.
Avec la banque en ligne, les données transmises lors du virement en ligne sont chiffrées SSL (Secure Socket Layer) pour parer à toute manipulation.
Les virements bancaires avec iDEAL sont une garantie de succès aux Pays-Bas : Environ 100.000 boutiques en ligne et organismes proposent iDEAL avec environ 50% de tous les paiements e-commerce traités via iDEAL. Ceci représente chaque mois environ 13 millions de transactions. |
Vous trouverez de plus amples informations (en néerlandais et en anglais) sur la page web d'iDEAL (www.ideal.nl).
Déroulement d'une transaction
Déroulement d'une transaction via iDEAL
Interface de la plateforme de paiement
Formats des données : a alphabétique as alphabétique avec caractères spéciaux n numérique an alphanumérique ans alphanumérique avec caractères spéciaux ns numérique avec caractères spéciaux bool expression booléenne (true ou false) 3 longueur fixe avec 3 chiffres/caractères ..3 longueur variable avec maximum 3 chiffres/caractères enum énumération de valeurs admissibles dttm Date et heure ISO (AAAA-MM-JJThh:mm:ss) Abréviations : CND condition M obligatoire (mandatory en anglais) O optionnel C conditionnel Remarque : Veuillez noter que les noms des paramètres peuvent être en majuscules ou en minuscules.
Appel de l'interface iDEAL
Pour procéder à un paiement avec virement en ligne avec iDEAL, utilisez l'adresse URL ci-dessous :
Remarque : Pour des raisons de sécurité, la plateforme de paiement rejette toutes les requêtes de paiement contenant des erreurs de format. Veuillez par conséquent utiliser le type de données correct pour chaque paramètre.
Le tableau ci-dessous présente les paramètres de la requête de paiement cryptée :
Paramètre | Format | CND | Description |
---|---|---|---|
MerchantID | ans..30 | M | Identifiant du commerçant, attribué par BNP. Ce paramètre doit également être transféré non chiffré. |
TransID | ans..64 | M | ID de la transaction qui doit être unique pour chaque paiement |
RefNr | ans..40 | O | Numéro de référence univoque du commerçant. En cas d'utilisation de l'interface EMS, la longueur est limitée à 15 caractères. Seuls les caractères a-zA-Z0-9,-_ sont autorisés. |
Amount | n..10 | M | Montant indiqué dans la plus petite unité de la devise (par ex. les centimes pour l'euro) Veuillez contacter notre service d'assistance si vous souhaitez capturer des montants inférieurs à 100 (plus petite unité de la devise). |
Currency | a3 | M | Devise, trois caractères DIN / ISO 4217 |
OrderDesc | ans..384 | M | Description des marchandises achetées, des prix unitaires etc. Veuillez noter : les 27 premiers caractères apparaissent sur le relevé de compte du client. Consulter Analytics pour les données complètes. |
MAC | an64 | M | Code d'Authentification de Message Haché (HMAC) avec algorithme SHA-256 |
UserData | ans..1024 | O | Si indiqué lors de la requête, la plateforme de paiement transmet à la boutique le paramètre avec le résultat du paiement |
URLSuccess | ans..256 | M | Adresse URL complète qui appelle la plateforme de paiement en cas de réussite du paiement. L'URL ne peut être appelée que par le port 443. Cette URL ne peut contenir aucun paramètre : pour échanger des valeurs de paramètre entre la plateforme de paiement et la boutique, veuillez utiliser le paramètre UserData. |
URLFailure | ans..256 | M | Adresse URL complète qui appelle la plateforme de paiement en cas d'échec du paiement. L'URL ne peut être appelée que par le port 443. Cette URL ne peut contenir aucun paramètre : pour échanger des valeurs de paramètre entre la plateforme de paiement et la boutique, veuillez utiliser le paramètre UserData. |
Response | a7 | O | État de la réponse envoyée par la plateforme de paiement à URLSuccess et URLFailure, doit être chiffré. À cette fin, transmettez le paramètre Response=encrypt. |
URLNotify | ans..256 | M | Adresse URL complète appelée par la plateforme de paiement pour communiquer le résultat de paiement à la boutique. L'URL ne peut être appelée que par le port 443. Elle ne peut contenir aucun paramètre : utilisez le paramètre UserData à la place. |
ReqID | ans..32 | O | Pour éviter les paiements en double, saisissez une valeur alphanumérique qui identifie votre transaction et ne peut être attribuée qu’une seule fois. Si la transaction est à nouveau soumise avec le paramètre ReqID identique, la plateforme de paiement n’exécute pas le paiement et se contente de retourner le statut de la transaction d’origine. Attention : Plateforme de paiement doit afficher un statut de transaction finalisée pour la première action initiale. Les introductions avec un ReqID identique pour un statut ouvert sont traitées à intervalles réguliers. |
BIC | ans..11 | O | Code d'identification de la banque |
Language | a2 | O | |
Plain | ans..50 | O | Valeur à définir par le commerçant pour retourner des informations non chiffrées, par ex. le MID |
Custom | ans..1024 | O | Le commerçant peut introduire plusieurs valeurs séparées par un | qui sont ensuite retournées non chiffrées et séparées par un &. Custom=session=123|id=456 devient dans la réponse Session=123&id=456 |
Paramètres pour virements en ligne avec iDEAL
Le tableau suivant présente les paramètres de réponse que la plateforme de paiement transmet à URLSuccess ou URLFailure et URLNotify. Si vous avez spécifié le paramètre Response=encrypt, les paramètres suivants seront cryptés avec Blowfish et transmis à votre système :
Paramètre | Format | CND | Description | |
---|---|---|---|---|
MID | ans..30 | M | Identifiant du commerçant, attribué par BNP | |
PayID | an32 | M | ID attribuée au paiement par la plateforme de paiement, par ex. pour le référencement au sein des fichiers batch. | |
XID | an32 | M | Identifiant attribué par la plateforme de paiement pour toutes les différentes opérations (autorisation, capture, remboursement) d'une transaction. | |
TransID | ans..64 | M | Numéro de transaction du commerçant | |
Status | a..50 | M | OK (URLSuccess) ou FAILED (URLFailure) | |
Description | ans..1024 | M | Détails supplémentaires en cas d'échec du paiement. Veuillez ne pas utiliser le paramètre Description mais bien le paramètre Code pour une analyse de l'état de la transaction ! | |
Code | n8 | M | Code d'erreur conformément au fichier Excel des codes de réponse de la plateforme de paiement (partie du logiciel Client) | |
RefNr | ans..40 | O | Numéro de référence univoque du commerçant. Seuls les caractères a-zA-Z0-9,-_ sont autorisés. | |
UserData | ans..1024 | O | Si indiqué lors de la requête, la plateforme de paiement transmet à la boutique le paramètre avec le résultat du paiement | |
MAC | an64 | M | Code d'Authentification de Message Haché (HMAC) avec algorithme SHA-256 | |
AccBank | ans..20 | C | Identification de l'établissement financier du titulaire de compte (uniquement si Status=OK) | |
AccOwner | a..50 | C | Nom du titulaire de compte (uniquement si Status=OK) | |
IBAN | ans..34 | C | IBAN du titulaire de compte (uniquement si Status=OK) | |
BIC | ans..11 | C | BIC du titulaire de compte (uniquement si Status=OK) | |
PaymentPurpose | ans..26 | O | Motif du paiement | |
PaymentGuarantee | a.12 | O | NONE = pas de garantie de paiement, VALIDATED = compte client valide mais pas de garantie de paiement, FULL = garantie de paiement Remarque : ce paramètre n'est retourné que si l'état est = OK. | |
ErrorText | ans..128 | O | Message d'erreur PPRO détaillé. Remarque : n'est retourné que si l'état = FAILED. Utilisation possible uniquement après concertation avec le Support. | |
TransactionID | an..20 | O | Numéro de transaction unique pour PPRO | |
Plain | ans..50 | O | Valeur à définir par le commerçant pour retourner des informations non chiffrées, par ex. le MID | |
Custom | ans..1024 | O | Le commerçant peut introduire plusieurs valeurs séparées par un | qui sont ensuite retournées non chiffrées et séparées par un &. Custom=session=123|id=456 devient dans la réponse Session=123&id=456 |
Paramètres de retour pour URLSuccess, URLFailure et URLNotify avec iDEAL
Consultation des banques iDEAL enregistrées
La plateforme de paiement offre aux commerçants la possibilité de consulter quelles banques sont enregistrées pour le commerçant avant le processus de paiement. Étant donné que la liste de banques configurée change rarement, il n'est pas nécessaire de la consulter pour chaque virement bancaire. Utilisez l'adresse URL ci-dessous pour procéder à cette vérification :
Le tableau ci-dessous présente les paramètres de la requête de paiement cryptée : Veuillez noter que pour toutes les requêtes de la plateforme de paiement, les paramètres Merchant-ID, Len et Data doivent toujours être transmis :
Paramètre | Format | CND | Description |
---|---|---|---|
MerchantID | ans..30 | M | Identifiant du commerçant, attribué par BNP. Ce paramètre doit également être transféré non chiffré. |
Paramètres de vérification des banques iDEAL enregistrées
Veuillez transférer l'ID du commerçant aussi bien dans la chaîne de caractères non chiffrée que dans la chaîne chiffrée.
Le tableau ci-dessous présente les paramètres de résultat que la plateforme de paiement envoie comme réponse :
Paramètre | Format | CND | Description |
---|---|---|---|
MerchantID | ans..30 | M | Identifiant du commerçant, attribué par BNP. Ce paramètre doit également être transféré non chiffré. |
IdealIssuerList | ans.. | M | Cette liste IdealIssuerList contient toutes les banques enregistrées pour le commerçant au moment de la requête, au format IssuerID,Name,Country|… IssuerID = BIC de la banque Name = nom de la banque Country = nom du pays de la banque (max. 128 caractères) |
Paramètres de résultat de la vérification des banques iDEAL enregistrées
Remboursement avec référence
Les remboursements sont possibles via une connexion de type serveur à serveur. La plate-forme de paiement n'autorise que les remboursements pour iDEAL qui font référence à une capture de transaction préalablement effectuée via la plateforme de paiement. Le montant du remboursement est limité au montant de la capture précédente.
Veuillez noter que, dans le cas d’EMS, une seule demande de remboursement peut être traitée. L’envoi de plusieurs remboursements n’est pas autorisé.
Pour exécuter un remboursement pour iDEAL, veuillez utiliser l'adresse URL suivante :
Remarque : Veuillez noter que les remboursements pour iDEAL ne peuvent être traitées que si vous utilisez les partenaires de traitement EMS ou EVO Payments. Aucun remboursement n'est possible via la plateforme de paiement avec une connexion directe à la banque néerlandaise respective.
Remarque : Pour des raisons de sécurité, la plateforme de paiement rejette toutes les requêtes de paiement contenant des erreurs de format. Veuillez par conséquent utiliser le type de données correct pour chaque paramètre.
Le tableau ci-dessous présente les paramètres de la requête de paiement cryptée :
Paramètre | Format | CND | Description |
---|---|---|---|
MerchantID | ans..30 | M | Identifiant du commerçant, attribué par BNP. Ce paramètre doit également être transféré non chiffré. |
PayID | an32 | M | ID attribuée par la plateforme de paiement pour le paiement à rembourser |
TransID | ans..64 | M | ID de la transaction qui doit être unique pour chaque paiement |
MAC | an64 | M | Code d'Authentification de Message Haché (HMAC) avec algorithme SHA-256 |
Amount | n..10 | M | Montant indiqué dans la plus petite unité de la devise (par ex. les centimes pour l'euro) Veuillez contacter notre service d'assistance si vous souhaitez capturer des montants inférieurs à 100 (plus petite unité de la devise). |
Currency | a..3 | M | Code pour la devise, trois caractères DIN / ISO 4217 |
OrderDesc | ans..768 | O | Description des marchandises remboursées, prix unitaires, commentaires du commerçant etc. |
ReqID | ans..32 | O | Pour éviter les paiements en double, saisissez une valeur alphanumérique qui identifie votre transaction et ne peut être attribuée qu’une seule fois. Si la transaction est à nouveau soumise avec le paramètre ReqID identique, la plateforme de paiement n’exécute pas le paiement et se contente de retourner le statut de la transaction d’origine. Attention : Plateforme de paiement doit afficher un statut de transaction finalisée pour la première action initiale. Les introductions avec un ReqID identique pour un statut ouvert sont traitées à intervalles réguliers. |
Paramètres de requête pour les remboursements des paiements iDEAL
Le tableau ci-dessous présente les paramètres de réponse de la plateforme de paiement :
Paramètre | Format | CND | Description |
---|---|---|---|
MID | ans..30 | M | Identifiant du commerçant, attribué par BNP |
PayID | an32 | M | ID attribuée au paiement par la plateforme de paiement, par ex. pour le référencement au sein des fichiers batch. |
XID | an32 | M | Identifiant attribué par la plateforme de paiement pour toutes les différentes opérations (autorisation, capture, remboursement) d'une transaction. |
TransID | ans..64 | M | Numéro de transaction du commerçant |
Status | a..30 | M | OK ou FAILED |
Description | ans..1024 | M | Détails supplémentaires en cas d'échec du paiement. Veuillez ne pas utiliser le paramètre Description mais bien le paramètre Code pour une analyse de l'état de la transaction ! |
Code | n8 | M | Code d'erreur conformément au fichier Excel des codes de réponse de la plateforme de paiement (partie du logiciel Client) |
Paramètres de résultat pour les remboursement des paiements iDEAL
Traitement Batch via l'interface
Pour de plus amples informations sur l'utilisation des fichiers Batch et sur leur structure, voir le manuel Batch Manager.
Cette section présente les paramètres qui doivent être transmis dans l'ensemble de données (Record) pour l'exécution d'un crédit iDEAL, ainsi que les informations pouvant être contenues dans le fichier de réponse sur l'état du paiement.
Le tableau ci-dessous donne une vue d'ensemble de toutes les versions batch possibles pour une action spécifique ainsi que leurs particularités :
Action | Version | Description |
---|---|---|
Note de crédit | 1.0 / 2.0 | Version standard sans retour de paramètre Code |
| 1.x / 2.x | Avec RefNr (valide pour toutes les versions autres que 1.0) |
Description des versions batch possibles
La structure devant être introduite pour un paiement iDEAL au sein d'un fichier Batch est comme suit :
HEAD,<MerchantID>,<Date>,<Version> IDEAL,Credit,<PayID>,<TransID>,(<RefNr>),<Amount>,<Currency> FOOT,<CountRecords>,<SumAmount> |
Exemple de Master MID Funktion:
HEAD,[Master]MerchantID,Date,2.x Type,Action,[Slave]MID,Amount,Currency,TransID,Data (depends on Action) FOOT,CountRecords,SumAmount |
Le tableau ci-dessous présente les différents champs et valeurs utilisés dans l'ensemble de données (record) au sein du fichier batch :
Paramètre | Format | CND | Description |
---|---|---|---|
Type | a..11 | M | HEAD pour l'en-tête, FOOT pour le pied de page, IDEAL pour iDEAL |
Action | a..20 | M | Le paramètre Action définit le type de transaction : Note de crédit |
Amount | n..10 | M | Montant indiqué dans la plus petite unité de la devise (par ex. les centimes pour l'euro) Veuillez contacter notre service d'assistance si vous souhaitez capturer des montants inférieurs à 100 (plus petite unité de la devise). |
Currency | a3 | M | Code pour la devise, trois caractères DIN / ISO 4217 |
TransID | ans..64 | M | ID de la transaction qui doit être unique pour chaque paiement |
RefNr | ans..40 | O | Numéro de référence univoque du commerçant. En cas d'utilisation de l'interface EMS, la longueur est limitée à 15 caractères. Seuls les caractères a-zA-Z0-9,-_ sont autorisés. |
PayID | an32 | M | ID pour cette transaction attribuée par la plateforme de paiement |
Description des champs au sein de l'enregistrement pour les fichiers Batch
La section Record dans le fichier de réponse pour les transactions Batch se présente comme suit :
HEAD,<MerchantID>,<Date>,<Version> IDEAL,Credit,<Amount>,<Currency>,<TransID>(<RefNr>),<PayID>,<Status>,<Code> FOOT,<CountRecords>,<SumAmount> |
Le tableau ci-dessous présente les paramètres de réponse que le Batch Manager sauvegarde dans la section Record pour chaque transaction (les paramètres par défaut non détaillés ici tels que <TransID> ou <RefNR>, ainsi que les paramètres de la requête sont retournés inchangés et correspondent à l'appel tel que spécifié) :
Paramètre | Format | CND | Description |
---|---|---|---|
Action | a..20 | M | Le paramètre Action définit le type de transaction : Note de crédit |
PayID | an32 | M | ID pour cette transaction attribuée par la plateforme de paiement |
Status | a..50 | M | OK ou FAILED |
Code | n8 | M | Code d'erreur conformément au fichier Excel des codes de réponse de la plateforme de paiement (partie du logiciel Client) |
Description des paramètres de résultat au sein de l'enregistrement pour les fichiers Batch