Introduction
Mercanet is a secure multi-channel e-commerce payment solution that complies with the PCI DSS standard. It allows you to accept and manage payment transactions by taking into account business rules related to your activity (payment upon shipping, deferred payment, recurring payment, payment in instalments, etc.).
The purpose of this document is to explain the implementation steps of the solution up to live operations.
Who does this document target?
This document is intended for merchants wishing to subscribe to the Mercanet offer and integrate payment as part of their iOS mobile application.
It is an implementation guide for your technical team.
To get an overview of the Mercanet solution, we advise you to consult the following documents:
To get an overview of the In-App connector, we advise you to also consult the following document:
Prerequisites
Knowledge of standards related to mobile programming languages used today is necessary to develop a iOS mobile application connected to the SDK proposed by In-App.
Before implementing the SDK, you should have followed In-App connector implementation steps (cf. In-App documentation).
Note: all code sections in this document are provided as samples, you will
need to adapt them to your mobile application for them to be fully
operable.
IMPORTANT: the In-App SDK must be used with
at least a 7.0 version of iOS system.
Download SDK
You can download our iOS SDK via this link.
SDK checksums are in the table below.
| Type | Checksum |
|---|---|
| MD5 | 850d261af9e54213465fff672953a5a6 |
| SHA256 | 6fc9ac3c4d402e2e86dd8ede4653e0793a112987e4327671b9f7bf73b3f49bda |
| SHA512 | 4c738fe022320ef53e767c2daec3570c34f06cbe8e9ded067f627217c7173c749924eaece90726b6cb6f3875b53d8c37d9fa4cba6e1ad53c5133d69f0f467e41 |
Historic iOS SDK
| Version | Date | Description |
|---|---|---|
| 24.3.0 | June 2024 |
Addition of the « Privacy Manifest » required by Apple for apps and third-party libraries likely to collect personal data. |
| 23.1.0 | January 2023 |
Add field paymentMeanCoBadgingBrandList on getWalletData method |
| 22.5.0 | July 2022 |
Add field issuingCountryCode on object INAPPCardData |
| 21.5.0 | July 2021 |
Add package arm64 in XCFramework |
| 21.4.0 | June 2021 |
Add fields paymentMeanBrand and paymentMeanBrandSelectionStatus on walletOrderWithPaymentMeanId, walletCheckEnrollmentWithPaymentMeanId and addCardWithCardNumber methods |
| 21.3.2 | April 2021 |
Add method generatePaymentTokenWithCardNumber GDPR: Delete UUID on deviceContext |
| 21.2.0 | February 2021 |
Replace paymentMeanId format from NSString to NSInteger Add packaging XCFramework Fix on packaging Release-universal (add architectures i386 and x86_64) |
Implementing the SDK in 3 steps
Step 1: importing the SDK in an iOS project
The SDK contains three folders:
- Release-iphoneos: this folder is useful to compile a project for an iphone device. It's useful to perform real tests before launching live operation.
- Release-iphonesimulator: this folder is useful to compile a project for an iOS simulator.
- Release-universal: this folder regroups the two architectures previously mentioned.
The SDK is published in the form of a framework file.
Simply drag and drop the InAppSdk.framework file into your project to import it.
Linking the binary with libraries
In your project, you must link the SDK file.
To do this, in XCode:
- click on your project;
- click on your target application,
- click on the Build phases tab,
- expand the Link Binary With Libraries section,
- click on the « + » symbol,
- select the InAppSdk.framework file.
This is sometimes done automatically.
Linking embedded binaries
In your merchant project, you must link embedded binaries.
To do this, in XCode:
- click on your project;
- click on your target application,
- click on General tab,
- in the Embedded Binaries section:
- click on the "+" symbol,
- select the InAppSdk.framework file.
You should have the following configuration:
Step 2: using available functions
All the necessary methods are in the InAppSdk public class.
Tip: on the iOS version of the SDK, the asynchronism is
managed within the SDK itself. Therefore, there is no need to call these
functions asynchronously, the response is received using a handler at the
end of the call.
Tip: before using a function, make sure you have the rights to
use this function on your shop by contacting the Mercanet
technical support.
Payment functions
Function cardOrder
This function allows you to
carry out a card payment.
It has to be called after a request
from your server to In-App orderInitialize
service, with
sdkOperationName=CARDORDER.cardOrder request format
| Fields | Presence | Type | Comments | |
|---|---|---|---|---|
| cardCSCValue | Optional | Visual card security code | ||
| cardExpiryDate | Mandatory | Card expiry date | ||
| cardNumber | Optional | Card number | ||
| paymentMeanBrand | Optional | Name of the payment method that is used | ||
| paymentMeanBrandSelectionStatus | Optional | Status of the processing of the brand application selection | ||
| publicKeyValue | Mandatory | Value of the public key used to encrypt the data sent to through the SDK | Retrieved from initialization request | |
| redirectionData | Mandatory | Context of the transaction sent during initialization | ||
| redirectionUrl | Mandatory | URL of the next SDK service to call | ||
| redirectionVersion | Mandatory | Interface version | ||
| handler | Mandatory | void (^)(INAPPOrderResponse * response) | Handler supplied at the end of the call | |
cardOrder response format (OrderResponse object)
| Fields | Type | Comments |
|---|---|---|
| acquirerResponseCode | Acquirer response code | |
| amount | Transaction amount | |
| authentExemptionReasonList | List of | Exemption fixed by the issuer |
| authorisationId | Authorisation ID returned by the acquirer if the authorisation request is accepted | |
| authorisationTypeLabel | Label of the authorisation request type | |
| authorMessageReference | Identifier shared with the acquirer during the authorisation process | |
| captureDay | Capture delay | |
| captureMode | Capture mode | |
| cardData | INAPPCardData | Contains specific information regarding a card (Cf part Containers) |
| cardExpiryDate | (yyyyMM) | Card expiry date |
| currencyCode | Currency code | |
| customerId | Customer ID | |
| errorFieldName | Request field name which originated the error | |
| guaranteeIndicator | Transaction's guarantee level | |
| guaranteeLimitDateTime | Deadline for application of the payment guarantee | |
| holderAuthentMethod | Name of the method applied to authenticate a payment mean holder | |
| holderAuthentProgram | Authentication program | |
| holderAuthentRelegationCode | Code indicating whether the issuer accepts or refuses the transfer of responsibility | |
| holderAuthentResponseCode | Response code of the authentication process | |
| holderAuthentStatus | Result of the authentication process | |
| holderAuthentType | Cardholder authentication type applied by the issuer of the card. Field valued in 3-D Secure v2. | |
| inAppResponseCode | Mercanet response code | |
| invoiceReference | Invoice reference | |
| issuerWalletInformation | Information given by the wallet provider intended for the merchant in response to a transaction creation request | |
| maskedPan | Masked card number | |
| merchantId | Mercanet identifier of your shop | |
| merchantWalletId | Customer's Wallet identifier | |
| orderChannel | Order channel | |
| orderId | Order ID | |
| panEntryMode | Card number reading mode | |
| paymentMeanBrand | Brand of the card | |
| paymentMeanBrandSelectionStatus | Status of the processing of the brand application selection | |
| paymentMeanType | Payment method type (card, transfer, withdrawal, etc). It groups together a set of paymentMeanBrand. | |
| paymentPattern | Type of payment (per operation, 1st recurring payment etc). | |
| returnContext | Value sent in the request | |
| s10TransactionReference | INAPPS10TransactionReference | Contains the identification of the original transaction (to be compliant with Mercanet 1.0 (Cf Containers part) |
| statementReference | Reference provided by the merchant which is sent in the payment collection flow. This reference appears on the account statements of the cardholder. | |
| transactionDateTime | Date and time the transaction was processed on the Mercanet server (expressed in the Mercanet server time zone) | |
| transactionOrigin | Origin of a transaction (for example: name of the program), set by the merchant | |
| transactionPlatform | Platform where the transaction has been executed | |
| transactionReference | Transaction reference | |
| walletType | Wallet type |
Function walletOrder
This function allows you to
carry out a wallet payment.
It has to be called after a request
from your server to In-App orderInitialize
service, with
sdkOperationName=WALLETORDER.walletOrder request format
| Fields | Presence | Type | Comments | |
|---|---|---|---|---|
| cardCSCValue | Optional | Visual card security code | ||
| paymentMeanBrand | Optional | Selected brand of the payment mean. If not sent, value stored in the Wallet will be used. | ||
| paymentMeanBrandSelectionStatus | Optional | Status of the processing of the brand application selection. If not sent, value stored in the wallet will be used. | ||
| paymentMeanId | Mandatory | ID of the selected card in the Wallet | ||
| publicKeyValue | Mandatory | Value of the public key used to encrypt the data sent to through the SDK | Retrieved from initialization request | |
| redirectionData | Mandatory | Context of the transaction sent during initialization | ||
| redirectionUrl | Mandatory | URL of the next SDK service to call | ||
| redirectionVersion | Mandatory | Interface version | ||
| handler | Mandatory | void (^)(INAPPOrderResponse * response) | Handler supplied at the end of the call | |
walletOrder response format (OrderResponse object)
| Fields | Type | Comments |
|---|---|---|
| acquirerResponseCode | Acquirer response code | |
| amount | Transaction amount | |
| authentExemptionReasonList | List of | Exemption fixed by the issuer |
| authorisationId | Authorisation ID returned by the acquirer if the authorisation request is accepted | |
| authorisationTypeLabel | Label of the authorisation request type | |
| authorMessageReference | Identifier shared with the acquirer during the authorisation process | |
| captureDay | Capture delay | |
| captureMode | Capture mode | |
| cardData | INAPPCardData | Contains specific information regarding a card (Cf part Containers) |
| cardExpiryDate | (yyyyMM) | Card expiry date |
| currencyCode | Currency code | |
| customerId | Customer ID | |
| errorFieldName | Request field name which originated the error | |
| guaranteeIndicator | Transaction's guarantee level | |
| guaranteeLimitDateTime | Deadline for application of the payment guarantee | |
| holderAuthentMethod | Name of the method applied to authenticate a payment mean holder | |
| holderAuthentProgram | Authentication program | |
| holderAuthentRelegationCode | Code indicating whether the issuer accepts or refuses the transfer of responsibility | |
| holderAuthentResponseCode | Response code of the authentication process | |
| holderAuthentStatus | Result of the authentication process | |
| holderAuthentType | Cardholder authentication type applied by the issuer of the card. Field valued in 3-D Secure v2. | |
| inAppResponseCode | Mercanet response code | |
| invoiceReference | Invoice reference | |
| issuerWalletInformation | Information given by the wallet provider intended for the merchant in response to a transaction creation request | |
| maskedPan | Masked card number | |
| merchantId | Mercanet identifier of your shop | |
| merchantWalletId | Customer's Wallet identifier | |
| orderChannel | Order channel | |
| orderId | Order ID | |
| panEntryMode | Card number reading mode | |
| paymentMeanBrand | Brand of the card | |
| paymentMeanBrandSelectionStatus | Status of the processing of the brand application selection | |
| paymentMeanType | Payment method type (card, transfer, withdrawal, etc). It groups together a set of paymentMeanBrand. | |
| paymentPattern | Type of payment (per operation, 1st recurring payment etc). | |
| returnContext | Value sent in the request | |
| s10TransactionReference | INAPPS10TransactionReference | Contains the identification of the original transaction (to be compliant with Mercanet 1.0 (Cf Containers part) |
| statementReference | Reference provided by the merchant which is sent in the payment collection flow. This reference appears on the account statements of the cardholder. | |
| transactionDateTime | Date and time the transaction was processed on the Mercanet server (expressed in the Mercanet server time zone) | |
| transactionOrigin | Origin of a transaction (for example: name of the program), set by the merchant | |
| transactionPlatform | Platform where the transaction has been executed | |
| transactionReference | Transaction reference | |
| walletType | Wallet type |
Function paymentProviderOrder
This function
allows you to get the BCMC Intent URL to be called to carry out a BCMC
payment.
It has to be called after a request from your server to
In-App orderInitialize service, with
sdkOperationName=PAYMENTPROVIDERORDER
and paymentMeanBrand=BCMCMOBILE.paymentProviderOrder request format
| Fields | Presence | Type | Comments | |
|---|---|---|---|---|
| publicKeyValue | Mandatory | Value of the public key used to encrypt the data sent to through the SDK | Retrieved from initialization request | |
| redirectionData | Mandatory | Context of the transaction sent during initialization | ||
| redirectionUrl | Mandatory | URL of the next SDK service to call | ||
| redirectionVersion | Mandatory | Interface version | ||
| handler | Mandatory | void (^)(INAPPPaymentProviderResponse * response) | Handler supplied at the end of the call | |
paymentProviderOrder response format (PaymentProviderResponse object)
| Fields | Type | Comments |
|---|---|---|
| errorFieldName | Request field name which originated the error | |
| inAppResponseCode | Mercanet response code | |
| outerRedirectionUrl | Redirection URL to an outer payment application (here: BCMC mobile application) | |
| redirectionUrl | URL of the next SDK service to call | |
| transactionContextData | Transaction context | |
| transactionContextVersion | Transaction context version |
Function getTransactionData
This function allows
you to check the status of the ongoing BCMC transaction once the
BCMC application has been called.
It has to be called following
a request to In-App paymentProviderOrder, when
the BCMC application calls back the merchant application.
getTransactionData request format
| Fields | Presence | Type | Comments | |
|---|---|---|---|---|
| transactionContextData | Mandatory | Transaction context | Retrieved from paymentProviderOrder response | |
| transactionContextVersion | Mandatory | Transaction context version | ||
| redirectionUrl | Mandatory | URL of the next SDK service to call | ||
| handler | Mandatory | void (^)(INAPPGetTransactionDataResponse * response) | Handler supplied at the end of the call | |
getTransactionData response format (GetTransactionDataResponse object)
| Fields | Type | Comments |
|---|---|---|
| acquirerResponseCode | Acquirer response code | |
| authentExemptionReasonList | List of | Exemption fixed by the issuer |
| authorisationId | Authorisation ID returned by the acquirer if the authorisation request is accepted | |
| authorisationTypeLabel | Label of the authorisation request type | |
| authorMessageReference | Identifier shared with the acquirer during the authorisation process | |
| captureLimitDate | Date from which the transaction will be sent for settlement. Beyond this date, you can no longer validate or cancel the transaction. | |
| captureMode | Capture mode | |
| cardData | INAPPCardData | Contains specific information regarding a card (Cf part Containers) |
| cardExpiryDate | (yyyyMM) | Card expiry date |
| currencyCode | Currency code | |
| customerId | Customer ID | |
| errorFieldName | Request field name which originated the error | |
| guaranteeIndicator | Transaction's guarantee level | |
| guaranteeLimitDateTime | Deadline for application of the payment guarantee | |
| holderAuthentMethod | Name of the method applied to authenticate a payment mean holder | |
| holderAuthentProgram | Authentication program | |
| holderAuthentRelegationCode | Code indicating whether the issuer accepts or refuses the transfer of responsibility | |
| holderAuthentResponseCode | Response code of the authentication process | |
| holderAuthentStatus | Result of the authentication process | |
| holderAuthentType | Cardholder authentication type applied by the issuer of the card. Field valued in 3-D Secure v2. | |
| inAppResponseCode | Mercanet response code | |
| invoiceReference | Invoice reference | |
| issuerWalletInformation | Information given by the wallet provider intended for the merchant in response to a transaction creation request | |
| maskedPan | Masked card number | |
| merchantId | Mercanet identifier of your shop | |
| merchantWalletId | Customer's Wallet identifier | |
| orderChannel | Order channel | |
| orderId | Order ID | |
| originAmount | Original amount of the transaction | |
| panEntryMode | Card number reading mode | |
| paymentMeanBrand | Brand of the card | |
| paymentMeanBrandSelectionStatus | Status of the processing of the brand application selection | |
| paymentMeanType | Payment method type (card, transfer, withdrawal, etc). It groups together a set of paymentMeanBrand. | |
| paymentPattern | Type of payment (per operation, 1st recurring payment etc). | |
| returnContext | Value sent in the request | |
| s10TransactionReference | INAPPS10TransactionReference | Contains the identification of the original transaction (to be compliant with Mercanet 1.0 (Cf Containers part) |
| statementReference | Reference provided by the merchant which is sent in the payment collection flow. This reference appears on the account statements of the cardholder. | |
| transactionDateTime | Date and time the transaction was processed on the Mercanet server (expressed in the Mercanet server time zone) | |
| transactionOrigin | Origin of a transaction (for example: name of the program), set by the merchant | |
| transactionPlatform | Platform where the transaction has been executed | |
| transactionReference | Transaction reference | |
| transactionStatus | Status of the transaction | |
| walletType | Wallet type |
Function cardCheckEnrollment
This function is
used to prepare a 3-D Secure payment. It allows you to get the
paReq (Payer Authentication Request) message and the ACS (Access
Control Server) URL you will use to redirect the customer for
authentication.
It has to be called after a request from your
server to In-App orderInitialize service, with
sdkOperationName=THREEDSECUREANDORDER.cardCheckEnrollment request format
| Fields | Presence | Type | Comments | |
|---|---|---|---|---|
| cardCSCValue | Optional | Visual card security code | ||
| cardExpiryDate | Mandatory | Card expiry date | ||
| cardNumber | Optional | Card number | ||
| paymentMeanBrand | Optional | Name of the payment method that is used | ||
| paymentMeanBrandSelectionStatus | Optional | Status of the processing of the brand application selection | ||
| publicKeyValue | Mandatory | Value of the public key used to encrypt the data sent to through the SDK | Retrieved from initialization request | |
| redirectionData | Mandatory | Context of the transaction sent during initialization | ||
| redirectionUrl | Mandatory | URL of the next SDK service to call | ||
| redirectionVersion | Mandatory | Interface version | ||
| handler | Mandatory | void (^)(INAPPCardCheckEnrollmentResponse * response) | Handler supplied at the end of the call | |
cardCheckEnrollment response format (CardCheckEnrollmentResponse object)
| Fields | Type | Comments |
|---|---|---|
| authentRedirectionUrl | ACS redirection URL | |
| errorFieldName | Request field name which originated the error | |
| maskedPan | Masked card number | |
| paReqMessage | PaReq message used for ACS authentication | |
| redirectionStatusCode | Mercanet response code | |
| redirectionUrl | URL of the next SDK service to call | |
| tokenPan | Unique ID for a PAN | |
| transactionContextData | Transaction context | |
| transactionContextVersion | Transaction context version |
Depending on the result, your application must redirect the customer to the ACS (refer to POST form to the ACS).
Function walletCheckEnrollment
This function
allows you to prepare a 3-D Secure payment from a card already
stored in Mercanet Wallet. It allows you to get the
paReq (Payer Authentication Request) message and the ACS (Access
Control Server) URL you will use to redirect the customer for
authentication.
It has to be called after a request from your
server to In-App orderInitialize service, with
sdkOperationName=THREEDSECUREANDWALLETORDER.walletCheckEnrollment request format
| Fields | Presence | Type | Comments | |
|---|---|---|---|---|
| cardCSCValue | Optional | Visual card security code | ||
| paymentMeanBrand | Optional | Selected brand of the payment mean. If not sent, value stored in the Wallet will be used. | ||
| paymentMeanBrandSelectionStatus | Optional | Status of the processing of the brand application selection. If not sent, value stored in the wallet will be used. | ||
| paymentMeanId | Mandatory | ID of the selected card in the Wallet | ||
| publicKeyValue | Mandatory | Value of the public key used to encrypt the data sent to through the SDK | Retrieved from initialization request | |
| redirectionData | Mandatory | Context of the transaction sent during initialization | ||
| redirectionUrl | Mandatory | URL of the next SDK service to call | ||
| redirectionVersion | Mandatory | Interface version | ||
walletCheckEnrollment response format (WalletCheckEnrollmentResponse object)
| Fields | Type | Comments |
|---|---|---|
| authentRedirectionUrl | ACS redirection URL | |
| errorFieldName | Request field name which originated the error | |
| maskedPan | Masked card number | |
| paReqMessage | PaReq message used for authentication | |
| paymentMeanBrand | Brand of the card | |
| paymentMeanBrandSelectionStatus | Status of the processing of the brand application selection | |
| redirectionStatusCode | Mercanet response code | |
| redirectionUrl | URL of the next SDK service to call | |
| tokenPan | Unique ID for a PAN | |
| transactionContextData | Transaction context | |
| transactionContextVersion | Transaction context version |
Depending on the result, your application must redirect the customer to the ACS (refer to POST form to the ACS).
Function cardValidateAuthenticationAndOrder
This
function allows you to validate customer's authentication, and perform the
payment.
It has to be called following a request to In-App cardCheckEnrollment or
walletCheckEnrollment, once the ACS returns the PARes
message."URL Encode" algorithm must be applied to the PARes message
before being supplied to the SDK.
cardValidateAuthenticationAndOrder request format
| Fields | Presence | Type | Comments | |
|---|---|---|---|---|
| paResMessage | Mandatory | Customer authentication result. Standard "URL Encode" algorithm must be applied to paResMessage field received from ACS. | ||
| transactionContextData | Mandatory | Transaction context | Retreived from cardCheckEnrollment or walletCheckEnrollment response | |
| transactionContextVersion | Mandatory | Transaction context version | ||
| redirectionUrl | Mandatory | URL of the next SDK service to call | ||
| handler | Mandatory | void (^)(INAPPOrderResponse * response) | Handler supplied at the end of the call | |
cardValidateAuthenticationAndOrder response (OrderResponse object)
| Fields | Type | Comments |
|---|---|---|
| acquirerResponseCode | Acquirer response code | |
| amount | Transaction amount | |
| authentExemptionReasonList | List of | Exemption fixed by the issuer |
| authorisationId | Authorisation ID returned by the acquirer if the authorisation request is accepted | |
| authorisationTypeLabel | Label of the authorisation request type | |
| authorMessageReference | Identifier shared with the acquirer during the authorisation process | |
| captureDay | Capture delay | |
| captureMode | Capture mode | |
| cardData | INAPPCardData | Contains specific information regarding a card (Cf part Containers) |
| cardExpiryDate | (yyyyMM) | Card expiry date |
| currencyCode | Currency code | |
| customerId | Customer ID | |
| errorFieldName | Request field name which originated the error | |
| guaranteeIndicator | Transaction's guarantee level | |
| guaranteeLimitDateTime | Deadline for application of the payment guarantee | |
| holderAuthentMethod | Name of the method applied to authenticate a payment mean holder | |
| holderAuthentProgram | Authentication program | |
| holderAuthentRelegationCode | Code indicating whether the issuer accepts or refuses the transfer of responsibility | |
| holderAuthentResponseCode | Response code of the authentication process | |
| holderAuthentStatus | Result of the authentication process | |
| holderAuthentType | Cardholder authentication type applied by the issuer of the card. Field valued in 3-D Secure v2. | |
| inAppResponseCode | Mercanet response code | |
| invoiceReference | Invoice reference | |
| issuerWalletInformation | Information given by the wallet provider intended for the merchant in response to a transaction creation request | |
| maskedPan | Masked card number | |
| merchantId | Mercanet identifier of your shop | |
| merchantWalletId | Customer's Wallet identifier | |
| orderChannel | Order channel | |
| orderId | Order ID | |
| panEntryMode | Card number reading mode | |
| paymentMeanBrand | Brand of the card | |
| paymentMeanBrandSelectionStatus | Status of the processing of the brand application selection | |
| paymentMeanType | Payment method type (card, transfer, withdrawal, etc). It groups together a set of paymentMeanBrand. | |
| paymentPattern | Type of payment (per operation, 1st recurring payment etc). | |
| returnContext | Value sent in the request | |
| s10TransactionReference | INAPPS10TransactionReference | Contains the identification of the original transaction (to be compliant with Mercanet 1.0 (Cf Containers part) |
| statementReference | Reference provided by the merchant which is sent in the payment collection flow. This reference appears on the account statements of the cardholder. | |
| transactionDateTime | Date and time the transaction was processed on the Mercanet server (expressed in the Mercanet server time zone) | |
| transactionOrigin | Origin of a transaction (for example: name of the program), set by the merchant | |
| transactionPlatform | Platform where the transaction has been executed | |
| transactionReference | Transaction reference | |
| walletType | Wallet type |
Wallet management functions
Function getWalletData
This function allows you
to retrieve the content of a customer's Mercanet
Wallet.
It has to be called after a request from your server to
In-App walletInitialize service, with
sdkOperationName=GETWALLETDATA.getWalletData request format
| Fields | Presence | Type | Comments | |
|---|---|---|---|---|
| publicKeyValue | Mandatory | Value of the public key used to encrypt the data sent to through the SDK | Retrieved from initialization request | |
| redirectionData | Mandatory | Context of the transaction sent during initialization | ||
| redirectionUrl | Mandatory | URL of the next SDK service to call | ||
| redirectionVersion | Mandatory | Interface version | ||
| handler | Mandatory | void (^)(INAPPGetWalletDataResponse * response) | Handler supplied at the end of the call | |
getWalletData response format (GetWalletDataResponse format)
| Fields | Type | Comments |
|---|---|---|
| errorFieldName | Request field name which originated the error | |
| inAppResponseCode | Mercanet response code | |
| walletCreationDateTime | Wallet creation date | |
| walletPaymentMeanData | List of INAPPGetWalletDataResponseItem | List of a customer's Wallet registered cards (Cf Containers part) |
Function addCard
This function allows you to add
a new card to a customer's Mercanet Wallet.
It
has to be called after a request from your server to In-App walletInitialize service, with
sdkOperationName=ADDCARD.addCard request format
| Fields | Presence | Type | Comments | |
|---|---|---|---|---|
| cardExpiryDate | Mandatory | Card expiry date | ||
| cardNumber | Mandatory | Card number | ||
| paymentMeanAlias | Mandatory | Alias of the card stored in the Wallet | ||
| paymentMeanBrand | Optional | Brand of the card | ||
| paymentMeanBrandSelectionStatus | Optional | Status of the processing of the brand application selection | ||
| publicKeyValue | Mandatory | Value of the public key used to encrypt the data sent to through the SDK | Retrieved from initialization request | |
| redirectionData | Mandatory | Context of the transaction sent during initialization | ||
| redirectionUrl | Mandatory | URL of the next SDK service to call | ||
| redirectionVersion | Mandatory | Interface version | ||
| handler | Mandatory | void (^)(INAPPAddCardResponse * response) | Handler supplied at the end of the call | |
addCard response format (AddCardResponse object)
| Fields | Type | Comments |
|---|---|---|
| errorFieldName | Request field name which originated the error | |
| inAppResponseCode | Mercanet response code | |
| paymentMeanId | ID of the payment mean in the Wallet | |
| maskedPan | Masked card number | |
| walletActionDateTime | Date of the last action done on the Wallet |
Function deletePaymentMean
This function allows
you to delete a payment mean from a customer's Mercanet
Wallet.
It has to be called after a request from your server to
In-App walletInitialize service, with
sdkOperationName=DELETEPAYMENTMEAN.deletePaymentMean request format
| Fields | Presence | Type | Comments | |
|---|---|---|---|---|
| paymentMeanId | Mandatory | ID of the payment mean to delete from the Wallet | ||
| publicKeyValue | Mandatory | Value of the public key used to encrypt the data sent to through the SDK | Retrieved from initialization request | |
| redirectionData | Mandatory | Context of the transaction sent during initialization | ||
| redirectionUrl | Mandatory | URL of the next SDK service to call | ||
| redirectionVersion | Mandatory | Interface version | ||
| handler | Mandatory | void (^)(INAPPDeletePaymentMeanResponse * response) | Handler supplied at the end of the call | |
deletePaymentMean response format (DeletePaymentMeanResponse object)
| Fields | Type | Comments |
|---|---|---|
| errorFieldName | Request field name which originated the error | |
| inAppResponseCode | Mercanet response code | |
| walletActionDateTime | Date of the last action done on the Wallet |
Card data consulting function
Function getCardData
This function allows you to
get information linked to a PAN or a card BIN. For example, it will allow
you to propose to the customer to choose the brand to apply on a payment
while his card is linked to several brands.
It has to be called
after a request from your server to In-App
paymentMeanInfoInitialize service, with
sdkOperationName=GETCARDDATA.getCardData request format
| Fields | Presence | Type | Comments | |
|---|---|---|---|---|
| cardIIN | Optional | Card IIN | At least one of these fields must be sent in the request | |
| cardNumber | Optional | Card number | ||
| publicKeyValue | Mandatory | Value of the public key used to encrypt the data sent to through the SDK | Retrieved from initialization request | |
| redirectionData | Mandatory | Context of the transaction sent during initialization | ||
| redirectionUrl | Mandatory | URL of the next SDK service to call | ||
| redirectionVersion | Mandatory | Interface version | ||
| handler | Mandatory | void (^)(INAPPGetCardDataResponse * response) | Handler supplied at the end of the call | |
getCardData response format (GetCardDataResponse object)
| Fields | Type | Comments |
|---|---|---|
| cardDataList | List of INAPPCardData | List of INAPPCardData container containing information about a card (in case of card cobadged several occurrences may appear - example: CB / Visa card). (Cf Containers part) |
| errorFieldName | Request field name which originated the error | |
| inAppResponseCode | Mercanet response code |
Containers
INAPPCardData
| Fields | Type | Comments |
|---|---|---|
| cardBrand | Card brand | |
| cardCorporateIndicator | Indicates whether the card is an Enterprise / Commercial card or not | |
| cardEffectiveDateIndicator | Indicator of existence of a card effective date (Y/N/Empty) | |
| cardProductCode | Product code of the card | |
| cardProductName | Product name of the card | |
| cardProductProfile | Profile code of the card | |
| cardProductUsageLabel | Profile name of the card which is displayed on payment electronic ticket in accordance with MPADS requirements | |
| cardScheme | Network name associated with the card | |
| cardSeqNumberIndicator | Indicator of existence of an issue number | |
| issuerCode | Issuer code of the card | |
| issuerCountryCode | Country code of the card issuer | |
| issuerName | Issuer name of the card | |
| issuerRegionCode | Region code of the card issuer | |
| issuingCountryCode | Country code in which the card has been issued | |
| panCheckAlgorithm | Control algorithm applied on the PAN (L/V/N/Empty) | |
| panLengthMax | Maximum length of the PAN | |
| panLengthMin | Minimal length of the PAN |
INAPPS10TransactionReference
| Fields | Type | Comments | |
|---|---|---|---|
| s10TransactionId | Alternative identifier for the transaction to be compliant with Mercanet 1.0 | The couple
s10TransactionId/s10TransactionIdDate ensures the unicity of the
1.0 transaction. The use of this couple instead of
transactionReference depends on an option in the merchant
configuration. |
|
| s10TransactionIdDate | Date of the transaction (expressed in the Mercanet server time zone) | ||
INAPPGetWalletDataResponseItem
| Fields | Type | Comments |
|---|---|---|
| maskedPan | Masked card number | |
| panExpiryDate | Card expiry date | |
| paymentMeanAlias | Card alias | |
| paymentMeanBrand | Card brand | |
| paymentMeanId | Payment mean ID in the customer's wallet |
POST redirection form
POST form to the ACS
Depending on enrollment check
result, your mobile application must redirect the customer to the ACS by
POSTing the following parameters to the received
authentRedirectionUrl:
- PaReq message: returned by the previous call in paReqMessage field;
- MD (Merchant Data) : field containing merchant status data which must be returned to the merchant. This field must be used to retrieve the session on your website;
- TermUrl : merchant URL used to receive the customer authentication result (PaRes and MD response fields). It must be a URL from your website where the customer is redirected to.
IMPORTANT: The MD field must contain ASCII
characters in the range 0x20 to 0x7E only; If other data are needed, the
field must be Base64 encoded. Size of the field (after Base64 encoding, if
applicable) is limited to 1024 bytes. If confidential data are included
(as the PAN), they must be encrypted.
On iOS, a function can be called in a UIWebView from JavaScript code. Therefore, TermUrl can be a merchant web page that pushes the received POST fields to merchant iOS application, using a UIWebViewDelegate shouldStartloadWithRequest method.
Sample AcsWebViewController that gets the PaRes from an ACS authentication:
@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;
}
@endAnalysing the errors caused by a function
The table below gives you the generic response codes for all operations. Refer to the data dictionary for details of response codes by function.
| Status | Response fields | Action to be performed |
|---|---|---|
| Function performed | responseCode = 00 | The requested function has been successfully completed (for example a refund with the refund function). |
| Declined following a technical problem | responseCode = 90, 99 | Temporary technical problem when the function was processed. Try to execute the function again later. |
| Unauthorised function | responseCode = 40 | You do not have the rights to execute this function. Please contact the technical support centre to request that this right be activated if your purchasing contract allows it. |
| Function not performed | Any other responseCode | The function could not be performed because one of the parameters is incorrect. Please consult the data dictionary for the details of each error code and for the format of each parameter. |
Step 3: testing in the validation environment and going to production
In order to test your developments on the tests environment, and to go to production, you must have finalize the server-to-server implementation part described in the In-App documentation. Then, you may go back to "test on the validation environment" step of this last documentation.
