Introduction
Mercanet est une solution de paiement de commerce électronique multicanale sécurisée conforme à la norme PCI DSS. Elle vous permet d’accepter et de gérer des transactions de paiement en prenant en compte les règles métiers liées à votre activité (paiement à la livraison, paiement différé, paiement récurrent, paiement en plusieurs fois, …).
L’objectif du présent document est d’expliquer la mise en œuvre de la solution jusqu’au démarrage en production.
À qui s'adresse ce document
Ce document s'adresse aux commerçants qui souhaitent souscrire à l'offre Mercanet et proposer le paiement intégré à leur application mobile iOS.
C'est un guide d'implémentation qui s'adresse à votre équipe technique.
Pour avoir une vue d'ensemble de la solution Mercanet, nous vous conseillons de consulter les documents suivants :
Pour avoir une vue d'ensemble du connecteur In-App, nous vous conseillons également de consulter le document :
Prérequis
Une connaissance des standards relatifs aux langages de programmation Mobile pratiqués aujourd'hui est nécessaire pour pouvoir développer une application mobile iOS se connectant au SDK proposé via In-App.
Avant d'implémenter le SDK, il est également nécessaire d'avoir suivi les étapes de mise en place du connecteur In-App (cf. documentation In-App).
Remarque : toutes les portions de code de ce document sont fournies à titre
d’exemple, il convient de les adapter à votre application mobile afin
qu'elles soient pleinement exploitables.
IMPORTANT : le SDK In-App doit être utilisé au minimum avec une
version 7.0 du système iOS.
Téléchargement du SDK iOS
Vous pouvez télécharger le SDK iOS via ce lien.
Les signatures du SDK sont présentées ci dessous.
| Type | Signature |
|---|---|
| MD5 | 850d261af9e54213465fff672953a5a6 |
| SHA256 | 6fc9ac3c4d402e2e86dd8ede4653e0793a112987e4327671b9f7bf73b3f49bda |
| SHA512 | 4c738fe022320ef53e767c2daec3570c34f06cbe8e9ded067f627217c7173c749924eaece90726b6cb6f3875b53d8c37d9fa4cba6e1ad53c5133d69f0f467e41 |
Historique du SDK iOS
| Version | Date | Description |
|---|---|---|
| 24.3.0 | Juin 2024 |
Ajout du « Privacy Manifest » requis par Apple pour les apps et les bibliothèques tièrces susceptibles de collecter des données personnelles. |
| 23.1.0 | Janvier 2023 |
Ajout du champs paymentMeanCoBadgingBrandList sur la méthode getWalletData |
| 22.5.0 | Juillet 2022 |
Ajout du champs issuingCountryCode sur l'objet INAPPCardData |
| 21.5.0 | Juillet 2021 |
Ajout du package arm64 dans XCFramework |
| 21.4.0 | Juin 2021 |
Ajout des champs paymentMeanBrand et paymentMeanBrandSelectionStatus sur les méthodes walletOrderWithPaymentMeanId, walletCheckEnrollmentWithPaymentMeanId et addCardWithCardNumber |
| 21.3.2 | Avril 2021 |
Ajout de la méthode generatePaymentTokenWithCardNumber GDPR: Suppression du UUID dans le deviceContext |
| 21.2.0 | Février 2021 |
Remplacement du format de paymentMeanId de NSString vers NSInteger Ajout du packaging XCFramework Correctif sur le packaging Release-universal (ajout des architectures i386 et x86_64) |
Démarrer l'implémentation du SDK en 3 étapes
Étape 1 : importer le SDK dans un projet iOS
Le SDK contient trois dossiers :
- Release-iphoneos : ce dossier sert à compiler un projet à destination d'un iphone physique. Il est utile pour les tests réels avant la mise en production.
- Release-iphonesimulator : ce dossier sert à compiler un projet à destination d'un simulateur iOS.
- Release-universal : ce dossier regroupe les deux architectures mentionnées ci-dessus.
Le SDK est publié sous la forme d'un fichier framework.
Il suffit de glisser-déposer le fichier InAppSdk.framework dans votre projet pour l’importer.
Lier le binaire aux bibliothèques
Dans votre projet, vous devez lier le fichier SDK.
Pour ce faire, dans XCode :
- cliquez sur votre projet ;
- cliquez sur votrre application cible,
- cliquez sur l'onglet Build phases,
- développez la rubrique Link Binary With Libraries,
- cliquez sur le symbole « + »,
- sélectionnez le fichier InAppSdk.framework.
Cela est parfois fait automatiquement.
Lier des binaires intégrés
Dans votre projet commerçant, vous devez lier les binaires intégrés.
Pour ce faire dans XCode :
- cliquez sur votre projet ;
- cliquez sur votre application cible,
- cliquez sur l'onglet General,
- dans la section Embedded Binaries :
- cliquez sur le symbole « + »,
- sélectionnez le fichier InAppSdk.framework.
Vous devriez avoir la configuration suivante :
Étape 2 : utiliser les fonctions disponibles
Toutes les méthodes nécessaires se trouvent dans la classe publique InAppSdk.
Conseil : Sur la version iOS du SDK, l’asynchronisme est géré au
sein du SDK lui-même. Il n’y a donc pas de nécessité de faire l’appel à
ces fonctions de façon asynchrone, la réponse est reçue à l’aide d’un
handler à la fin de l’appel.
Conseil : Avant d'utiliser une fonction, vérifiez que vous avez
bien les droits pour utiliser cette fonction sur votre boutique en
contactant l'assistance technique Mercanet.
Fonctions de paiement
Fonction cardOrder
Cette fonction vous permet
d'effectuer un paiement carte avec les informations bancaires d'un
client.
Elle doit être appelée après une requête
d'initialisation In-App orderInitialize depuis
votre serveur avec un
sdkOperationName=CARDORDER.Format de la requête cardOrder
| Paramètres | Présence | Type | Commentaires | |
|---|---|---|---|---|
| cardCSCValue | Facultatif | NSString | Cryptogramme visuel | |
| cardExpiryDate | Obligatoire | NSString | Date d'expiration | |
| cardNumber | Facultatif | NSString | Numéro de carte | |
| paymentMeanBrand | Facultatif | NSString | Moyen de paiement sélectionné | |
| paymentMeanBrandSelectionStatus | Facultatif | NSString | Statut de sélection du moyen de paiement | |
| publicKeyValue | Obligatoire | NSString | Valeur cryptée de la clé publique | Récupérés à partir de la requête d'initialisation |
| redirectionData | Obligatoire | NSString | Token unique contenant le contexte de la transaction | |
| redirectionUrl | Obligatoire | NSString | Adresse d'URL fournie en sortie de l'orderInitialize | |
| redirectionVersion | Obligatoire | NSString | Version de l'interface | |
| handler | Obligatoire | void (^)(INAPPOrderResponse * response) | Handler alimenté à la fin de l'appel | |
Format de la réponse cardOrder (objet INAPPOrderResponse)
| Nom du champ | Format | Commentaire |
|---|---|---|
| acquirerResponseCode | NSString | Code réponse acquéreur |
| amount | NSString | Montant de la transaction |
| authentExemptionReasonList | Liste de NSString | Exemption retenue par l'émetteur |
| authorisationId | NSString | Identifiant d'autorisation |
| authorisationTypeLabel | NSString | Intitulé du type de la demande d'autorisation |
| authorMessageReference | NSString | Identifiant partagé avec l'acquéreur lors du traitement de la demande d'autorisation |
| captureDay | NSString | Délai de capture |
| captureMode | NSString | Mode de capture |
| cardData | INAPPCardData | Contient les informations relative à la carte (Voir la partie Containers) |
| cardExpiryDate | NSString (yyyyMM) | Date d'expiration de la carte |
| currencyCode | NSString | Code de la devise |
| customerId | NSString | Identifiant client |
| errorFieldName | NSString | Nom du champ à l'origine de l'erreur |
| guaranteeIndicator | NSString | Niveau de garantie de paiement |
| guaranteeLimitDateTime | NSString | Date limite du niveau de garantie de paiement |
| holderAuthentMethod | NSString | Nom de la méthode appliquée pour identifier le porteur du moyen de paiement |
| holderAuthentProgram | NSString | Programme d'authentification |
| holderAuthentRelegationCode | NSString | Code indiquant si l’émetteur accepte ou refuse le transfert de responsabilité |
| holderAuthentResponseCode | NSString | Code réponse du processus d'authentification porteur |
| holderAuthentStatus | NSString | Résultat du processus d'authentification porteur |
| holderAuthentType | NSString | Type d'authentification du porteur appliqué par l'émetteur de la carte. Champ valorisé en 3-D Secure v2. |
| inAppResponseCode | NSString | Code réponse du serveur Mercanet |
| invoiceReference | NSString | Référence de la facture |
| issuerWalletInformation | NSString | Informations données par le fournisseur de portefeuilles virtuels à destination du commerçant en réponse à la demande de création de la transaction |
| maskedPan | NSString | Numéro de carte masqué |
| merchantId | NSString | Identifiant du commerçant |
| merchantWalletId | NSString | Identifiant du portefeuille virtuel du client |
| orderChannel | NSString | Canal de commande |
| orderId | NSString | Identifiant de commande |
| panEntryMode | NSString | Mode de lecture du numéro de carte |
| paymentMeanBrand | NSString | Moyen de paiement sélectionné |
| paymentMeanBrandSelectionStatus | NSString | Statut du choix de la marque de la carte |
| paymentMeanType | NSString | Type du moyen de paiement (carte, virement, prélèvement, …). Il regroupe un ensemble de paymentMeanBrand. |
| paymentPattern | NSString | Mode de paiement (simple, récurrent, etc.) |
| returnContext | NSString | Valeur transférée à la requête de paiement |
| s10TransactionReference | INAPPS10TransactionReference | Contient les informations sur l'identification de la transaction, compatibles avec Mercanet 1.0 (Voir la partie Containers) |
| statementReference | NSString | Référence fournie par le commerçant qui est envoyée dans le flux de remise en paiement. Cette référence apparait sur les relevés de compte du porteur. |
| transactionDateTime | NSString | Date et heure du traitement de la transaction par le serveur Mercanet(exprimé dans le time zone du serveur Mercanet) |
| transactionOrigin | NSString | Origine d’une transaction (ex : nom du programme), valorisée par le commerçant |
| transactionPlatform | NSString | Plateforme d'exécution de la transaction |
| transactionReference | NSString | Identifiant de la transaction |
| walletType | NSString | Type de portefeuille virtuel |
Fonction walletOrder
Cette fonction est utilisée
pour effectuer un paiement via wallet.
Elle est appelée après la
requête d’initialisation In-App orderInitialize
sur votre serveur avec
sdkOperationName=WALLETORDER.Format de la requête walletOrder
| Paramètres | Présence | Type | Commentaires | |
|---|---|---|---|---|
| cardCSCValue | Facultatif | NSString | Cryptogramme visuel | |
| paymentMeanBrand | Facultatif | NSString | Moyen de paiement sélectionné. Si la valeur n'est pas fournie, la valeur utilisée est celle précédemment enregistrée dans le wallet. | |
| paymentMeanBrandSelectionStatus | Facultatif | NSString | Statut de sélection du moyen de paiement. Si la valeur n'est pas fournie, la valeur utilisée est celle précédemment enregistrée dans le wallet | |
| paymentMeanId | Obligatoire | NSString | Identifiant de la carte sélectionnée | |
| publicKeyValue | Obligatoire | NSString | Valeur cryptée de la clé publique | Récupérés à partir de la requête d'initialisation |
| redirectionData | Obligatoire | NSString | Token unique contenant le contexte de la transaction | |
| redirectionUrl | Obligatoire | NSString | Adresse d'URL fournie en sortie de l'orderInitialize | |
| redirectionVersion | Obligatoire | NSString | Version de l’interface | |
| handler | Obligatoire | void (^)(INAPPOrderResponse * response) | Handler alimenté à la fin de l'appel | |
Format de la réponse walletOrder (objet INAPPOrderResponse)
| Nom du champ | Format | Commentaire |
|---|---|---|
| acquirerResponseCode | NSString | Code réponse acquéreur |
| amount | NSString | Montant de la transaction |
| authentExemptionReasonList | Liste de NSString | Exemption retenue par l'émetteur |
| authorisationId | NSString | Identifiant d'autorisation |
| authorisationTypeLabel | NSString | Intitulé du type de la demande d'autorisation |
| authorMessageReference | NSString | Identifiant partagé avec l'acquéreur lors du traitement de la demande d'autorisation |
| captureDay | NSString | Délai de capture |
| captureMode | NSString | Mode de capture |
| cardData | INAPPCardData | Contient les informations relative à la carte (Voir la partie Containers) |
| cardExpiryDate | NSString (yyyyMM) | Date d'expiration de la carte |
| currencyCode | NSString | Code de la devise |
| customerId | NSString | Identifiant client |
| errorFieldName | NSString | Nom du champ à l'origine de l'erreur |
| guaranteeIndicator | NSString | Niveau de garantie de paiement |
| guaranteeLimitDateTime | NSString | Date limite du niveau de garantie de paiement |
| holderAuthentMethod | NSString | Nom de la méthode appliquée pour identifier le porteur du moyen de paiement |
| holderAuthentProgram | NSString | Programme d'authentification |
| holderAuthentRelegationCode | NSString | Code indiquant si l’émetteur accepte ou refuse le transfert de responsabilité |
| holderAuthentResponseCode | NSString | Code réponse du processus d'authentification porteur |
| holderAuthentStatus | NSString | Résultat du processus d'authentification porteur |
| holderAuthentType | NSString | Type d'authentification du porteur appliqué par l'émetteur de la carte. Champ valorisé en 3-D Secure v2. |
| inAppResponseCode | NSString | Code réponse du serveur Mercanet |
| invoiceReference | NSString | Référence de la facture |
| issuerWalletInformation | NSString | Informations données par le fournisseur de portefeuilles virtuels à destination du commerçant en réponse à la demande de création de la transaction |
| maskedPan | NSString | Numéro de carte masqué |
| merchantId | NSString | Identifiant du commerçant |
| merchantWalletId | NSString | Identifiant du portefeuille virtuel du client |
| orderChannel | NSString | Canal de commande |
| orderId | NSString | Identifiant de commande |
| panEntryMode | NSString | Mode de lecture du numéro de carte |
| paymentMeanBrand | NSString | Moyen de paiement sélectionné |
| paymentMeanBrandSelectionStatus | NSString | Statut du choix de la marque de la carte |
| paymentMeanType | NSString | Type du moyen de paiement (carte, virement, prélèvement, …). Il regroupe un ensemble de paymentMeanBrand. |
| paymentPattern | NSString | Mode de paiement (simple, récurrent, etc.) |
| returnContext | NSString | Valeur transférée à la requête de paiement |
| s10TransactionReference | INAPPS10TransactionReference | Contient les informations sur l'identification de la transaction, compatibles avec Mercanet 1.0 (Voir la partie Containers) |
| statementReference | NSString | Référence fournie par le commerçant qui est envoyée dans le flux de remise en paiement. Cette référence apparait sur les relevés de compte du porteur. |
| transactionDateTime | NSString | Date et heure du traitement de la transaction par le serveur Mercanet(exprimé dans le time zone du serveur Mercanet) |
| transactionOrigin | NSString | Origine d’une transaction (ex : nom du programme), valorisée par le commerçant |
| transactionPlatform | NSString | Plateforme d'exécution de la transaction |
| transactionReference | NSString | Identifiant de la transaction |
| walletType | NSString | Type de portefeuille virtuel |
Fonction paymentProviderOrder
Cette fonction est
utilisée pour obtenir l'URL Intent BCMC à appeler pour vous permettre
d'effectuer un paiement BCMC.
Elle est appelée après la requête
d’initialisation In-App orderInitialize sur
votre serveur avec
sdkOperationName=PAYMENTPROVIDERORDER
et paymentMeanBrand=BCMCMOBILE.Format de la requête paymentProviderOrder
| Paramètres | Présence | Type | Commentaires | |
|---|---|---|---|---|
| publicKeyValue | Obligatoire | NSString | Valeur cryptée de la clé publique | Récupérés à partir de la requête d'initialisation |
| redirectionData | Obligatoire | NSString | Token unique contenant le contexte de la transaction | |
| redirectionUrl | Obligatoire | NSString | Adresse d'URL fournie en sortie de l'orderInitialize | |
| redirectionVersion | Obligatoire | NSString | Version de l’interface | |
| handler | Obligatoire | void (^)(INAPPPaymentProviderResponse * response) | Handler alimenté à la fin de l'appel | |
Format de la réponse paymentProviderOrder (objet INAPPPaymentProviderResponse)
| Nom du champ | Format | Commentaire |
|---|---|---|
| errorFieldName | NSString | Nom du champ à l'origine de l'erreur |
| inAppResponseCode | NSString | Code réponse de Mercanet |
| outerRedirectionUrl | NSString | URL Intent destinée à réveiller l'application BCMC |
| redirectionUrl | NSString | URL de redirection pour l'appel suivant |
| transactionContextData | NSString | Contexte de la transaction |
| transactionContextVersion | NSString | Version du contexte de la transaction |
Fonction getTransactionData
Cette fonction est
utilisée pour vérifier le statut de la transaction BCMC après l'appel de
l'application BCMC.
Elle est appelée après un appel à
paymentProviderOrder, lorsque l'application BCMC rappelle
l'application commerçant.
Format de la requête getTransactionData
| Paramètres | Présence | Type | Commentaires | |
|---|---|---|---|---|
| transactionContextData | Obligatoire | NSString | Contexte de la transaction | Récupérés à partir de la requête au paymentProviderOrder |
| transactionContextVersion | Obligatoire | NSString | Version du contexte de la transaction | |
| redirectionUrl | Obligatoire | NSString | URL de redirection pour l'appel suivant | |
| handler | Obligatoire | void (^)(INAPPGetTransactionDataResponse * response) | Handler alimenté à la fin de l'appel | |
Format de la réponse getTransactionData (objet INAPPGetTransactionDataResponse)
| Nom du champ | Format | Commentaire |
|---|---|---|
| acquirerResponseCode | NSString | Code réponse acquéreur |
| authentExemptionReasonList | Liste de NSString | Exemption retenue par l'émetteur |
| authorisationId | NSString | Identifiant d'autorisation |
| authorisationTypeLabel | NSString | Intitulé du type de la demande d'autorisation |
| authorMessageReference | NSString | Identifiant partagé avec l'acquéreur lors du traitement de la demande d'autorisation |
| captureLimitDate | NSString | Délai de capture |
| captureMode | NSString | Mode de capture |
| cardData | INAPPCardData | Contient les informations relative à la carte (Voir la partie Containers) |
| cardExpiryDate | NSString (yyyyMM) | Date d'expiration de la carte |
| currencyCode | NSString | Code de la devise |
| customerId | NSString | Identifiant client |
| errorFieldName | NSString | Nom du champ à l'origine de l'erreur |
| guaranteeIndicator | NSString | Niveau de garantie de paiement |
| guaranteeLimitDateTime | NSString | Date limite du niveau de garantie de paiement |
| holderAuthentMethod | NSString | Nom de la méthode appliquée pour identifier le porteur du moyen de paiement |
| holderAuthentProgram | NSString | Programme d'authentification |
| holderAuthentRelegationCode | NSString | Code indiquant si l’émetteur accepte ou refuse le transfert de responsabilité |
| holderAuthentResponseCode | NSString | Code réponse du processus d'authentification porteur |
| holderAuthentStatus | NSString | Résultat du processus d'authentification porteur |
| holderAuthentType | NSString | Type d'authentification du porteur appliqué par l'émetteur de la carte. Champ valorisé en 3-D Secure v2. |
| inAppResponseCode | NSString | Code réponse du serveur Mercanet |
| invoiceReference | NSString | Référence de la facture |
| issuerWalletInformation | NSString | Informations données par le fournisseur de portefeuilles virtuels à destination du commerçant en réponse à la demande de création de la transaction |
| maskedPan | NSString | Numéro de carte masqué |
| merchantId | NSString | Identifiant du commerçant |
| merchantWalletId | NSString | Identifiant du portefeuille virtuel du client |
| orderChannel | NSString | Canal de commande |
| orderId | NSString | Identifiant de commande |
| originAmount | NSString | Montant d'origine de la transaction |
| panEntryMode | NSString | Mode de lecture du numéro de carte |
| paymentMeanBrand | NSString | Moyen de paiement sélectionné |
| paymentMeanBrandSelectionStatus | NSString | Statut du choix de la marque de la carte |
| paymentMeanType | NSString | Type du moyen de paiement (carte, virement, prélèvement, …). Il regroupe un ensemble de paymentMeanBrand. |
| paymentPattern | NSString | Mode de paiement (simple, récurrent, etc.) |
| returnContext | NSString | Valeur transférée à la requête de paiement |
| s10TransactionReference | INAPPS10TransactionReference | Contient les informations sur l'identification de la transaction, compatibles avec Mercanet 1.0 (Voir la partie Containers) |
| statementReference | NSString | Référence fournie par le commerçant qui est envoyée dans le flux de remise en paiement. Cette référence apparait sur les relevés de compte du porteur. |
| transactionDateTime | NSString | Date et heure du traitement de la transaction par le serveur Mercanet(exprimé dans le time zone du serveur Mercanet) |
| transactionOrigin | NSString | Origine d’une transaction (ex : nom du programme), valorisée par le commerçant |
| transactionPlatform | NSString | Plateforme d'exécution de la transaction |
| transactionReference | NSString | Identifiant de la transaction |
| transactionStatus | NSString | Statut de la transaction |
| walletType | NSString | Type de portefeuille virtuel |
Fonction cardCheckEnrollment
Cette fonction est
utilisée pour préparer un paiement 3-D Secure et obtenir le message
paReq (Payer Authentication Request) ainsi que l'URL de l'ACS
(Access Control Server) à appeler.
Elle est appelée après la
requête d’initialisation In-App orderInitialize
sur votre serveur avec
sdkOperationName=THREEDSECUREANDORDER.Format de la requête cardCheckEnrollment
| Paramètres | Présence | Type | Commentaires | |
|---|---|---|---|---|
| cardCSCValue | Facultatif | NSString | Cryptogramme visuel | |
| cardExpiryDate | Obligatoire | NSString | Date d'expiration | |
| cardNumber | Facultatif | NSString | Numéro de carte | |
| paymentMeanBrand | Facultatif | NSString | Moyen de paiement sélectionné | |
| paymentMeanBrandSelectionStatus | Facultatif | NSString | Statut de sélection du moyen de paiement | |
| publicKeyValue | Obligatoire | NSString | Valeur cryptée de la clé publique | Récupérés à partir de la requête d'initialisation |
| redirectionData | Obligatoire | NSString | Token unique contenant le contexte de la transaction | |
| redirectionUrl | Obligatoire | NSString | Adresse d'URL fournie en sortie de l'orderInitialize | |
| redirectionVersion | Obligatoire | NSString | Version de l'interface | |
| handler | Obligatoire | void (^)(INAPPCardCheckEnrollmentResponse * response) | Handler alimenté à la fin de l'appel | |
Format de la réponse cardCheckEnrollment (objet INAPPCardCheckEnrollmentResponse)
| Nom du champ | Format | Commentaire |
|---|---|---|
| authentRedirectionUrl | NSString | URL de redirection ACS |
| errorFieldName | NSString | Nom du champ à l'origine de l'erreur |
| maskedPan | NSString | Numéro de PAN masqué |
| paReqMessage | NSString | Message PaReq utilisé pour l'authentification ACS |
| redirectionStatusCode | NSString | Code réponse de Mercanet |
| redirectionUrl | NSString | URL de redirection pour l'appel suivant |
| tokenPan | NSString | Identifiant unique d'un PAN |
| transactionContextData | NSString | Contexte de la transaction |
| transactionContextVersion | NSString | Version du contexte de la transaction |
En fonction de la réponse, votre application doit rediriger le client vers l'ACS (Voir la partie Formulaire POST vers l'ACS).
Fonction walletCheckEnrollment
Cette fonction est
utilisée pour préparer un paiement 3-D Secure à partir d'une carte
déjà enregistrée dans le wallet Mercanet. Elle permet
d'obtenir le message paReq (Payer Authentication Request) ainsi que
l'URL de l'ACS (Access Control Server) à appeler.
Elle est
appelée après la requête d’initialisation In-App
orderInitialize sur votre serveur avec
sdkOperationName=THREEDSECUREANDWALLETORDER.Format de la requête walletCheckEnrollment
| Paramètres | Présence | Type | Commentaires | |
|---|---|---|---|---|
| cardCSCValue | Facultatif | NSString | Cryptogramme visuel | |
| paymentMeanBrand | Facultatif | NSString | Moyen de paiement sélectionné. Si la valeur n'est pas fournie, la valeur utilisée est celle précédemment enregistrée dans le wallet. | |
| paymentMeanBrandSelectionStatus | Facultatif | NSString | Statut de sélection du moyen de paiement. Si la valeur n'est pas fournie, la valeur utilisée est celle précédemment enregistrée dans le wallet | |
| paymentMeanId | Obligatoire | NSString | Identifiant de la carte sélectionnée | |
| publicKeyValue | Obligatoire | NSString | Valeur cryptée de la clé publique | Récupérés à partir de la requête d'initialisation |
| redirectionData | Obligatoire | NSString | Token unique contenant le contexte de la transaction | |
| redirectionUrl | Obligatoire | NSString | Adresse d'URL fournie en sortie de l'orderInitialize | |
| redirectionVersion | Obligatoire | NSString | Version de l’interface | |
| handler | Obligatoire | void (^)(INAPPWalletCheckEnrollmentResponse * response) | Handler alimenté à la fin de l'appel | |
Format de la réponse walletCheckEnrollment (objet INAPPWalletCheckEnrollmentResponse)
| Nom du champ | Format | Commentaire |
|---|---|---|
| authentRedirectionUrl | NSString | URL de redirection ACS |
| errorFieldName | NSString | Nom du champ à l'origine de l'erreur |
| maskedPan | NSString | Numéro de PAN masqué |
| paReqMessage | NSString | Message PaReq utilisé pour l'authentification ACS |
| paymentMeanBrand | NSString | Marque de la carte |
| paymentMeanBrandSelectionStatus | NSString | Statut de sélection de la marque de la carte |
| redirectionStatusCode | NSString | Code réponse de Mercanet |
| redirectionUrl | NSString | URL de redirection pour l'appel suivant |
| tokenPan | NSString | Identifiant unique d'un PAN |
| transactionContextData | NSString | Contexte de la transaction |
| transactionContextVersion | NSString | Version du contexte de la transaction |
En fonction de la réponse, votre application doit rediriger le client vers l'ACS (Voir la partie Formulaire POST vers l'ACS).
Fonction cardValidateAuthenticationAndOrder
Cette
fonction est utilisée pour valider l'authentification de l'ACS et
effectuer le paiement.
Elle est appelée après un appel à
cardCheckEnrollment ou walletCheckEnrollment, lorsque l'ACS
renvoie le message PaRes. L'algorithme "URL Encode" doit être
appliqué au message PaRes avant que celui-ci ne soit fourni au
SDK.
Format de la requête cardValidateAuthenticationAndOrder
| Paramètres | Présence | Type | Commentaires | |
|---|---|---|---|---|
| paResMessage | Obligatoire | NSString | Réponse d'authentification du payeur. L'algorithme standard "URL Encode" doit être appliqué au champ paResMessage reçu de l'ACS. | |
| transactionContextData | Obligatoire | NSString | Contexte de la transaction | Récupérés à partir de la requête au cardCheckEnrollment ou au walletCheckEnrollment |
| transactionContextVersion | Obligatoire | NSString | Version du contexte de la transaction | |
| redirectionUrl | Obligatoire | NSString | URL pour l'appel suivant | |
| handler | Obligatoire | void (^)(INAPPOrderResponse * response) | Handler alimenté à la fin de l'appel | |
Format de la réponse cardValidateAuthenticationAndOrder (objet INAPPOrderResponse)
| Nom du champ | Format | Commentaire |
|---|---|---|
| acquirerResponseCode | NSString | Code réponse acquéreur |
| amount | NSString | Montant de la transaction |
| authentExemptionReasonList | Liste de NSString | Exemption retenue par l'émetteur |
| authorisationId | NSString | Identifiant d'autorisation |
| authorisationTypeLabel | NSString | Intitulé du type de la demande d'autorisation |
| authorMessageReference | NSString | Identifiant partagé avec l'acquéreur lors du traitement de la demande d'autorisation |
| captureDay | NSString | Délai de capture |
| captureMode | NSString | Mode de capture |
| cardData | INAPPCardData | Contient les informations relative à la carte (Voir la partie Containers) |
| cardExpiryDate | NSString (yyyyMM) | Date d'expiration de la carte |
| currencyCode | NSString | Code de la devise |
| customerId | NSString | Identifiant client |
| errorFieldName | NSString | Nom du champ à l'origine de l'erreur |
| guaranteeIndicator | NSString | Niveau de garantie de paiement |
| guaranteeLimitDateTime | NSString | Date limite du niveau de garantie de paiement |
| holderAuthentMethod | NSString | Nom de la méthode appliquée pour identifier le porteur du moyen de paiement |
| holderAuthentProgram | NSString | Programme d'authentification |
| holderAuthentRelegationCode | NSString | Code indiquant si l’émetteur accepte ou refuse le transfert de responsabilité |
| holderAuthentResponseCode | NSString | Code réponse du processus d'authentification porteur |
| holderAuthentStatus | NSString | Résultat du processus d'authentification porteur |
| holderAuthentType | NSString | Type d'authentification du porteur appliqué par l'émetteur de la carte. Champ valorisé en 3-D Secure v2. |
| inAppResponseCode | NSString | Code réponse du serveur Mercanet |
| invoiceReference | NSString | Référence de la facture |
| issuerWalletInformation | NSString | Informations données par le fournisseur de portefeuilles virtuels à destination du commerçant en réponse à la demande de création de la transaction |
| maskedPan | NSString | Numéro de carte masqué |
| merchantId | NSString | Identifiant du commerçant |
| merchantWalletId | NSString | Identifiant du portefeuille virtuel du client |
| orderChannel | NSString | Canal de commande |
| orderId | NSString | Identifiant de commande |
| panEntryMode | NSString | Mode de lecture du numéro de carte |
| paymentMeanBrand | NSString | Moyen de paiement sélectionné |
| paymentMeanBrandSelectionStatus | NSString | Statut du choix de la marque de la carte |
| paymentMeanType | NSString | Type du moyen de paiement (carte, virement, prélèvement, …). Il regroupe un ensemble de paymentMeanBrand. |
| paymentPattern | NSString | Mode de paiement (simple, récurrent, etc.) |
| returnContext | NSString | Valeur transférée à la requête de paiement |
| s10TransactionReference | INAPPS10TransactionReference | Contient les informations sur l'identification de la transaction, compatibles avec Mercanet 1.0 (Voir la partie Containers) |
| statementReference | NSString | Référence fournie par le commerçant qui est envoyée dans le flux de remise en paiement. Cette référence apparait sur les relevés de compte du porteur. |
| transactionDateTime | NSString | Date et heure du traitement de la transaction par le serveur Mercanet(exprimé dans le time zone du serveur Mercanet) |
| transactionOrigin | NSString | Origine d’une transaction (ex : nom du programme), valorisée par le commerçant |
| transactionPlatform | NSString | Plateforme d'exécution de la transaction |
| transactionReference | NSString | Identifiant de la transaction |
| walletType | NSString | Type de portefeuille virtuel |
Fonctions de gestion de Wallet
Fonction getWalletData
Cette fonction vous permet
de récupérer le contenu d'un wallet Mercanet.
Elle doit être appelée après une requête
d'initialisation In-App walletInitialize depuis
votre serveur avec un
sdkOperationName=GETWALLETDATA.Format de la requête getWalletData
| Paramètres | Présence | Type | Commentaires | |
|---|---|---|---|---|
| publicKeyValue | Obligatoire | NSString | Valeur cryptée de la clé publique | Récupérés à partir de la requête d'initialisation |
| redirectionData | Obligatoire | NSString | Token unique contenant le contexte de la transaction | |
| redirectionUrl | Obligatoire | NSString | Adresse d'URL fournie en sortie de l'orderInitialize | |
| redirectionVersion | Obligatoire | NSString | Version de l’interface | |
| handler | Obligatoire | void (^)(INAPPGetWalletDataResponse * response) | Handler alimenté à la fin de l'appel | |
Format de la réponse getWalletData (objet INAPPGetWalletDataResponse)
| Nom du champ | Format | Commentaire |
|---|---|---|
| errorFieldName | NSString | Nom du champ à l'origine de l'erreur |
| inAppResponseCode | NSString | Code réponse du serveur Mercanet |
| walletCreationDateTime | NSString | Date de création du wallet |
| walletPaymentMeanData | Liste de INAPPGetWalletDataResponseItem | Liste des cartes sauvegardée dans le wallet (Voir la partie Containers) |
Fonction addCard
Cette fonction vous permet de
stocker une carte dans un wallet Mercanet.
Elle
doit être appelée après une requête d'initialisation In-App walletInitialize depuis votre serveur avec un
sdkOperationName=ADDCARD.Format de la requête addCard
| Paramètres | Présence | Type | Commentaires | |
|---|---|---|---|---|
| cardExpiryDate | Obligatoire | NSString | Date d'expiration de la carte | |
| cardNumber | Obligatoire | NSString | Numéro de la carte | |
| paymentMeanAlias | Obligatoire | NSString | Alias de la carte | |
| paymentMeanBrand | Facultatif | NSString | Marque de la carte | |
| paymentMeanBrandSelectionStatus | Facultatif | NSString | Statut du choix de la marque de la carte | |
| publicKeyValue | Obligatoire | NSString | Valeur cryptée de la clé publique | Récupérés à partir de la requête d'initialisation |
| redirectionData | Obligatoire | NSString | Token unique contenant le contexte de la transaction | |
| redirectionUrl | Obligatoire | NSString | Adresse d'URL fournie en sortie de l'orderInitialize | |
| redirectionVersion | Obligatoire | NSString | Version de l’interface | |
| handler | Obligatoire | void (^)(INAPPAddCardResponse * response) | Handler alimenté à la fin de l'appel | |
Format de la réponse addCard (objet INAPPAddCardResponse)
| Nom du champ | Format | Commentaire |
|---|---|---|
| errorFieldName | NSString | Nom du champ à l'origine de l'erreur |
| inAppResponseCode | NSString | Code réponse du serveur Mercanet |
| paymentMeanId | NSString | Identifiant du moyen de paiement dans le wallet |
| maskedPan | NSString | PAN masqué de la carte |
| walletActionDateTime | NSString | Date d'ajout dans le wallet |
Fonction deletePaymentMean
Cette fonction vous
permet de supprimer une carte d'un wallet Mercanet.
Elle doit être appelée après une requête
d'initialisation In-App walletInitialize depuis
votre serveur avec un
sdkOperationName=DELETEPAYMENTMEAN.Format de la requête deletePaymentMean
| Paramètres | Présence | Type | Commentaires | |
|---|---|---|---|---|
| paymentMeanId | Obligatoire | NSString | Identifiant du moyen de paiement à supprimer | |
| publicKeyValue | Obligatoire | NSString | Valeur cryptée de la clé publique | Récupérés à partir de la requête d'initialisation |
| redirectionData | Obligatoire | NSString | Token unique contenant le contexte de la transaction | |
| redirectionUrl | Obligatoire | NSString | Adresse d'URL fournie en sortie de l'orderInitialize | |
| redirectionVersion | Obligatoire | NSString | Version de l’interface | |
| handler | Obligatoire | void (^)(INAPPDeletePaymentMeanResponse * response) | Handler alimenté à la fin de l'appel | |
Format de la réponse deletePaymentMean (objet INAPPDeletePaymentMeanResponse)
| Nom du champ | Format | Commentaire |
|---|---|---|
| errorFieldName | NSString | Nom du champ à l'origine de l'erreur |
| inAppResponseCode | NSString | Code réponse du serveur Mercanet |
| walletActionDateTime | NSString | Date d'ajout dans le wallet |
Fonction de consultation des données carte
Fonction getCardData
Cette fonction vous permet
de récupérer les informations liées à un PAN ou à un BIN de carte. Elle
vous permettra, par exemple, de pouvoir proposer le choix de la marque à
votre client lors d'un paiement.
Elle doit être appelée après
une requête d'initialisation In-App
paymentMeanInfoInitialize depuis votre serveur avec un
sdkOperationName=GETCARDDATA.Format de la requête getCardData
| Paramètres | Présence | Type | Commentaires | |
|---|---|---|---|---|
| cardIIN | Facultatif | NSString | IIN de la carte | Au moins un de ces champs doit être fourni en requête |
| cardNumber | Facultatif | NSString | Numéro de la carte | |
| publicKeyValue | Obligatoire | NSString | Valeur cryptée de la clé publique | Récupérés à partir de la requête d'initialisation |
| redirectionData | Obligatoire | NSString | Token unique contenant le contexte de la transaction | |
| redirectionUrl | Obligatoire | NSString | Adresse d'URL fournie en sortie de l'orderInitialize | |
| redirectionVersion | Obligatoire | NSString | Version de l’interface | |
| handler | Obligatoire | void (^)(INAPPGetCardDataResponse * response) | Handler alimenté à la fin de l'appel | |
Format de la réponse getCardData (objet INAPPGetCardDataResponse)
| Nom du champ | Format | Commentaire |
|---|---|---|
| cardDataList | Liste de INAPPCardData | Liste de conteneur INAPPCardData contenant les informations de la carte (en cas de carte cobadgée plusieurs occurrences peuvent apparaître - exemple : carte CB/Visa). (Voir la partie Containers) |
| errorFieldName | NSString | Nom du champ à l'origine de l'erreur |
| inAppResponseCode | NSString | Code réponse du serveur Mercanet |
Containers
INAPPCardData
| Nom du champ | Format | Commentaire |
|---|---|---|
| cardBrand | NSString | Marque de la carte |
| cardCorporateIndicator | NSString | Indicateur de carte commerciale |
| cardEffectiveDateIndicator | NSString | Indicateur de date de début de validité de la carte |
| cardProductCode | NSString | Code produit de la carte |
| cardProductName | NSString | Libellé du code produit de la carte |
| cardProductProfile | NSString | Code profil de la carte |
| cardProductUsageLabel | NSString | Libellé du profil de la carte qui est exposé sur le ticket électronique de paiement selon les directives MPADS |
| cardScheme | NSString | Nom du réseau associé à la carte |
| cardSeqNumberIndicator | NSString | Indicateur d'existence d'un numéro de séquence |
| issuerCode | NSString | Code émetteur de la carte |
| issuerCountryCode | NSString | Code pays de l'émetteur de la carte |
| issuerName | NSString | Nom de l'émetteur de la carte |
| issuerRegionCode | NSString | Code région de l'émetteur de la carte |
| issuingCountryCode | NSString | Code pays dans lequel la carte est émise |
| panCheckAlgorithm | NSString | Algorithme de vérification appliqué au PAN |
| panLengthMax | NSString | Taille maximale du PAN |
| panLengthMin | NSString | Taille minimale du PAN |
INAPPS10TransactionReference
| Nom du champ | Format | Commentaire | |
|---|---|---|---|
| s10TransactionId | NSString | Identifiant alternatif de la transaction compatible avec Mercanet 1.0 | Le couple
s10TransactionId/s10TransactionIdDate assure l’unicité de la
transaction 1.0. L’utilisation de ce couple en lieu et
place de la donnée transactionReference dépend de la configuration
du commerçant. |
| s10TransactionIdDate | NSString | Date de la transaction (exprimée dans le time zone du serveur Mercanet) | |
INAPPGetWalletDataResponseItem
| Nom du champ | Format | Commentaire |
|---|---|---|
| maskedPan | NSString | PAN masqué de la carte |
| panExpiryDate | NSString | Date d'expiration de la carte |
| paymentMeanAlias | NSString | Alias de la carte |
| paymentMeanBrand | NSString | Marque de la carte |
| paymentMeanId | NSString | Identifiant du moyen de paiement dans le wallet |
Formulaire POST de redirection
Formulaire POST vers l'ACS
En fonction de la réponse de
vérification d'enrôlement du porteur, votre application doit rediriger
vers l'ACS en appelant la authentRedirectionUrl reçue avec des
paramètres POST :
- PaReq message : retourné par l'appel précédent dans le champ paReqMessage ;
- MD (Merchant Data) : champ comportant des données sur le statut du commerçant qui doivent être retournées à ce dernier. Ce champ doit être utilisé pour récupérer la session sur votre site web ;
- TermUrl : l’URL du commerçant vers laquelle la réponse finale doit être envoyée après authentification de l’utilisateur final (champs de réponse PaRes et MD). Il doit s’agir d’une URL de votre site web vers laquelle l’utilisateur final doit être redirigé.
IMPORTANT : le champ MD doit contenir uniquement
des caractères ASCII compris entre 0x20 et 0x7E ; si d'autres données sont
nécessaires, le champ doit être encodé en Base64. La taille du champ
(après le codage Base64, le cas échéant) est limitée à 1024 octets. Si des
données confidentielles sont incluses (telles que le PAN), elles doivent
être cryptées.
Avec iOS, il est possible d'appeler une fonction dans une UIWebView depuis du code JavaScript. Dès lors, TermUrl peut être une page web du commerçant qui pousse les champs POST reçus vers l'application iOS du commerçant à l'aide d'une méthode UIWebViewDelegate shouldStartloadWithRequest.
Exemple de AcsWebViewController qui obtient le PaRes à partir d'une authentification ACS :
@implementation MERCHANTAPPAcsWebViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.webView.delegate = self;
NSMutableString *s = [NSMutableString stringWithCapacity:0];
[s appendString: [NSString stringWithFormat:@"<html><body onload=\"document.forms[0].submit()\">"
"<form method=\"post\" action=\"%@\">", self.acsUrl]];
if([self.acsPostParams count] % 2 == 1) {
NSLog(@"UIWebViewWithPost error: params don't seem right");
return;
}
for (int i=0; i < [self.acsPostParams count] / 2; i++) {
[s appendString: [NSString stringWithFormat:
@"<input type=\"hidden\" name=\"%@\" value=\"%@\" >\n",
[self.acsPostParams objectAtIndex:i*2],
[self.acsPostParams objectAtIndex:(i*2)+1]]];
}
[s appendString: @"</input></form></body></html>"];
[self.webView loadHTMLString:s baseURL:nil];
}
// This function is called on all location change :
- (BOOL)webView:(UIWebView *)webView2 shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType {
// Intercept custom location change, URL begins with “putpares l:"
if ([[[request URL] absoluteString] hasPrefix:@"putpares:"]) {
// Extract the selector name from the URL
NSArray *components = [[[request URL] absoluteString] componentsSeparatedByString:@":"];
NSString * paRes = [components objectAtIndex:1];
NSLog(@"paRes : %@", paRes);
[UIApplication sharedApplication].networkActivityIndicatorVisible = YES;
UIAlertView *alert = [[UIAlertView alloc]
initWithTitle:[[NSBundle mainBundle] localizedStringForKey:@"wait" value:@"" table:nil]
message:@""
delegate:nil
cancelButtonTitle:nil
otherButtonTitles:nil];
[alert show];
[InAppSdk
cardValidateAuthenticationAndOrderWithPaResMessage:paRes
andTransactionContextData:self.transactionContextData
andRedirectionUrl:self.redirectionUrl
andTransactionContextVersion:self.transactionContextVersion
andHandler:^(NSDictionary *result) {
//Do something with cardValidateAuthentication response
}];
// Cancel the location change
return NO;
}
// Accept this location change
return YES;
}
@endAnalyser les erreurs causées par une fonction
Le tableau ci-dessous vous donne les codes réponses génériques pour toutes les opérations. Veuillez consulter le dictionnaire des données pour connaître le détail des codes-réponse par fonction.
| État | Champs de la réponse | Action à réaliser |
|---|---|---|
| Fonction réalisée | responseCode = 00 | La fonction demandée a été réalisée avec succès (par exemple un remboursement avec la fonction refund). |
| Refus suite problème technique | responseCode = 90, 99 | Problème technique temporaire lors du traitement de la fonction. Essayez ultérieurement d’exécuter de nouveau la fonction. |
| Fonction non autorisée | responseCode = 40 | Vous n’avez pas les droits pour exécuter cette fonction. Prenez contact avec le centre d’assistance technique pour demander l’activation de ces droits si votre contrat acquéreur le permet. |
| Fonction non réalisée | Tout autre responseCode | La fonction n’a pas pu être réalisée car un des paramètres doit être incorrect. Consultez le dictionnaire des données pour connaître le détail de chaque code erreur et le format de chaque paramètre. |
Étape 3 : tester en Recette et passer en Production
Afin de tester vos développements en environnement de Recette et d'effectuer votre passage en Production, vous devez avoir finalisé l'implémentation de la partie serveur à serveur décrite dans la documentation In-App. Vous pouvez alors reprendre à l'étape de "test en environnement de recette" de cette même documentation.
