Walletpage POST

To search in the page use Ctrl+F on your keyboard

Give a feedback about this page

The last interfaceVersion is HP_3.0

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 Walletpage POST solution up to live operations.

Who does this document target?

This document is intended for merchants wishing to subscribe to the Mercanet offer and use a connector based on HTTPS exchanges in POST mode between their websites and the Mercanet servers, so as to enable their customers to manage their OneClick or subscriber wallets.

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:

Functional presentation
Functionality set-up guide
OneClick payment guide
Subscription payment

Prerequisites

Knowledge of standards related to web programming languages used today, such as Java, PHP or .Net, is necessary to develop a connection to Walletpage POST.

Note: all code sections in this document are provided as samples, you will need to adapt them to your website for them to be fully operable.

Secret key management

Upon your subscription, BNP Paribas provides a secret key on the Mercanet Téléchargement extranet that will allow you to secure exchanges between your website and the Mercanet server.

You are responsible for looking after this key and should take all measures to:

restrict access to the key
safeguard it by encrypting it
never copy it onto a non-secure disc or device
never send it (via e-mail or regular mail) in a non-secure method

A secret key compromised (and used by a malicious third party) might disrupt the regular operation of your shop and might in particular generate unauthorised sales or cash transactions (e.g. refunds).

IMPORTANT: in the event that a secret key is compromised, you are required to ask as quickly as possible for its revocation then for its renewal via the Mercanet Téléchargement extranet (please refer to the « Key management » section in the relevant documentation).

The very same secret key is used on the various Paypage, Office (M2M), In-App and Walletpage connectors.

IMPORTANT: a secret key is associated with a version. After getting a new secret key, you must modify your request and populate the keyVersion field with the new version, otherwise you will get an answer code 34 (suspected fraud).

Understanding customer wallet management with Walletpage POST

The wallet management process works as follows:

picture on the general principle of a wallet management process

1. When the customer initiates the wallet management step, a request must be sent to the Walletpage POST connector the URL of which is provided by BNP Paribas. The request is then checked, and encrypted if it is valid (it is named RedirectionData in the system). The request is sent through a POST form via HTTPS. Any other solution that can sends such requests also works.

2. The merchant's website redirects the calling application to the wallet management interface, with the encrypted request. The latter is decrypted, and Walletpage enables the customer to perform various operations on their wallet. For the customer to be able to return to your site, a response is created and sent to the response URL provided in workflow No. 1.

There are two independent response notifications:

3. The wallet management server sends the manual response to the manual response URL using the HTTP(S) POST method. This URL is supplied in the wallet management request when the customer clicks on the “Back to shop” button or link on the wallet management page. This is why the normal response URL is also the page the customer is redirected to when wallet management operations are over. As nothing guarantees that the customer will click on this link, the receipt of the manual response cannot be guaranteed either.

4. Automatic responses are sent separately from manual responses. They also use the HTTP(S) POST requests sent by the wallet management servers, but this time, they use the automatic response URL specified in the wallet management request. You will receive the response when the customer clicks on the “Back to shop” button or if the wallet management session expires.

Getting started with Walletpage POST in 5 steps

Step 1: subscribing to the service

If your shop has not been registered yet, you must fill in the registration form (asking for the subscription service or the OneClick service) sent by BNP Paribas and send it back to them.

If your shop has already been registered with Mercanet, you need to ask the technical contact to activate the subscription service or the OneClick service.

Tip: if your wallet database is shared between several shops, you must specify it in your registration form or tell it to the technical support team.

If this information is not supplied, Mercanet defines a dedicated wallet database for your shop.

Step 2: managing your customers' wallets

The wallet management request is a HTTPS POST request sent to the wallet management connector. You must send the request via an HTML form using the POST method.

Generating the wallet management request

Three essential data are specified in wallet management requests:

Data element name	Description
Data	Contains all the information related to the management of the wallet.
InterfaceVersion	Defines the version of the request and of the response exchanged with the Mercanet server.
Seal	Used to validate the integrity of data exchanged. The Seal data element is computed using the Data data element and the secret key.

Additional optional data are available:

Data element name	Description
Encode	Specifies the method used to encode the Data data element.
SealAlgorithm	Specifies the algorithm used to compute the Seal data element.

Data field syntax

The Data field is structured in compliance with the following format:

<fieldName1>=<fieldValue1>|<fieldName2>=<fieldValue2>|…|<fieldNameN>=<fieldValueN>

All fields required for the wallet management (see details in the data dictionary) should be included in the character string. The order of the fields is irrelevant.

Sample wallet management request:

merchantId=011223744550001|normalReturnUrl=http://www.normalreturnurl.com|merchantWalletId=w5346|keyVersion=1|requestDateTime=2015-08-05T16:18:09.415+02:00

A field can have several values:

..|fieldName=value1,value2, … ,valueX|…

Sample paymentMeanBrandList field with VISA and MASTERCARD as values:

…|normalReturnUrl=https://www.normalreturnurl.com|merchantId=201010314150000|keyVersion=1|merchantWalletId=2|paymentMeanBrandList=VISA,MASTERCARD|requestDateTime=2017-05-26T11:09:01.487+02:00|keyVersion=1|…

If the field is a container, you must use a dot between the container name and the field name:

..|Container.fieldName1=fieldValue1|container.fieldName2=fieldValue2|……

Sample customerContact field containing the customer's e-mail (me@email.com), last name and first name (John Smith):

…|customerContact.email=me@email.com|customerContact.firstname=John|customerContact.lastname=Smith|…

Encoding the Data field

The Data field should be encoded using base64 or base64Url if it contains special characters (such as accented characters).

Note: since the signature is computed using the Data field, please note that it is the encoded Data value which is used for the request signature.

Securing the request

The request includes the transaction parameters and is sent by the customer's web browser. Theoretically, a third party can intercept the request and modify its content before the data reaches the payment server.

Therefore it is necessary to strengthen security so as to ensure the integrity of the parameters of the transaction sent. The Mercanet solution meets this challenge by exchanging signatures. An effective signature control comprises two elements:

the integrity of the request and response messages
the issuer and recipient authentication, as they share the same secret key

IMPORTANT: if your secret key is compromised, or if you suspect this might be the case, you should always go to Mercanet Téléchargement to request a new one.

How to secure the request

The request is secured by calculating the hash value in line with the transaction parameters. Then, the secret key is added to it. All character strings are converted to UTF-8 before being hashed.

The hashing algorithm generates an irreversible result. When such a message is received, the recipient needs to recalculate the hash value and compare it with the one received. Any difference indicates that the data exchanged was falsified, or that the recipient and the issuer do not share the same secret key.

The result must be sent in hexadecimal format in the data element named Seal.

Calculating the Seal data element

HMAC-SHA algorithm

The value of the Seal data element is computed as follows:

Content of the Data field sent in the POST form. Giving the data, mentioned in the examples below.
UTF-8 encoding of data from the previous result.
HMAC with SHA256 encryption of bytes obtained with the secret key.

This procedure can be summarised as follows:

HMAC-SHA256( UTF-8(Data), UTF-8(secretKey))

Attention: by default, the seal is calculated with the SHA-256 algorithm.

For the seal to be computed with the HMAC-SHA-256 algorithm, the use of which we strongly recommend, the input parameters of the request must include the sealAlgorithm field populated with the following value: “HMAC-SHA-256”.

Hmac Sha256 sample code

Sample Hmac Sha256 encoding in Php 5
```
<?php

…

// Seal computation thanks to hash sorted data hash with merchant key

$data_to_send= utf8_encode($data)

$seal=hash_hmac('sha256', $data_to_send, $secretKey);

…
…

?> 
```
data_to_send and secretKey must use a UTF-8 character set. Please refer to the utf8_encode function for the conversion of ISO-8859-1 characters in UTF-8.

Sample Hmac Sha256 encoding in Java


import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class ExampleHMACSHA256 {

/**
 * table to convert a nibble to a hex char.
 */
static final char[] hexChar = {
   '0' , '1' , '2' , '3' ,
   '4' , '5' , '6' , '7' ,
   '8' , '9' , 'a' , 'b' ,
   'c' , 'd' , 'e' , 'f'};

/**
 * Fast convert a byte array to a hex string
 * with possible leading zero.
 * @param b array of bytes to convert to string
 * @return hex representation, two chars per byte.
 */
public static String encodeHexString ( byte[] b )
   {
   StringBuffer sb = new StringBuffer( b.length * 2 );
   for ( int i=0; i<b.length; i++ )
      {
      // look up high nibble char
      sb.append( hexChar [( b[i] & 0xf0 ) >>> 4] );

      // look up low nibble char
      sb.append( hexChar [b[i] & 0x0f] );
      }
   return sb.toString();
   }

/**
 * Computes the seal
 * @param Data the parameters to cipher
 * @param secretKey the secret key to append to the parameters 
 * @return hex representation of the seal, two chars per byte.
 */
public static String computeSeal(String data, String secretKey) throws Exception
{
  Mac hmacSHA256 = Mac.getInstance("HmacSHA256");
  SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
  hmacSHA256.init(keySpec);

  return encodeHexString(hmacSHA256.doFinal(data.getBytes()));
}

/**
 * @param args
 */
public static void main(String[] args) {
try {
System.out.println (computeSeal("parameters", "key"));
} catch (Exception e) {
e.printStackTrace();
}
}

}

Sample Hmac Sha256 encoding in .net

(Carried out using a simple form called "Form1" containing two text fields to enter data and txtSecretKey, and another field to display lblHEX).


using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using System.Security.Cryptography;

namespace ExampleDotNET
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }

        private void cmdGO_Click(object sender, EventArgs e)
        {
            String sChaine = data.Text;
            UTF8Encoding utf8 = new UTF8Encoding();
            Byte[] encodedBytes = utf8.GetBytes(sChaine);
        
            byte[] shaResult;
            
            HMAC hmac = new HMAC.Create("HMACSHA256");
            var key = "YourSecretKey";
            hmac.Key = utf8.GetBytes(key); 
            hmac.Initialize();

            shaResult = hmac.ComputeHash(encodedBytes);

            lblHEX.Text = ByteArrayToHEX(shaResult);
        }

        private string ByteArrayToHEX(byte[] ba)
        {
            StringBuilder hex = new StringBuilder(ba.Length * 2);
            foreach (byte b in ba)
                hex.AppendFormat("{0:x2}", b);
            return hex.ToString();
        }

    }
}

Seal calculation validation

Once you have set up your seal calculation, here is a sample request to help you verify that you find the correct seal:

automaticResponseURL=https://automatic-response-url.fr/|normalReturnUrl=https://normal-return-url/|merchantId=011223344550000|keyVersion=1|merchantWalletId=wallet01|requestDateTime=2018-08-08T16:29:19.619+02:00|customerContact.email=customer@email.com

For the above request, with a HMAC-SHA-256 hash algorithm and the following secret key:

secret123

The expected seal is:

406fa400c74ab8a2c4ad2801ec9d216991a8af4751059b3766157914cddf7912

SHA-256 algorithm

The value of the Seal data element is computed as follows:

Concatenation of the Data field element and of the secret key (encoded if the corresponding option is selected).
UTF-8 encoding of the data constituting the result of the previous operation.
SHA256 hashing of bytes obtained.

This procedure can be summarised as follows:

SHA256( UTF-8(Data+secretKey ) )

Sample Sha256 code

Sample Sha256 encoding in Php 5

<?php
echo hash('sha256', $data.$secretKey);
?>

The UTF-8 character set should be used for the Data and secretKey data. To convert ISO-8859-1 to UTF-8, use the utf8_encode function.

Sample Sha256 encoding in Java

import java.security.MessageDigest;

public class ExampleSHA256 {

/**
 * table to convert a nibble to a hex char.
 */
static final char[] hexChar = {
   '0' , '1' , '2' , '3' ,
   '4' , '5' , '6' , '7' ,
   '8' , '9' , 'a' , 'b' ,
   'c' , 'd' , 'e' , 'f'};

/**
 * Fast convert a byte array to a hex string
 * with possible leading zero.
 * @param b array of bytes to convert to string
 * @return hex representation, two chars per byte.
 */
public static String encodeHexString ( byte[] b )
   {
   StringBuffer sb = new StringBuffer( b.length * 2 );
   for ( int i=0; i<b.length; i++ )
      {
      // look up high nibble char
      sb.append( hexChar [( b[i] & 0xf0 ) >>> 4] );

      // look up low nibble char
      sb.append( hexChar [b[i] & 0x0f] );
      }
   return sb.toString();
   }

/**
 * Computes the seal
 * @param Data the parameters to cipher
 * @param secretKey the secret key to append to the parameters 
 * @return hex representation of the seal, two chars per byte.
 */
public static String computeSeal(String Data, String secretKey) throws Exception
{
  MessageDigest md = MessageDigest.getInstance("SHA-256");
  md.update((Data+secretKey).getBytes("UTF-8"));

  return encodeHexString(md.digest());
}

/**
 * @param args
 */
public static void main(String[] args) {
try {
System.out.println (computeSeal("parameters", "key"));
} catch (Exception e) {
e.printStackTrace();
}
}
}

Sample Sha256 encoding in .NET

Completed using a simple form called "Form 1" containing two text fields to be filled in: data, txtSecretKey and another one to be displayed: lblHEX.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using System.Security.Cryptography;

namespace ExampleDotNET
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }

        private void cmdGO_Click(object sender, EventArgs e)
        {
            String sChaine = data.Text + txtSecretKey.Text;
            UTF8Encoding utf8 = new UTF8Encoding();
            Byte[] encodedBytes = utf8.GetBytes(sChaine);
        
            byte[] shaResult;
            SHA256 shaM = new SHA256Managed();
            shaResult = shaM.ComputeHash(encodedBytes);

            lblHEX.Text = ByteArrayToHEX(shaResult);
        }

        private string ByteArrayToHEX(byte[] ba)
        {
            StringBuilder hex = new StringBuilder(ba.Length * 2);
            foreach (byte b in ba)
                hex.AppendFormat("{0:x2}", b);
            return hex.ToString();
        }

    }
}

Sample wallet management request

Below is a sample form with the Data field unencoded:

<form method="post" action="https://url.to.sips.server/walletManagementInit">
    <input type="hidden" name="Data" value=" merchantId=011223744550001|normalReturnUrl=http://www.normalreturnurl.com| merchantWalletId=w53465|keyVersion=1|requestDateTime=2015-08-05T16:18:09.415+02:00 ">
    <input type="hidden" name="InterfaceVersion" value="HP_2.4">
    <input type="hidden" name="Seal" value="21a57f2fe765e1ae4a8bf15d73fc1bf2a533f547f2343d12a499d9c0592044d4">
    <input type="submit" value="Gérer son wallet">   
</form>

Processing wallet management initialisation errors

All fields received by Walletpage POST through the connector are checked individually. The table below lists the error messages that might be displayed during this step, and the solutions to be implemented.

Note: messages are displayed on the simulation platform to help you validate the integration of your website. For security reasons, much simpler error messages are displayed on the production platform. Example: "Error when processing the request. Contact your merchant".

Message	Cause	Solution
Unknown interface version: <version>	The <version> value in the InterfaceVersion field is unknown.	Check the interface version in this user guide.
Invalid keyword: <fieldName>= <fieldValue>	The <fieldName> field is not expected in the request.	Check the field names in the sections below and in the data dictionary.
Invalid field size: <fieldName>= <fieldValue>	The <fieldName> field is of incorrect length.	Check the field length in the data dictionary.
Invalid field value: <fieldName >= <fieldValue>	The value of the <fieldName> field is not correct.	Check the values available for this field in the data dictionary.
Mandatory field missing: <fieldName >	The <fieldName> field is missing in the request.	Check the mandatory fields of the request in the sections below.
Unknown security version: <version>	The <version> value in the keyVersion field is unknown.	Check the versions of keys available in Mercanet Téléchargement.
Invalid signature	The checking of the of the request seal has failed. This may be caused by an incorrect computing of the seal data or may indicate the falsification of some fields after the computing of the signature.	Check that the Seal is computed as indicated in the above section. If it is, ask for a new secret key via Mercanet Téléchargement because the request has been falsified.
<Other messages>	In the case of technical errors, various messages may be displayed.	Please contact the technical support.

Populating the request fields

The request and the response of the walletManagementInit method are described on this page.

Setting up the wallet management request

Here is an example of how to set up the wallet management request for each funtionality available in Walletpage POST (the details of these functionalities are described in the Functionality set-up guide, and Subscription payment).

Restriction of customer functionalities for wallet management

By default, the customer has access to all the wallet management functionalities. To restrict access, you must specify the list of desired functionalities in the WalletActionNameList field (as in the example below to only allow to add or modify payment methods in one's wallet):

..| |walletActionNameList=ADDPM,UPDATEPM |..

Dynamic restriction of means of payment

The means of payment that will be available for addition to the wallet must be filtered using the paymentMeanBrandList field:

..|paymentMeanBrandList=VISA,PAYPAL|..

Customer's wallet identification

The customer's wallet ID must be populated in the merchantWalletId field.

…|merchantWalletId=1205987|..

Provider acting on behalf of a merchant

The provider's ID must be passed in the intermediateServiceProvider field of the request, and the provider's secret key must be used to calculate the Seal field:

..|intermediateServiceProviderId=241591|..

Response processing

There are two types of responses. Although the protocol, format and content of both responses are identical, the latter must be managed differently because they meet different needs.

Responses are HTTP(S) POST responses sent to the normalReturnUrl (mandatory) and automaticResponseUrl (optional) URLs specified in the request.

You must set up the system that will decode these responses so you can know the result of the request.

The following four data are defined in the responses:

Field name	Comments/rules
Data	Fields concatenation in the response.
Encode	Type of encoding used to encode the Data field. This field is populated using the responseEncoding field from the request.
Seal	Response message signature.
InterfaceVersion	Connector interface version.

IMPORTANT: It is important not to sort the content of the Data field to calculate the Seal of the response. Keep the fields in the sequence you received them.

If the value of the Encode field is “base64” or “base64url”, the Data field must be encoded using Base64/Base64Url so the concatenated string of fields is reconstructed. The concatenated string is structured as follows: key1=value1|key2=value2, etc. The seal (Seal field) of both responses is hashed with the same algorithm as the one supplied as input in the sealAlgorithm field. If no value was defined, SHA-256 is used by default.

IMPORTANT: for a seal to be computed with the HMAC-SHA-256 algorithm, the input parameters of the request must include the sealAlgorithm field populated with the following value: “HMAC-SHA-256”.

The value of the Seal field is computed as follows:

For the HMAC-SHA algorithm:

use of the shared secret key to generate the HMAC variant of the message
use of the Data field only (encoded if the corresponding option is selected)
UTF-8 encoding of the data constituting the result of the previous operation
HMAC-SHA hashing of the bytes obtained

This procedure can be summarised as follows:

HMAC-SHA256( UTF-8(Data), UTF-8(secretKey))

Example of computed Seal with a secret key equal to "secret123" and the Data field in POST format below:

captureDay=0|captureMode=AUTHOR_CAPTURE|currencyCode=978|merchantId=039000254447216|orderChannel=INTERNET|responseCode=00|transactionDateTime=2022-11-14T11:21:12+01:00|transactionReference=SIM20221114112037|keyVersion=1|acquirerResponseCode=00|amount=1000|authorisationId=664865|guaranteeIndicator=N|panExpiryDate=202401|paymentMeanBrand=VISA|paymentMeanType=CARD|customerIpAddress=10.78.106.18|maskedPan=############0600|holderAuthentRelegation=N|holderAuthentStatus=NOT_PARTICIPATING|tokenPan=490700h719850600|transactionOrigin=SIMS|paymentPattern=ONE_SHOT|customerMobilePhone=null|mandateAuthentMethod=null|mandateUsage=null|transactionActors=null|mandateId=null|captureLimitDate=20221114|dccStatus=null|dccResponseCode=null|dccAmount=null|dccCurrencyCode=null|dccExchangeRate=null|dccExchangeRateValidity=null|dccProvider=null|statementReference=null|panEntryMode=MANUAL|walletType=null|holderAuthentMethod=NO_AUTHENT_METHOD|holderAuthentProgram=3DS_V2|paymentMeanId=null|instalmentNumber=null|instalmentDatesList=null|instalmentTransactionReferencesList=null|instalmentAmountsList=null|settlementMode=null|mandateCertificationType=null|valueDate=null|creditorId=null|acquirerResponseIdentifier=null|acquirerResponseMessage=null|paymentMeanTradingName=null|additionalAuthorisationNumber=null|issuerWalletInformation=null|s10TransactionId=6|s10TransactionIdDate=20221114|preAuthenticationColor=null|preAuthenticationInfo=null|preAuthenticationProfile=null|preAuthenticationThreshold=null|preAuthenticationValue=null|invoiceReference=null|s10transactionIdsList=null|cardProductCode=F|cardProductName=VISA CLASSIC|cardProductProfile=C|issuerCode=00000|issuerCountryCode=GRC|acquirerNativeResponseCode=00|settlementModeComplement=null|preAuthorisationProfile=null|preAuthorisationProfileValue=null|preAuthorisationRuleResultList=[{"ruleCode":"VI","ruleType":"NG","ruleWeight":"I","ruleSetting":"S","ruleResultIndicator":"0","ruleDetailedInfo":"TRANS=1:3;CUMUL=24999:200000"},{"ruleCode":"RCode","ruleType":"RType","ruleWeight":"RWeight","ruleSetting":"RSetting","ruleResultIndicator":"RIndicator","ruleDetailedInfo":"DetailedInfo"}]|preAuthenticationProfileValue=null|preAuthenticationRuleResultList=null|paymentMeanBrandSelectionStatus=NOT_APPLICABLE|transactionPlatform=PROD|avsAddressResponseCode=null|avsPostcodeResponseCode=null|customerCompanyName=null|customerBusinessName=null|customerLegalId=null|customerPositionOccupied=null|paymentAttemptNumber=1|holderContactEmail=null|installmentIntermediateServiceProviderOperationIdsList=null|holderAuthentType=null|acquirerContractNumber=3863090010|secureReference=null|authentExemptionReasonList=null|paymentAccountReference=a667b63d8bec4fb980106497c53e4|schemeTransactionIdentifier=b4e683c1a6ff4a09a0415116a0a25b401d38c19d24e643078d|guaranteeLimitDateTime=null|paymentMeanDataProvider=null|virtualCardIndicator=N|cardProductUsageLabel=CREDIT|authorisationTypeLabel=TRANSACTION DE PAIEMENT|authorMessageReference=272612|acceptanceSystemApplicationId=142000000001|challengeMode3DS=null|issuingCountryCode=GRC|abortedProcessingStep=null|abortedProcessingLocation=null

The Seal you have to obtain is c946655cce0059124b4ad3eb62c0922c51a0a7d8d28a3cf223e4c0da41bbc5b9

Example of computed Seal with a secret key equal to "secret123" and the Data field in JSON format below:

{"keyVersion":1,"amount":44000,"captureDay":0,"captureMode":"AUTHOR_CAPTURE","currencyCode":"978","customerId":"40813","customerIpAddress":"213.118.246.190","merchantId":"225005049920001","orderAmount":44000,"orderChannel":"INTERNET","responseCode":"97","responseDescription":"Request time-out; transaction refused","transactionDateTime":"2023-03-15.00:39:04+0100","transactionReference":"dd88adfZ1027b40813f40813y1678837075","statementReference":"T7Ft4KKLRA2M11B9","s10TransactionId":"6","s10TransactionIdDate":"20230315","sealAlgorithm":"sha256","transactionPlatform":"PROD","paymentAttemptNumber":2,"preAuthorisationRuleResultList":[{"ruleCode":"VI","ruleType":"NG","ruleWeight":"I","ruleSetting":"S","ruleResultIndicator":"0","ruleDetailedInfo":"TRANS=1:3;CUMUL=24999:200000"},{"ruleCode":"RCode","ruleType":"RType","ruleWeight":"RWeight","ruleSetting":"RSetting","ruleResultIndicator":"RIndicator","ruleDetailedInfo":"DetailedInfo"}]}

The Seal you have to obtain is 77be1c230491c0d4eef6eaf910f635d42f55c90cd34c5a162c0ef6fcefb3f087

For the SHA-256 algorithm (although this is the default value, this algorithm is no longer recommended):

concatenation of the Data field and of the secret key (encoded if the corresponding option is selected)
UTF-8 encoding of the data constituting the result of the previous operation
SHA256 hashing of the bytes obtained

This procedure can be summarised as follows:

SHA256( UTF-8(Data+secretKey ) )

Example of computed Seal with a secret key equal to "secret123" and the Data field in POST format below:

captureDay=0|captureMode=AUTHOR_CAPTURE|currencyCode=978|merchantId=039000254447216|orderChannel=INTERNET|responseCode=00|transactionDateTime=2022-11-14T11:21:12+01:00|transactionReference=SIM20221114112037|keyVersion=1|acquirerResponseCode=00|amount=1000|authorisationId=664865|guaranteeIndicator=N|panExpiryDate=202401|paymentMeanBrand=VISA|paymentMeanType=CARD|customerIpAddress=10.78.106.18|maskedPan=############0600|holderAuthentRelegation=N|holderAuthentStatus=NOT_PARTICIPATING|tokenPan=490700h719850600|transactionOrigin=SIMS|paymentPattern=ONE_SHOT|customerMobilePhone=null|mandateAuthentMethod=null|mandateUsage=null|transactionActors=null|mandateId=null|captureLimitDate=20221114|dccStatus=null|dccResponseCode=null|dccAmount=null|dccCurrencyCode=null|dccExchangeRate=null|dccExchangeRateValidity=null|dccProvider=null|statementReference=null|panEntryMode=MANUAL|walletType=null|holderAuthentMethod=NO_AUTHENT_METHOD|holderAuthentProgram=3DS_V2|paymentMeanId=null|instalmentNumber=null|instalmentDatesList=null|instalmentTransactionReferencesList=null|instalmentAmountsList=null|settlementMode=null|mandateCertificationType=null|valueDate=null|creditorId=null|acquirerResponseIdentifier=null|acquirerResponseMessage=null|paymentMeanTradingName=null|additionalAuthorisationNumber=null|issuerWalletInformation=null|s10TransactionId=6|s10TransactionIdDate=20221114|preAuthenticationColor=null|preAuthenticationInfo=null|preAuthenticationProfile=null|preAuthenticationThreshold=null|preAuthenticationValue=null|invoiceReference=null|s10transactionIdsList=null|cardProductCode=F|cardProductName=VISA CLASSIC|cardProductProfile=C|issuerCode=00000|issuerCountryCode=GRC|acquirerNativeResponseCode=00|settlementModeComplement=null|preAuthorisationProfile=null|preAuthorisationProfileValue=null|preAuthorisationRuleResultList=[{"ruleCode":"VI","ruleType":"NG","ruleWeight":"I","ruleSetting":"S","ruleResultIndicator":"0","ruleDetailedInfo":"TRANS=1:3;CUMUL=24999:200000"},{"ruleCode":"RCode","ruleType":"RType","ruleWeight":"RWeight","ruleSetting":"RSetting","ruleResultIndicator":"RIndicator","ruleDetailedInfo":"DetailedInfo"}]|preAuthenticationProfileValue=null|preAuthenticationRuleResultList=null|paymentMeanBrandSelectionStatus=NOT_APPLICABLE|transactionPlatform=PROD|avsAddressResponseCode=null|avsPostcodeResponseCode=null|customerCompanyName=null|customerBusinessName=null|customerLegalId=null|customerPositionOccupied=null|paymentAttemptNumber=1|holderContactEmail=null|installmentIntermediateServiceProviderOperationIdsList=null|holderAuthentType=null|acquirerContractNumber=3863090010|secureReference=null|authentExemptionReasonList=null|paymentAccountReference=a667b63d8bec4fb980106497c53e4|schemeTransactionIdentifier=b4e683c1a6ff4a09a0415116a0a25b401d38c19d24e643078d|guaranteeLimitDateTime=null|paymentMeanDataProvider=null|virtualCardIndicator=N|cardProductUsageLabel=CREDIT|authorisationTypeLabel=TRANSACTION DE PAIEMENT|authorMessageReference=272612|acceptanceSystemApplicationId=142000000001|challengeMode3DS=null|issuingCountryCode=GRC|abortedProcessingStep=null|abortedProcessingLocation=null

The Seal you have to obtain is 8fb7c5b7e972ed5a279629757aeae9885cdfc1fd888e6fc03114064e94bb2bf4

Example of computed Seal with a secret key equal to "secret123" and the Data field in JSON format below:

{"keyVersion":1,"amount":44000,"captureDay":0,"captureMode":"AUTHOR_CAPTURE","currencyCode":"978","customerId":"40813","customerIpAddress":"213.118.246.190","merchantId":"225005049920001","orderAmount":44000,"orderChannel":"INTERNET","responseCode":"97","responseDescription":"Request time-out; transaction refused","transactionDateTime":"2023-03-15.00:39:04+0100","transactionReference":"dd88adfZ1027b40813f40813y1678837075","statementReference":"T7Ft4KKLRA2M11B9","s10TransactionId":"6","s10TransactionIdDate":"20230315","sealAlgorithm":"sha256","transactionPlatform":"PROD","paymentAttemptNumber":2,"preAuthorisationRuleResultList":[{"ruleCode":"VI","ruleType":"NG","ruleWeight":"I","ruleSetting":"S","ruleResultIndicator":"0","ruleDetailedInfo":"TRANS=1:3;CUMUL=24999:200000"},{"ruleCode":"RCode","ruleType":"RType","ruleWeight":"RWeight","ruleSetting":"RSetting","ruleResultIndicator":"RIndicator","ruleDetailedInfo":"DetailedInfo"}]}

The Seal you have to obtain is e9aa5be21186a9f9a417b82d1d450792851c849ccc8a2f85136897da29477975

Specifying the manual response URL

The main goal of the manual response is to redirect the customer to your website and specify the wallet management result.

The main Mercanet page includes the "Back" button with a link that redirects the customer to your website. Clicking on this button, the customer is redirected by Mercanet to the URL address included in the normalReturnUrl field provided in the request. The redirection is a HTTP(S) POST request that contains the data of the response. It is your responsibility to retrieve those paramaters and check the signature, thus ensuring the integrity of the response. Besides, you are in charge of displaying relevant messages to your customer (i.e. messages pertaining to the details of the response).

This normalReturnUrl field is also used for all payment results (cancellation, refusal, etc.) so as to perform the redirection to your site.

It is important to note that the receipt of the response cannot be guaranteed, since this response is sent by the customer’s Web browser. First, the customer may choose not to click on the link. Then he might encounter connection issues that block the transmission of this response. Therefore, your business processes cannot be based only on this response.

Specifying the automatic response URL

The automatic response is sent only if the automaticResponseUrl field was sent in the wallet management request. If that is the case, the Mercanet server sends a HTTP(S) POST response to the URL address received.

The fields of the automatic response are the same as those of the manual response. The only difference between both procedures is that the automatic response is sent directly by the Mercanet server and does not go through the customer's Web browser. Therefore, this response is much more reliable since it is always sent. The Mercanet server does not expect any response after the automatic response has been sent.

It is your responsibility to retrieve the various data of the response, check the signature to make sure the fields of the response have not been tampered with, and update your back office.

Choose response format : POST or JSON

From the interfaceVersion HP_3.0 Mercanet sends you the concatenated string of the response (Data field) in 2 distinct formats to choose :

The POST format

This POST format has the following structure : key1=value1|key2=value2…

POST response example with "pipe" separator between the data

merchantId=029000254447216|keyVersion=1|merchantWalletId=2|merchantSessionId=null|customerId=null|customerIpAddress=10.78.106.17
    |returnContext=null|walletCreationDateTime=2022-10-19T12:58:01+02:00|walletLastActionDateTime=2022-10-19T12:58:01+02:00
    |walletPaymentMeanDataList={paymentMeanId=1, paymentMeanAlias=cb, paymentMeanBrand=CB, maskedPan=############0400, panExpiryDate=202301, mandateId=null, transactionActors=null, paymentMeanBrandSelectionStatus=NOT_APPLICABLE}
    |customerCompanyName=null|customerBusinessName=null|customerLegalId=null|customerPositionOccupied=null

The JSON format

JSON format has the following structure : { "key1" : "value1", "key2" : "value2", …}

Note: JSON format easily displays a list or a collection of objects with the following structure : "clientList" : [ { "name" : "name1", "surname" : "surname1",… }, { "name" : "name2", "surname" : "surname2",… } ]

JSON response example


    {
  		"keyVersion":1,"customerIpAddress":"10.78.106.17","merchantId":"029000254447216","merchantWalletId":"2","walletCreationDateTime":"2022-10-19.12:58:01+0200",
        "walletLastActionDateTime":"2022-10-19.12:58:01+0200","sealAlgorithm":"sha256",
  		"walletPaymentMeanDataList":[
  		    {"paymentMeanId":"1","paymentMeanAlias":"cb","paymentMeanBrand":"CB","maskedPan":"############0400","panExpiryDate":"202301","paymentMeanBrandSelectionStatus":"NOT_APPLICABLE"}
  		]
	}

Default behaviour since the interfaceVersion HP_3.0

Format of the automatic and manual response is determined by the connector that was used during HTTPS exchanges between your website and Mercanet servers.

Tip: Here is a summary table of the mechanic between InterfaceVersion HP_3.0 / Connector called / Response Format

Interface Version	Connector	Response Format
WMR_WS_3.x	JSON	JSON (JS_3.x)
HP_3.x	POST	POST (HP_3.x)
WMR_WS_3.x	SOAP	POST (HP_3.x)

Choose response versions from the wallet management request

If you want to override this default behavior it is possible to fill in from the wallet management request the exact versions of the automatic and manual responses that you use.

The wallet management request field which allows to fill in the automatic response version is interfaceVersionAutomaticResponse

The wallet management request field which allows to fill in the manual response version is interfaceVersionNormalResponse

Attention: If versions entered in the request are incorrect, then the wallet management request fails (error code 30).

These two new fields interfaceVersionAutomaticResponse and interfaceVersionNormalResponse are optional but if one of both is filled in so the other one becomes mandatory. Otherwise, the wallet management request is failed (error code 12).

Solving response receipt issues

Below is a list of the most common issues that block the receipt of automatic and manual responses. Please make sure you have checked them before you call the technical support:

Make sure the response URLs are provided in the wallet management request and are valid. To do this, simply copy and paste them into the address bar of your browser.
The supplied URLs must be accessible from the outside, i.e. the Internet. Access control mechanisms (login/password or IP address filter) or a firewall might block access to your server.
Access to response URLs must be confirmed in the notifications report of your web browser.
If you use a non-standard port, it must be within the 80 to 9999 range to ensure compatibility with Mercanet.

In some error cases, the Mercanet Server is unable to sign the response message. This applies, for instance, to the "Unknown merchantID" error and to the situation where the secret key is unkwown to Mercanet. For these particular reasons, the payment server will send a response without a signature in the Seal field.

Retrieving response fields

The content of Walletpage's automatic and manual web responses is identical.

The fields present in the automatic and manual responses are listed on this page.

Note: manual and automatic responses are encoded in base64 or in base64url.

Analysing the response to the wallet management request

If you carry out the authentication steps by means of an electronic seal, you should make sure the seal you received actually matches the seal you recomputed using the response fields.

In case the seal you received does not match the seal you recomputed, the wallet management session status is considered unknown, please contact the support.

Status	Response fields	Action to perform
Wallet management operation taken into account	walletLastActionDateTime populated with the current date and time walletPaymentMeanDataList contains the means of payment in the wallet after the update	Store the following wallet data in your customer database: paymentMeanAlias paymentMeanId paymentMeanBrand PanExpiryDate maskedPAN
Wallet management operation not taken into account	walletLastActionDateTime not populated with the current date and time walletPaymentMeanDataList contains the means of payment in the wallet	If the wallet must be updated, then submit a request again.

Status

Response fields

Action to perform

Wallet management operation taken into account

walletLastActionDateTime populated with the current date and time

walletPaymentMeanDataList contains the means of payment in the wallet after the update

Store the following wallet data in your customer database:

paymentMeanAlias
paymentMeanId
paymentMeanBrand
PanExpiryDate
maskedPAN

Wallet management operation not taken into account

walletLastActionDateTime not populated with the current date and time

walletPaymentMeanDataList contains the means of payment in the wallet

If the wallet must be updated, then submit a request again.

Step 3: testing in the test environment

Once the development of the connection to Mercanet done, you can run a test on the Mercanet server:

Url : https://payment-webinit-mercanet.test.sips-services.com/walletManagementInit

To perform your tests, use the test eshop and the tests cards mentioned on this page :

merchantId	211000021310001
scretKey	S9i8qClCnb2CZU3y3Vn0toIOgz3z_aBi79akR30vM9o
keyVersion	1

Attention:

This test eshop only accepts Euro currency.

Step 4: validating the switch to the production environment

Once you have tested your website connection to Walletpage POST, you can validate the connection to the production version of Walletpage POST.

Prior to this, we recommend you block public access to your website to prevent customers from carrying out transactions during this validation phase.

If you would like to customise your payment pages, you can use our CustomPages tool to test and view the rendering on payment pages. To do so, please refer to the CustomPages documentation to use the tool.

To switch to the production server, you must change the URL in order to connect to the Mercanet production server using the merchantId, secretKey and keyVersion credentials you received during the registration phase.

Mercanet URL	https://payment-webinit.mercanet.com/walletManagementInit
merchantId	Shop identifier received by e-mail
SecretKey	Secret key you can retrieve from the Mercanet Téléchargement extranet
keyVersion	Secret key version retrieved from Mercanet Téléchargement (obviously 1 for the first key)

Attention: forgetting one of these 4 parameters is a common mistake that systematically results in an error.

How to validate proper functioning in the production environment

Initiate a wallet by adding a first card into it.
Make sure the wallet has been created.
Add a second card into an existing wallet if you have subscribed to the multi-card option.
Make sure the second card has been added.

Step 5: launching live operation

Once the validation for the transition to live operation has been carried out, make your site public so your customers can add means of payment to their wallets.

Walletpage POST

Introduction

Who does this document target?

Prerequisites

Secret key management

Understanding customer wallet management with Walletpage POST

Getting started with Walletpage POST in 5 steps

Step 1: subscribing to the service

Step 2: managing your customers' wallets

Generating the wallet management request

Data field syntax

Encoding the Data field

Securing the request

How to secure the request

Calculating the Seal data element

HMAC-SHA algorithm

Hmac Sha256 sample code

Seal calculation validation

SHA-256 algorithm

Sample Sha256 code

Sample wallet management request

Processing wallet management initialisation errors

Populating the request fields

Setting up the wallet management request

Restriction of customer functionalities for wallet management

Dynamic restriction of means of payment

Customer's wallet identification

Provider acting on behalf of a merchant

Response processing

Specifying the manual response URL

Specifying the automatic response URL

Choose response format : POST or JSON

Solving response receipt issues

Retrieving response fields

Analysing the response to the wallet management request

Step 3: testing in the test environment

Step 4: validating the switch to the production environment

How to validate proper functioning in the production environment

Step 5: launching live operation

Need help?