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 on dispatch, deferred payment, recurring payment, payment in instalments, etc.).
The purpose of this document is to explain how to implement the solution until the release.
Who does this document target?
This document is intended to help you to set up a secure solution for your regular customers to store their payment details for future purchases. It presents the payment features and describes how to implement them with the Mercanet solution.
The purpose of the solution is to facilitate the purchase process (and thus increase the conversion rate) by improving the customer experience, particularly for mobile payments.
The principle is to allow customers to pay on Mercanet payment pages in a single click, without having to re-enter their payment details for each purchase.
To obtain an overview of the Mercanet solution, we advise you to view the following documents:
- Functional Presentation
- Functionality set-up guide
Prerequisites
The payment requires your customers payment details to be stored by Mercanet so you can accept payments.
To comply with the GDPR, you must complete your internal personal data processing register, specifying that the card details are stored in Mercanet platform. For more information on the GDPR, please refer to our Sips information systems security.
Overview of the service
The payment has several steps:
- enrolment of customer payment details
- OneClick payment
- management of customer payment details
- customer authentication
Storage of customer payment details
When you record a customer in your information system, you should allocate to him a unique account identifier (merchantWalletId) that Mercanet will use to store the customer's payment details. This ID will be used for subsequent payments.
A block diagram of the payment with a card:
The diagram above also applies to the payment with or a PayPal account.
The service is based on the Mercanet wallet, a secure virtual wallet, PCI-compliant, where customer payment details are stored:
- The wallet is a multi-purpose payment method.
- identifier = merchantWalletId.
- Payment method ID = paymentMeanSequence.
The payment methods that can be used with are:
- CB, Visa, Mastercard, Amex, Bancontact, Oney cards
- PayPal account
Mercanet stores in the wallet all the information you need to allow you to debit your customer based on their ID:
- CB, Visa, Mastercard, Amex, Bancontact, Oney cards
- Card number
- Expiry date
- Card type
- PayPal account
- PayPal account identifier
Enrolment of customer payment details
The customer enrolment involves recording customer payment details in the Mercanet wallet. The enrolment may or may not be associated with a first payment.
Customers can be enrolled via 4 interfaces:
- Paypage: the payment details are recorded during a purchase from the payment pages hosted by Mercanet.
- Office (M2M): you manage your own pages for entering payment details and you use the online web interface to record the customer in the Mercanet wallet (NB: the enrolment of PayPal as a payment method is not available with the Office (M2M) interface).
- Walletpage: the payment details are recorded, outside of a purchase, from the wallet management pages stored by Mercanet.
- In-App: you record the customer payment details during the first payment made through your mobile application.
payment
For subsequent payments, you transfer the customer ID in the requests, so that Mercanet can find payment details, which have already been recorded in the wallet.
- Paypage: for each purchase, you transmit the customer ID in the payment request.
- Office (M2M): you connect to the Mercanet via an online web interface for transmitting debit requests.
- In-App: for each purchase, you transmit the customer ID in the payment request.
Management of customer payment details
To complete the enrolment of payment methods and their use for making purchases, you can manage the content of the wallets. Several interfaces give you access to the wallet.
5 types of interface for managing the wallet content:
- Paypage: customers can modify their wallets during a purchase.
- In-App: customers can modify their wallets, inside or outside a purchase.
- Walletpage: customers can modify their wallets, outside of a purchase.
- Office (M2M): merchants can make changes to customer wallets.
- Mercanet Back Office: merchants can delete payment methods from their customer wallets.
Expired payment mean :
- if the payment mean is expired, it is not selectable on the payment page
- payment means expired from more than 3 months, are automatically removed from the wallet database
Customer authentication
In the payment process, you should authenticate your customers before accessing the User IDs stored in your customer database.
Once the authentication has been made, you transmit the Mercanet customer ID in the request via the merchantWalletId field.
Your User IDs management allocated to your customers should:
- guarantee a 1-1 relationship between the customer and their User ID (1 customer = 1 OneClick User ID).
- allow the permanent storage of User IDs.
Mercanet manages the secure storage of customer payment details.
Pages customisation
To maintain the graphic charter of your e-commerce website, the Paypage and Walletpage interfaces pages can be customised.
Please view the Payment pages customisation guide (Paypagel) for more information.
Reporting
For more information, please see the reports description guide.
Choice of connectors
Mercanet offers several interfaces for enrolling customers and processing payments. It is therefore helpful to analyse your business requirements when choosing the most suitable connectors for your circumstances.
The table below will help you make your choice.
| Interfaces Use cases |
Paypage | Office (M2M) | In-App | Walletpage | Mercanet Back Office | Recommendations for choosing the connector |
|---|---|---|---|---|---|---|
| Management of the enrolment pages | ||||||
| You outsource the pages for entering payment details to avoid the PCI requirements. | V | X | X | V | X | If you use Paypage to process your
payments, you can take advantage of this existing integration to
manage your customer enrolment. If not, we recommend the use
of Walletpage. |
| You manage the pages for entering payment details that you integrate into your customer enrolment process. | X | V | V | X | X | Office (M2M) meets your e-commerce needs. For m-commerce, we recommend the use of In-App. |
| Enrolment with or without payment | ||||||
| You allow your customers to enrol their payment methods during a purchase. | V | V | V | X | X | Paypage, Office (M2M) or In-App meet your needs, depending on whether or not you have decided to outsource the payment details entry pages. |
| You allow your customers to enrol their payment methods outside of a purchase. | X | V | V | V | X | Walletpage, Office (M2M) or In-App meet your needs, depending on whether or not you have decided to outsource the payment details entry pages. |
| payment | ||||||
| You outsource the payment pages. | V | X | X | X | X | Paypage meets your need. |
| You manage the payment pages on your website or mobile application. | X | V | V | X | X | Office (M2M) meets your e-commerce needs. For m-commerce, we recommend the use of In-App. |
| Crediting the customer | ||||||
| You need to credit one of your customers outside of a refund context. | X | V | X | X | X | Office (M2M) meets your need. |
| Managing your customer payment details | ||||||
| A customer wants to change the alias of one of their payment methods. | V | V | X | V | X | Reuse the same interface as the one used for enrolment. However, if you use In-App for the enrolment, we recommend using Office (M2M) in this case. |
| A customer wants to delete one of their payment methods. | V | V | V | V | V | Reuse the same interface as the one used for enrolment.
However, if you use In-App for the
enrolment, we recommend using Office (M2M) in this
case. If you cannot, or do not want to develop access to the
delete function for your customers, you can delete the payment
method from your customers' wallets from the Mercanet Back Office. |
| A customer wants to delete his wallet. | X | V | X | V | X | If you already use Walletpage to process other use cases, you can keep this interface to let your customers delete their wallets. |
Implementation
In order to implement the , you should get a suitable connector guide to learn about the technical details of implementation.
Enrolling your customer payment details with Paypage
This is a typical Paypage payment process, where the payment details are recorded in the wallet if the transaction is accepted.
Description
Here is an example of payment process valid for the payment methods CB, VISA and MASTERCARD.
1.To record your customer payment details, you should redirect them to Paypage, sending the transaction details in the request (amount, currency, etc.), as well as the customer ID (merchantWalletId field).
2.Mercanet displays the payment page, the customer provides their payment details then confirms.
3. Mercanet proceeds with 3-D Secure verification.
4. Mercanet makes anti-fraud checks.
5. Mercanet sends an authorisation request to the acquirer
6. Mercanet records the transaction in the back office
7. If the transaction is approved Mercanet records the customer payment details in the wallet.
8. Mercanet displays the payment receipt page with a confirmation message that the customer payment method has been recorded.
9. Mercanet returns the manual and automatic responses containing the transaction details, including the result of customer registration in the wallet.
10. Mercanet may or may not send the transaction for remittance, depending on the settings that you have configured in the payment request.
The sequence described above applies to the Amex, Bancontact, and PayPal payment methods.
Setting the request
To enrol a customer for the service via Paypage, you should populate the fields below:
| Field | Value setting |
|---|---|
| merchantWalletId | Customer unique ID |
Please refer to one of the Paypage guides corresponding to the selected connector (JSON, POST or SOAP) to learn how to populate the request, depending on your business requirement.
Analysing the response
Mercanet returns a typical Paypage manual and automatic response.
The following fields are related to the customer enrolment:
| Status | Response fields | Action to take |
|---|---|---|
| Transaction accepted Customer
enrolled |
|
Store the following customer details in your customer
database:
|
| Transaction accepted Customer not
enrolled |
|
Transaction accepted but the customer payment method has
not been enrolled for the following reasons:
|
| Transaction declined Customer not
enrolled |
responseCode = different from
00 |
Please refer to the Paypage guide corresponding to the selected connector (JSON, POST or SOAP) to analyse the Mercanet response. |
Enrolling your customer payment details with Office (M2M)
Before recording the payment method in the wallet, you should have to check it first via a 3-D Secure authentication request and via a standard payment request.
Description
You manage the data entry for payment methods on your website.
- Step 1: You send a request to Mercanet to
verify the payment method before enrolling the customer.
- The 3-D secure authentication to verify that the customer is the cardholder of CB, Visa, Mastercard, Amex, Bancontact cards.
- Anti-fraud checks that you have configured according to your business rules (e.g. foreign cards, commercial cards, etc.).
- Authorisation request to the acquirer to verify that the card is
still valid (not stolen, lost etc.).
- Mercanet records the transaction.
- Mercanet may or may not send the transaction for remittance to the acquirer, depending on the elements provided in the request.
- Mercanet sends you the results of the payment methods verification.
Step 2: Once the payment method has been verified, you send a second request to Mercanet to register the payment method in the wallet.
- Mercanet returns the payment method registration response.
The sequence described above applies to the Amex, and Bancontact means of payment.
Setting the payment method verification requests
Use the methods below, depending on the verification level of the payment method to be enrolled.
CB, Visa, Mastercard, Bancontact, Oney, AMEX cards
| Wallet service methods | Type of action |
|---|---|
| addcard | Adding a card to the wallet |
Please refer to one of the Office (M2M) guides corresponding to the selected connector (JSON or SOAP), as well as the Payment methods guides, to learn how to populate the request, depending on your business requirements.
Analysing the authentication response
cardValidateAuthentication method
| Status | Response fields | Action to take |
|---|---|---|
| Authenticated cardholder | holderAuthentResponseCode = 00 | You can register the card in the wallet using the addcard method. |
| Failure to authenticate cardholder | holderAuthentResponseCode=01 | Tell the customer that their card number is invalid and ask them to enrol another payment method. |
| Other refusals | holderAuthentResponseCode=XX | If 3-D Secure authentication is required for your business to enrol a card, ask the customer to enrol another payment method. If the 3-D Secure authentication is not
required for your business to enrol a card, you can proceed to
card verification with a cardOrder
request. |
Analysing the authorisation response with anti-fraud checks
When receiving the answer, before analysing it and following the advice in the table below, check the seal. The recalculated seal must be identical to the seal received.
CardOrder, cardValidateAuthenticationAndOrder and directDebitOrder methods
| Status | Response fields | Action to take |
|---|---|---|
| Transaction accepted | responseCode = 00 acquirerResponseCode = 00 |
Store in your information system the field schemeTransactionIdentifier You can register the card for the wallet using the addcard or addDirectDebit method. |
| Transaction refused | responseCode = XX | Tell the customer that their card number is invalid and ask them to enrol another payment method. |
Setting the enrollment request for customer payment details
Use the methods below, depending on the payment method to be enrolled. The merchantWalletId field contains the customer ID.
Carte CB, Visa, Mastercard, Bancontact, Oney, Amex
| Wallet service methods | Type of action |
|---|---|
| addcard | Adding a new card to the wallet |
Please refer to the adequate Office (M2M) guide, as well as the Payment methods guides, to learn how to populate the request, depending on your business requirements.
Analysing the enrolment response
| Status | Response fields | Action to take |
|---|---|---|
| Customer enrolled | walletReponseCode = 00 paymentMeanId = sequence number of the payment method |
You can complete customer registration in your information system |
Customer not enrolled Invalid request |
walletReponseCode = xx paymentMeanId = not populated |
Please refer to the Office (M2M) guide corresponding to the selected connector (JSON or SOAP) to analyse the Mercanet response. |
Enrolling your customer payment details with Walletpage
With Walletpage, you allow your customers to enrol outside of a payment context.
Description
1. During the process of enrolling your customers, you redirect them to Walletpage to enter their payment details. Customers select a payment method, provide their payment details, then confirm.
2. Mercanet proceeds with 3-D Secure verification.
3. Mercanet makes anti-fraud checks.
4. Mercanet sends an authorisation request to the acquirer (which does not lead to a payment).
5. Mercanet records the payment method data in the wallet if the anti-fraud checks are OK and the authorisation is accepted.
6. Mercanet displays the home page containing a confirmation message. Customers can then see their payment method on the home page.
7. Mercanet returns the manual and automatic responses containing the wallet content.
Setting the request
Walletpage is the interface that allows customers to manage their wallets. To enrol a customer for the service via Walletpage, you should populate the fields below:
| Field | Value setting |
|---|---|
| merchantWalletId | Customer unique ID |
| PaymentMeanBrandList | List of the payment methods that you want to offer for payment. |
Please refer to the Walletpage guide corresponding to the selected connector (JSON, POST or SOAP) to learn how to populate the request, depending on your business requirements.
Analysing the response
Mercanet returns a manual and an automatic response. The 2 responses are sent through 2 different URLs. The automatic response is always sent, as soon as the URL has been filled in the wallet management request. The information contained in the manual and automatic responses is strictly identical.
| Status | Response fields | Action to take |
|---|---|---|
| Customer enrolled | walletPaymentMeanDataList and walletCreationDateTime entered by the customer. | Store the following customer details in your customer
database:
|
| Customer not enrolled | walletPaymentMeanDataList not
populated walletCreationDateTime not populated
|
Resubmit a customer enrolment request. |
Enrolling your customer's payment details with In-App
Before you register the means of payment in the wallet, you are first required to check it via a 3-D Secure authentication request and a standard payment request.
Flow description
The registration of a card in the wallet is a 4-step process:
- checking the 3-D Secure enrollment of the customer's card
- redirecting the customer to their bank's ACS
- sending the 3-D Secure authorisation request (with or without payment)
- adding the card in the wallet
Checking the means of payment details
Please refer to the 3-D Secure guide.
Initialising the request for registration of payment details
You initialise the payment using the walletInitialize method. Apart from
the mandatory data of this method, here are the request data you need to
pay attention to.
| Field name | Value setting |
|---|---|
merchantWalletId |
Customer's unique identifier |
sdkOperationName |
ADDCARD |
Analysing the initialisation response from the customer's payment details registration
| Use cases | Response fields | Action to take |
|---|---|---|
| Successful initialisation of the registration request | redirectionStatusCode =
00 |
You send the necessary data to the mobile application for
further card registration:
|
| Invalid initialisation request | redirectionStatusCode = 12,
30 |
One or more data in the request are invalid. Check the
redirectionStatusMessage
field and fix the incorrect value. |
| Mercanet server temporarily unavailable | redirectionStatusCode =
99 |
Resubmit the request. If the issue lasts, please alert BNP Paribas's technical support. |
Setting up the payment details registration request
If the initialisation of the registration request has succeeded, send
the request via the addCard method of the In-App SDK. Apart from the mandatory data of this method, here
are the request data you need to pay attention to.
| Field name | Value setting |
|---|---|
cardExpiryDate |
Value already retrieved. |
cardNumber |
Value already retrieved. |
paymentMeanBrand |
Value already retrieved. |
redirectionData |
Value retrieved as a response to walletInitialize. |
redirectionUrl. |
Value retrieved as a response to walletInitialize. |
Analysing the payment details registration response
| Use cases | Response fields | Action to take |
|---|---|---|
| Card registered in the wallet | inAppResponseCode =
00
|
Display to the customer the confirmation of their successful card registration. |
| Temporary technical issue | inAppResponseCode =
99 |
Resubmit the request. If the issue lasts, please alert BNP Paribas's technical support. |
| Invalid request | inAppResponseCode =
12 |
One or more data in the request are invalid. Check the
errorFieldName field and fix
the incorrect value. |
Paying on Paypage with
The payment phase in mode is possible if the customer has previously registered a payment method in their Mercanet wallet. During the payment kinematic, the customer does not have to re-enter their payment details, they simply select one of the payment methods previously recorded in the wallet and enter the security code.
Depending on the payment means picked by the customer, he can be asked to fill out the card security code from his payment card.
- Get your shop configured with the "OneClick No CSC" option (feel free to contact support teams to get more information)
- Performing the payment with a strong authentication (involves that the card is enrolled into the 3D Secure authentication program);
- Be certain that your acquirer supports this feature
Description
1. You redirect the customer to Paypage, sending the transaction data in the request (amount, currency, etc.), as well as the unique customer ID (merchantWalletId field).
2. Mercanet displays the payment page, the customer provides their payment method, enter the security code, then confirms.
3. Mercanet proceeds with 3-D Secure verification
4. Mercanet makes anti-fraud checks
5. Mercanet sends an authorisation request to the acquirer.
6. Mercanet records the transaction in the back office.
7. Mercanet displays the payment ticket page with a payment confirmation message.
8. Mercanet returns the manual and automatic responses containing the transaction details, including the result of the customer registration in the wallet.
9. Mercanet may or may not send the transaction for remittance, depending on the parameters that you have configured in the payment request.
Setting the request
To offer payment via Paypage, you should fill the fields below:
| Field | Value setting |
|---|---|
merchantWalletId |
Customer unique ID |
fraudData.bypass3DS |
MERCHANTWALLET if you want to deactivate 3-D Secure authentication during a OneClick payment for CB, VISA or MASTERCARD WIP_BANCONTACT if you want to deactivate 3-D Secure authentication during a payment for Bancontact Otherwise not populated |
Please refer to one of the Paypage guide corresponding to the selected connector (JSON, POST or SOAP) to learn how to enter the request, depending on your business requirement.
Analysing the response
Mercanet returns a typical Paypage manual and automatic response.
The fields related to a OneClick payment are as follows:
| Status | Status | Action to take |
|---|---|---|
Transaction accepted The customer uses a payment method already enrolled in the wallet. |
|
Confirm your order for sending |
Transaction accepted The customer chooses to use a payment method not enrolled in the wallet. |
|
Confirm your order for sending |
Transaction refused |
|
Please refer to the Paypage guide corresponding to the selected connector (JSON, POST or SOAP) to analyse the Mercanet response. |
In response to the payment request to the financial establishment, any reply code associated with a fraud risk, or a reply code indicating that the payment method can never be used, will trigger the automatic deletion of the payment method from the wallet. See below for the list of the codes concerned (acquirerResponseCode field):
| Value | Description |
|---|---|
| 04 | Retain the card |
| 07 | Retain the card, special circumstances |
| 14 | Invalid cardholder number |
| 15 | Card issuer unknown |
| 33 | Card expired |
| 34 | Suspected fraud |
| 41 | Lost card |
| 43 | Stolen card |
| 54 | Card expired |
| 57 | Unauthorised transaction for this cardholder |
| 59 | Suspected fraud |
| 63 | Security rules not followed |
Paying with on Office (M2M)
In this paragraph, we do not describe the card enrollment phase, we assume that the customer has already registered his card in Mercanet wallet.
Flows description
A 3-D Secure payment from a customer identifier is made in 4 steps:
- authenticating your customer and the means of payment they select in their wallet
- checking the selected card enrollment
- redirecting the customer to their bank's ACS
- the 3-D Secure authorisation request
Implementation
If your webshop is not a 3-D Secure one, please get in touch with the Mercanet technical support to activate the service.
To implement a 3-D Secure OneClick payment, you must implement the messages received and sent by the "E-commerce server" entity in the above chart.
Step 1: authenticating your customer and selecting their means of payment
You authenticate your customer to find the value of the corresponding merchantWalletId data.
You display them the list of means of payment included in their wallet. If you have not stored this list of means of payment in your information system, you can retrieve it calling a getWalletData request.
The customer selects the card means of payment of their choosing, which allows you to find the paymentMeanId data value.
For the CB/VISA/MASTERCARD/AMEX network's payment means, the CSC entry is not mandatory in case of strong authentication. The next step "Step 2: checking the selected card enrollment" details how to make sure that the selected card is eligible for strong authentication. We assume that your acquirer supports this feature (feel free to contact the support teams for more information).
responseCode = 12. It's up to you to
retry the payment with asking beforehand the customer his card security
codeFor all other payment means, and the payments not processed into a 3D secure context, you must collect the customer's card security code.
Step 2: checking the selected card enrollment
You check the 3-D Secure enrollment of the card with the use of the walletCheckEnrolment function.
Setting the request
In a 3-D Secure context, apart from the mandatory method data, here is the request data you should pay attention to:
| Field name | Population rule |
|---|---|
| amount | Payment amount. The amount is displayed on the holder authentication page. |
| captureDay | Must be 6 or less. If the value is greater than 6, the
Mercanet server forces it to 6. |
| merchantName | Shop name of your website that will be displayed on the
authentication page of the holder's bank. If not filled in,
the name of your shop specified when your shop was registered on
Mercanet will be displayed. |
| merchantReturnUrl | Do not populate, this field is deprecated. |
| merchantUrl | URL of your website that will be displayed on the
authentication page of the holder's bank. If not filled in,
the URL of your shop specified when your shop when registered on
Mercanet will be displayed. |
| merchantWalletId | Value retrieved in the previous step. |
| paymentMeanId | Value retrieved in the previous step. |
| orderChannel | For payments made through the Internet, please set to INTERNET. |
Analysing the response
| Status | Field name | What to do |
|---|---|---|
| Card is 3-D Secure enrolled. |
|
You must redirect the holder to their bank's ACS via the
URL indicated in the redirectionUrl field (see
next step). |
| Card is not 3-D Secure enrolled. |
redirectionStatusCode =
01 |
Proceed to step 5: authorisation request. |
| Webshop is not enrolled in the 3-D Secure programme. |
redirectionStatusCode =
40 |
Please contact BNP Paribas's technical support. |
| Technical error preventing the 3-D Secure process from running smoothly. | redirectionStatusCode = 10,
80, 89 |
Proceed to step 5: authorisation request. |
| Transaction is not valid. |
redirectionStatus =
12 |
One or more data in the query is not correct. Check the
errorFieldName field and fix
the wrong value. |
| Expired card |
redirectionStatus = not
filled in |
Ask your customer to select another means of payment or to enter a new means of payment. |
| Inexisting wallet or mean of payment | responseCode |
Check the field merchantWalletId and/or the
field paymentMeanId |
| Secret key or key version is not valid | responseCode = 34 |
Check the secret key used (field secretKey) and the key
version (field keyVersion) |
| Mercanet Server temporarily unavailable | responseCode = 99 |
You can submit the request a second time. If the error persists, please notify BNP Paribas Technical Support |
Step 3: redirecting the customer to their bank's ACS
If the card is enrolled, you must redirect the customer to the URL of the ACS of their bank, retrieved in the previous step in the redirectionUrl. In a passive authentication case, you must also perform this step, even if the customer will not actually be redirected to the ACS of their bank. bank.
Please refer to paragraph POST form to ACS of the Office (M2M) JSON documentation to implement this message.
Step 4: retrieving customer authentication data
At the end of the authentication process, the client is redirected to your website via an HTTP redirect. The result of the authentication is retrieved through the PARes field.
Please refer to paragraph POST form to ACS of the Office (M2M) JSON documentation to implement this message.
If the customer abandons the authentication process (closes the browser, never gets redirected to your website), do not transmit the authorisation request, do not deliver the order.
Step 5: 3-D Secure authorisation request
After authentication (including passive or failed authentication), when the customer returns to your e-commerce site, transmit the 3-D Secure authorization request via the function cardValidateAuthentificationAndOrder.
If authentication fails, Mercanet does not transmit authorisation request to your acquirer, the payment is necessarily refused.
Paying with on In-App
In this paragraph, we do not describe the card enrollment phase, we assume that the customer has already registered his card in Mercanet wallet
Flows description
A 3-D Secure payment from a customer identifier is made in 4 steps:
- authenticating your customer and the means of payment they select in their wallet
- checking the selected card enrollment
- redirecting the customer to their bank's ACS
- the 3-D Secure authorisation request
Implementation
If your shop does not have 3-D Secure authentication, please contact the Mercanet technical support to activate the service.
In order to accept a 3-D Secure card payment, you have to implement the messages received and transmitted by the entities named "E-Commerce Server" and "Mobile App" in the diagram above.
Step1: Authenticating your client and selecting the payment mean
You authenticate your client to retrieve the value to provide in the
field merchantWalletId.
You display the list of payment means contained in his wallet. If you
have not stored this list of payment means in your information system, you
can retrieve it using the walletInitialize function with
the sdkOperationName
GETWALLETDATA.
He selects the card of his choice, which allows you to retrieve the
value of the data paymentMeanId
Setting the walletInitialize request
Besides mandatory request data, here is the request data that you need to pay attention to:
| Field name | Population rule |
|---|---|
merchantWalletId |
Wallet Id of the customer |
sdkOperationName |
GETWALLETDATA |
Analysing the response
When receiving the response, before analysing it and following the advice in the table below, check the seal. The recalculated seal must be the same as the one received.
| Status | Field name | What to do |
|---|---|---|
| Wallet Initialize success | redirectionStatusCode =
00 |
You transmit the data necessary for the payment to be
processed to the mobile application:
|
| Invalid wallet initialisation request | redirectionStatusCode = 12,
30 |
One or more data in the request are not correct. Check the
redirectionStatusMessage
field and fix the incorrect value. |
| Mercanet server temporarily unavailable | redirectionStatusCode =
99 |
Resubmit the request. If the issue lasts, please alert BNP Paribas's technical support. |
Setting the getWalletData request
The data returned in the walletInitialize response are sent to the getWalletData request
Analysing the getWalletData response
| Use case | Response fields | Action to take |
|---|---|---|
| Successful initialisation of the payment | redirectionStatusCode =
00 |
You display the list of payment means returned:
|
| Wallet not found | inAppResponseCode =
25 |
Check the value of merchantWalletId |
Step 2 : payment initialisation
To initialize the payment you have to call the orderInitialize method.
Setting the oneclick request
In a 3-D Secure context, besides the mandatory method data, here are the request data you need to pay attention to.
| Field name | Sample field population |
|---|---|
| amount | Payment amount. The amount is displayed on the holder authentication page. |
| merchantWalletId | Value retrieved in the previous step. |
sdkOperationName |
THREEDSECUREANDWALLETORDER |
Analysing the response
| Use case | Response fields | Action to take |
|---|---|---|
| Successful initialisation of the payment | redirectionStatusCode =
00 |
You display the payment data collection screen in your
mobile application. You transmit the data necessary for the
payment to be processed to the mobile application:
|
| Invalid initialisation request | redirectionStatusCode = 12,
30 |
One or more data in the request are not correct. Check the
redirectionStatusMessage
field and fix the incorrect value. |
| Mercanet server temporarily unavailable | redirectionStatusCode =
99 |
Resubmit the request. If the issue lasts, please alert BNP Paribas's technical support. |
| Duplicated transaction | redirectionStatusCode =
94 |
The transactionReference or the
transactionId is already used
by another request from your shop. Resubmit the request with
another transaction reference. |
Step 3: checking the selected card enrollment
You check the 3-D Secure enrollment of the card with the use of the walletCheckEnrolment function.
Setting the request
In a 3-D Secure context, besides the mandatory method data, here are the request data you need to pay attention to.
| Field name | Sample field population |
|---|---|
paymentMeanId |
Value retrieved in the previous step. |
Analysing the response
| Use case | Response fields | What to do |
|---|---|---|
| Card is 3-D Secure enrolled. | redirectionStatusCode =
00 |
You must redirect the holder to their bank's ACS via the
URL indicated in the redirectionUrl field (see
next step). |
| Card is not 3-D Secure enrolled. | redirectionStatusCode =
01 |
Proceed to step 6: authorisation request. |
| Technical error preventing the 3-D Secure process from running smoothly. | redirectionStatusCode = 10,
80, 89, 99 |
Proceed to step 6: authorisation request. |
| Webshop is not enrolled in the 3-D Secure programme. | responseCode = 40redirectionStatusCode =
40 |
Please contact BNP Paribas's technical support. |
| Transaction is not valid. | redirectionStatusCode =
12 |
One or more data in the request is not correct. Check the
errorFieldName field and fix
the incorrect value. |
| Card is not valid. | redirectionStatusCode =
14 |
The details of the means of payment are not correct, go back to step 1 and ask the cardholder to enter their payment information again. |
| Wallet or payment mean not found. | redirectionStatusCode =
25 |
One or more data in the request is not correct. Check the
errorFieldName field or the
errorFieldName field and fix
the incorrect value. |
Step 4: redirecting the customer to their bank's ACS
If the card is enrolled, you must redirect the customer to their bank's
ACS URL that was retrieved in the previous step, in the authentRedirectionUrl field. In the
case of passive authentication, you must also perform this step, even if
the customer will not really be redirected to their bank's ACS.
Please refer to the paragraph relating to the redirection to the ACS of the
In-App documentation to know how to implement this
message.
Step 5: retrieving customer authentication data
At the end of the authentication process, the customer is redirected to
your application using an HTTP redirection. The authentication result is
retrieved through the PARes field.
Please refer to the paragraph back from the ACS of the Office (M2M) JSON documentation to know how to implement this message.
If the customer cancels the authentication process (closes their browser and is never redirected to your website), do not submit the authorisation request, do not ship the order.
Step 6: 3-D Secure authorisation request
Upon the customer's return to your e-commerce website after they have
been authenticated (including for passive authentication), submit the 3-D
Secure authorisation request via the cardValidateAuthenticationAndOrder
method.
If the authentication of the customer has failed,Mercanet does not send an authorisation request to your acquirer, the payment is necessarily refused.
Setting the payment request
In a 3-D Secure context, besides the mandatory method data, here are the request data you need to pay attention to.
| Field name | Population rule |
|---|---|
paResMessage |
If you have redirected the cardholder to their bank's ACS,
because their card is enrolled: please populate this field using
the data from the paResMessage field,
previously URL encoded, received from the ACS.If you have not
redirected the cardholder to their bank's ACS, because their card
is not enrolled, do not populate this field. |
Analysing the response
Please refer to the In-App documentation.
Crediting the customer on Office (M2M)
You can credit a customer based on their User ID without reference to an initial debit transaction.
Description
1. You send a credit request using the walletCreditHolder method, sending the transaction data in the request (amount, currency, etc.), as well as the unique customer ID (merchantWalletId and paymentMeanId fields).
2. Mercanet retrieves the customer payment details stored and sends an authorisation request to the acquirer
3. Mercanet records the transaction in the back office.
4. Mercanet returns the response to the credit request.
5. Mercanet may or may not send the transaction for collection, the same evening.
Setting the request
To credit a customer using the walletCreditHolder method, you should populate the fields below:
| Field | Value |
|---|---|
| merchantWalletId | Customer unique ID |
| paymentMeanId | Payment method ID |
Please refer to the Office (M2M) guide corresponding to the selected connector (JSON or SOAP) to learn how to populate the other fields for the request, depending on your business requirements.
Analysing the response
| Status | Response fields | Action to take |
|---|---|---|
| Transaction accepted | responseCode = 00 | Check the next day in the transaction report that the credit has actually been sent. (transactionStatus =
CREDITED) |
| Transaction refused | responseCode = XX | Please refer to the Office (M2M) guide corresponding to the selected connector (JSON or SOAP) to analyse the Mercanet response. |
Managing a customer's payment methods and account
With Paypage
Description
During a purchase on the Paypage interface, the customer can interact directly with their saved payment methods. The following features are available:
- changing the name of the saved payment method (not available for expired payment method).
- deleting a payment method.
changing the name of the saved payment method (not
available for expired payment method).
deleting a payment method.
Implementation
For the customer to be able to manage the content of their wallet during a purchase, no further development is required, this feature is available by default.
However, it is possible to remove this feature. To do this, please contact technical support.
With Walletpage
Description
The Walletpage interface for account management allows customers to manage their wallets independently. The following features are available:
- viewing accounts contents
- adding new payment methods to an existing account
- changing the name of a payment method already enrolled
- deleting a payment method in a account
- deleting an account
Setting the request
All management features are available to the user by default. However, it is possible to reduce the scope of these features, by indicating the list of features required in the walletActionNameList field.
For the wallet management you should populate the fields below:
| Field | Value |
|---|---|
merchantWalletId |
Customer ID |
walletActionNameList |
Value like this: SIGNOFF,UPDATEPM |
Please refer to the Walletpage guide corresponding to the selected connector (JSON, POST or SOAP) to learn how to populate the request, depending on your business requirements.
Analysing the response
| Status | Response fields | Action to take |
|---|---|---|
| Customer removed | walletPaymentMeanDataList not populated | |
| Customer not removed | walletPaymentMeanDataList populated | You can update your information system with the new wallet content. |
With Office (M2M) and Office Batch
Overview
The "Wallet" service of the Office (M2M) interface allows you to manage the content of your customers wallets. The following features are available:
- obtaining the complete contents of a OneClick account
- obtaining details on the payment method contained in a account
- creating a new account
- deleting a account
- adding new payment methods to an existing account
- updating a payment method of a account
- deleting a payment method from a account
Using the Office (M2M) or Office Batch interfaces, you should create and host the wallet management pages to allow your customers to manage their account.
Viewing the content of an OneClick account with Office (M2M)
Office (M2M) allows you to view customer details through a getWalletData request.
- Setting the requestTo view the content of a wallet with the getWalletData method, you should populate the fields below:
Field Value merchantWalletID Customer identifier Please refer to the Office (M2M) guide corresponding to the selected connector (JSON or SOAP) to learn how to populate the other fields for the request, depending on your business requirements.
- Analysing the response
Status Response fields Action to take Customer found in the wallet database walletReponseCode = 00
walletPaymentMeanDataList filled with the payment methods recorded in the wallet
The customer exists in the wallet.
Analyse the walletPaymentMeanDataList field to access the customer payment method details- paymentMeanBrand
- paymentMeanId
- maskedPAN
- PANExpiryDate
Customer not found in the wallet database walletReponseCode = 25
The account has been deleted or was not created. Other refusals walletReponseCode = xx
Please refer to the Office (M2M) guide corresponding to the selected connector (JSON or SOAP) to analyse the Mercanet response.
Modifying the alias of payment method of an OneClick account with Office (M2M)
Office (M2M) allows you to modify the alias of a customer payment method via the updatePaymentMean request.
- Setting the requestTo modify a payment method via the updatePaymentMean request, you should populate the fields below:
Field Value setting merchantWalletID Customer identifier paymentMeanId Sequence number of the payment method paymentMeanAlias New payment method alias
Please refer to the Office (M2M) guide corresponding to the selected connector (JSON or SOAP) to learn how to populate the other fields for the request, depending on your business requirements.
- Analysing the response
| Status | Response fields | Action to take |
|---|---|---|
| Alias modified | walletReponseCode = 00 walletActionDateTime populated |
|
| Customer not found in the wallet database | walletReponseCode = 25 |
The account doesn't exist. |
| Other refusals | walletReponseCode = xx |
Please refer to the Office (M2M) guide corresponding to the selected connector (JSON or SOAP) to analyse the Mercanet response. |
Deleting a payment method of an account with Office (M2M)
Office (M2M) allows you to delete a customer payment method via the deletePaymentMean request.
- Setting the request
To modify a payment method via the deletePaymentMean method, you should populate the fields below:
| Field | Value setting |
|---|---|
| merchantWalletID | Customer identifier |
| paymentMeanId | Sequence number of the payment method |
Please refer to the Office (M2M) guide corresponding to the selected connector (JSON or SOAP) to learn how to populate the other fields for the request, depending on your business requirements.
- Analysing the response
| Status | Response fields | Action to take |
|---|---|---|
| Payment method deleted | walletReponseCode = 00 walletActionDateTime populated |
|
| Customer/payment method not found in the wallet database | walletReponseCode = 25 |
|
| Other refusals | walletReponseCode = xx |
Please refer to the Office (M2M) guide corresponding to the selected connector (JSON or SOAP) to analyse the Mercanet response. |
Deleting a customer with Office (M2M)
Office (M2M) allows you to delete a customer via the signOff request.
- Setting the request
To delete a wallet with the signOff method, you should populate the fields below:
| Field | Value setting |
|---|---|
| merchantWalletID | Customer identifier |
Please refer to the Office (M2M) guide corresponding the selected connector (JSON or SOAP) to learn how to populate the other fields for the request, depending on your business requirements.
- Analysing the response
| Status | Response field | Action to take |
|---|---|---|
| Customer deleted | walletReponseCode = 00 | You can update your information system. |
| Customer not deleted | walletReponseCode = xx | Please refer to the Office (M2M) guide corresponding to the selected connector (JSON or SOAP) to analyse the Mercanet response. |
With Mercanet Back Office
You can delete a payment method for a customer account via the Mercanet Back Office. This feature is protected by the access rights assigned to you upon registration. If you need this feature, but you don't have the access rights, please contact technical support.
Anticipating the customers payment methods expiry
On a monthly basis, you will receive by email or SFTP an expired cards report. This report references customers whose payment methods are due to expire in 3 months.
Based on this expired cards report, you can alert your customers to update the payment methods recorded in their wallets.
Please note that you won't need this file to know the expiry dates of your customers payment methods. Indeed, when a customer enrols, you will receive information in response that you can store in your information system:
- ID for the payment method in the wallet (paymentMeanId field)
- Payment method brand (paymentMeanBrand field)
- Expiry date (panExpiryDate field)
- Masked PAN (maskedPan field)
For details of the expired cards report content, please view the "Report Description" document.
5 steps to getting started with
Step 1 - Subscribing to the service
Your shop has not been registered to Mercanet.
If your shop is not yet registered, you should complete the registration form (requesting the service) and return it to BNP Paribas.
Your shop is already registered to Mercanet.
If your shop is already registered to Mercanet, you should ask BNP Paribas to activate the service.
Configuration data of the service.
To access the service, you should contact technical support and provide the following information:
- do you want to receive the expired cards report
- if a customer database is shared between several shops of the same brand, please provide the brand ID
Step 2 - Implementing the service
Step 3 - Testing the service in the acceptance environment
Once the implementation of the Mercanet connectors is complete, you can run tests to validate your OneClick integration.
| Test data | |
|---|---|
| merchantId | 201000076690001 |
| secret key | p64ifeYBVIaRcjaWoahCiw9L8wokNLqG2_YOj_POD4g |
| key version | 1 |
| test cards | see Test cards page |
| Server | Test URL |
|---|---|
| Paypage POST | https://payment-web-mercanet.test.sips-services.com/paymentInit |
| Paypage JSON | https://payment-web-mercanet.test.sips-services.com/rs-services/v2/paymentInit |
| Paypage SOAP | https://payment-web-mercanet.test.sips-services.com/services/v2/paymentInit |
| WalletPage POST | https://payment-webinit.mercanet.test.sips-services.com/walletManagementInit |
| WalletPage JSON | https://payment-web-mercanet.test.sips-services.com/rs-services/v2/walletManagementInit |
| WalletPage SOAP | https://payment-web-mercanet.test.sips-services.com/services/v2/walletManagementInit |
| Office | https://office-server-mercanet.test.sips-services.com/ |
Step 4 Validating the service in production environment
You can now validate the connection to Mercanet in production environment.
Prior to this, we recommend that you isolate your website from the public, to prevent customers from making transactions during this validation phase.
You should change the URL to connect to the production Mercanet server, using the IDs received during registration for the merchantId, secretKey and keyVersion.
| URL Mercanet | URL of the Mercanet payment server received by email. |
| MerchantId | Shop ID received by email. |
| SecretKey | Secret key that you get from the Mercanet Téléchargement extranet. |
| KeyVersion | Version of the secret key retrieved from Mercanet Téléchargement (logically 1 for the 1st key). |
If you want to customise your payment pages or wallet management pages, please follow the procedure described in the Custompages document.
How to validate customer enrollment
Immediately
- Submit an enrolment request based on the enrolment scenario that you have chosen (Paypage, Office (M2M) or Walletpage).
How to validate customer debits
Immediately
- Submit a debit request based on the debit scenario that you have chosen (Mercanet, Paypage or Office (M2M)).
- View the transaction via Mercanet Back Office, using the transactionReference or S10transactionId.
The next day
- Check that the transaction appears in the transactions report.
- Check your business account to make sure that the operation has been credited.
- If you wish, you can refund the transaction via Mercanet Back Office.
Two days later
- Check that the refund operation appears in the operations report.
- Check the debit on your merchant account after the refund.
How to validate customer management
Immediately
- Submit one or several wallet management requests based on the debit scenario that you have chosen (Paypage, Walletpage, Office (M2M) or Mercanet Back Office).
Step 5 - Launching the service in production environment
Once the transition in production environment has been validated, you can open your website to the public to enable your customers to use the service and to register.
Customer enrollment
During the day
- Monitor acceptance rates (number of responseCode 00 per total number of transactions).
- Check the nature of non-banking refusals.
- Technical problem: responseCode 90, 97, 99
- Fraud: responseCode 34, 3-D Failure
- Maximum number of payment attempts reached: responseCode 75
The next day
- Check that all transactions processed (accepted and refused) appear in the transactions report.
- Check the operations you have made and remittances (if you have chosen this report option) in the operations report.
Customer debits
When you submit your first customer debits via Paypage or Office (M2M):
- Monitor acceptance rates (number of responseCode00 per total number of transactions).
- Check the nature of non-banking refusals.
- Technical problem: responseCode 90, 97, 99
- Acquirer fraud: responseCode 34
