Paypage SOAP

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

Give a feedback about this page

The last interfaceVersion is IR_WS_3.4

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 Paypage SOAP 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 SOAP mode between their websites and the Paypage SOAP payment servers.

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

Prerequisites

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

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 payment with Paypage SOAP

The general principle for a payment process is as follows:

picture of the general principle of a payment scheme

1. When the customer makes a payment, a payment request must be sent to Paypage SOAP. The URL of this connector is provided by BNP Paribas. The request is then checked, and encryted if valid (it is named RedirectionData in the system). The request is sent through a POST form via HTTPS. Any other solution that can send such requests also works.

2. The merchant site redirects the calling application to the Mercanet payment pages. The customer must enter the information of the means of payment for the Mercanet payment server to process the transaction. It is worth noting that payment details can be entered directly on the server that provides the means of payment (e.g. PayPal or SEPA mandate). At the end of the payment process, whether successful or not, two responses are created and sent to the URL specified as part of flow No. 1.

There are two independent response notifications:

3. The payment server sends the manual responses in HTTP(S) POST format to the manual response URL. This URL is specified in the payment request and is used when the customer clicks on the Continue button of the payment page. It is the page the user is redirected to at the end of the payment. As nothing guarantees that the customer will click on this link, you have no guarantee of receiving the manual response either.

4. Automatic responses are sent separately from manual responses. They also use the HTTP(S) POST requests sent by the Mercanet payment servers, this time using the automatic response URL specified in the payment request. This means you receive the response as soon as the payment is made on the Mercanet payment pages.

IMPORTANT: if you do not have the "New payment attempt" option (see "New payment attempt" section in the document "Functionality set-up guide"), if the payment has failed and the customer is redirected to your website, it is no longer possible to return to the Mercanet payment pages and attempt to pay again or correct card data. The role of your website is to initialise a new payment request, beginning with calling the Paypage connector.

Getting started with Paypage SOAP in 5 steps

Step 1: registering the shop

In order to register your shop as live, you are required to complete the registration form sent by BNP Paribas and send the form back to the latter.

When filling in the form, you must appoint an administrator contact and a technician contact so that BNP Paribas can send you the information needed to launch your shop.

BNP Paribas will then register your shop and e-mail you your merchant ID, together with your IDs and passwords for Merchant Extranet (to retrieve the secret key and perform cash management).

Note: For Merchant Extranet, the connexion information are sent to the administrator contact.

Registering the shop is not needed to start integrating the connector and testing the connection on the customer test environment. It is possible to defer requesting shop registration until you perform live operation tests.

Step 2: making a payment

The payment request is a call to a REST web service (SOAP) located on the Mercanet payment platform.

Generating the payment request

All the fields requested by the transaction must be supplied (please refer to the "Filling in the request fields" chapter).

Request syntax

The request is built in line with the SOAP format.

Sample payment request with an amount of 52.50 euros:

<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'>
  <soapenv:Body>
    <urn:paymentWebInit xmlns:urn='urn:sips:cn:contract:payment:v2'>
      <urn:input>
        <urn:amount>5250</urn:amount>
        <urn:currencyCode>978</urn:currencyCode>
        <urn:interfaceVersion> IR_WS_2.20</urn:interfaceVersion>
        <urn:merchantId>011223744550001</urn:merchantId>
        <urn:normalReturnUrl> http://www.normalreturnurl.com </urn:normalReturnUrl>
        <urn:orderChannel>INTERNET</urn:orderChannel>
        <urn:responseKeyVersion>1</urn:responseKeyVersion>
        <urn:transactionReference>TREF0808151333</urn:transactionReference>
        <urn:keyVersion>3</urn:keyVersion>
      <urn:seal>3a02205859ffd2eff4d7dd015ce01fda11d80f03fa88e2caa188c5eea5a42c61</urn:seal></urn:input>
    </urn:paymentWebInit>
  </soapenv:Body>
</soapenv:Envelope>

Request fields presence

Some fields of the payment request are required:

Only when using certain means of payment. Please read the dedicated means of payment guide to know the mandatory fields.
Depending on your shop configuration. Please read the Functionality set-up guide to find out the mandatory fields.
Only in certain use cases (e.g. recurring payment). Please read the Functionality set-up guide to know the mandatory fields.

Those fields are marked as "conditional".

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:

Concatenation of data field values in the alphabetical order of field names (in accordance with ASCII character codes), without integrating the keyVersion and sealAlgorithm fields. Giving the field data, mentioned in the examples below.
- as an example, a field that would be named authorMessageReference must be positioned before another field named authorisationId
Obtaining the UTF-8 encoding of the 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(sortedDataValues), UTF-8(secretKey))

Attention: by default, the seal is computed with the HMAC-SHA-256 algorithm, the use of which we strongly recommend.

For the seal to be computed with the SHA-256 algorithm, the input parameters of the request must include the sealAlgorithm field populated with the following value: “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:

      <urn:paymentWebInit>
         <urn:input>
            <urn:amount>2500</urn:amount>
            <urn:urn:automaticResponseUrl>https://automatic-response-url.fr/</urn:urn:automaticResponseUrl>
            <urn:normalReturnUrl>https://normal-return-url/</urn:normalReturnUrl>
            <urn:captureDay>0</urn:captureDay>
            <urn:captureMode>AUTHOR_CAPTURE</urn:captureMode>
            <urn:currencyCode>978</urn:currencyCode>
            <urn:customerContact>
                <urn:email>customer@email.com</urn:email>
            </urn:customerContact>
            <urn:interfaceVersion>IR_WS_2.22</urn:interfaceVersion>
            <urn:keyVersion>1</urn:keyVersion>
            <urn:merchantId>011223344550000</urn:merchantId>
            <urn:orderChannel>INTERNET</urn:orderChannel>
            <urn:orderId>ORD101</urn:orderId>
            <urn:returnContext>ReturnContext</urn:returnContext>
            <urn:transactionOrigin>SO_WEBAPPLI</urn:transactionOrigin>
            <urn:transactionReference>TREFEXA2012</urn:transactionReference>
            <urn:seal>322b943d833417c1570e0a282641e8e29d6a5b968c9b846694b5610e18ab5b81</urn:seal>
         </urn:input>
      </urn:paymentWebInit>

For the above request, the concatenated string which must be calculated is:

2500https://automatic-response-url.fr/0AUTHOR_CAPTURE978customer@email.comIR_WS_2.22011223344550000https://normal-return-url/INTERNETORD101ReturnContextSO_WEBAPPLITREFEXA2012

With a SHA-256 hash algorithm and the following secret key:

secret123

The expected seal is:

322b943d833417c1570e0a282641e8e29d6a5b968c9b846694b5610e18ab5b81

Sample redirection form to Paypage SOAP

In return to this request, you should receive a response (also in SOAP) containing the following fields:

Field name	Description
redirectionData	Request token to be provided during the redirection to the payment pages.
redirectionStatusCode	List of possible response codes.
redirectionStatusMessage	Short message providing the initialisation status.
redirectionUrl	URL of the Mercanet payment pages you have to redirect the customer to.
redirectionVersion	Redirection version.
seal	Output seal.
reponseEncoding	Encoding type used for responses.

If the payment initialisation was successful, the redirectionStatusCode field must be populated with "00". The redirectionData, redirectionVersion and redirectionUrl fields will likewise be populated to allow the redirection to the Mercanet payment pages.

To redirect the customer to the payment pages, you must implement a POST form sending the two following fields: redirectionData and redirectionVersion. The POST form shall redirect the customer to the URL provided in the redirectionUrl field.

Below is a sample form that must be submitted automatically:

<form method="post" action=”value of redirectionURL”>
    <input type="hidden" name="redirectionVersion" value=”value of redirectionVersion”>
    <input type="hidden" name="redirectionData" value=”value of redirectionData”>
  </form>

Processing payment initialisation errors

All fields received by Paypage SOAP 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.

redirectionStatusCode	Description
00	Standard situation followed by the standard process used to display the payment pages.
03	The merchantId or the acquirer contract is not correct.
12	The transaction parameters are not correct. Please check the request parameters.
30	The request format is not correct.
34	Security issue: e.g. the computed seal is not correct.
94	The transaction already exists.
99	Service temporarily unavailable.

There are four possible situations:

RedirectionStatusCode = 00

The user must be redirected to the payment page.

RedirectionStatusCode = 03, 12, 30, 34

These error codes indicate that the request has an issue that needs to be fixed. The payment process must be stopped.

RedirectionStatusCode = 94

The transaction reference has already been used. You need to try again with another transaction reference.

RedirectionStatusCode = 99

The payment service is unavailable. Try to submit the request again. A new transaction reference must be used to prevent response code 94 from being returned.

Populating the request fields

The request and the response of paymentWebInit method are described in this page.

Setting up the payment request

Here is an example of how to set up the payment request for each functionality available in Paypage SOAP (the details of these functionalities are described in the Functionality set-up guide).

Dynamic display of the means of payment

You need to use the paymentMeanBrandList field to filter the means of payment that will be displayed on the means of payment selection page:

..
        <urn:paymentMeanBrandList>
          <urn:paymentMeanBrand>VISA</urn:paymentMeanBrand>
          <urn:paymentMeanBrand>MASTERCARD</urn:paymentMeanBrand>
        </urn:paymentMeanBrandList>
..

Receipt display by Mercanet

The payment confirmation page that Mercanet displays by default can be deactivated using the paypageData.bypassReceiptPage field:

..
          <urn:bypassReceiptPage>true</urn:bypassReceiptPage>
..

Payment channel

To choose your payment channel, you must fill in the orderChannel field in the payment request:

..
        <urn:orderChannel>INTERNET</urn:orderChannel>
..

End-of-day payment

For end-of-day payments, simply fill in the captureMode and captureDay fields:

..
        <urn:captureDay>0</urn:captureDay>
        <urn:captureMode>AUTHOR_CAPTURE</urn:captureMode>
..

Deferred payment

For payments that must be captured N days after they were accepted online, simply fill in the captureMode and captureDay fields (3 days in the following example):

..
        <urn:captureDay>3</urn:captureDay>
        <urn:captureMode>AUTHOR_CAPTURE</urn:captureMode>
..

For more complex cases of deferred payments, such as multiple shipments or shipment beyond 6 days, please refer to the "multiple payment on dispatch" guide.

Payment upon shipping

For payments upon shipping, the transaction is captured during your validation. You just need to fill in the captureMode and captureDay fields (in the following example, a period of up to 3 days before the validation is set):

..
        <urn:captureDay>3</urn:captureDay>
        <urn:captureMode>VALIDATION</urn:captureMode>
..

Payment in instalments

For payments with instalments linked to a very same transaction, you need to populate the paymentPattern field with the INSTALMENT value and provide details about instalments in the instalmentData field (in the following example, €600 paid in 3 instalments) :

..
        <urn:amount>60000</urn:amount>
..
        <urn:transactionReference>tref1</urn:transactionReference>
..
        <urn:instalmentData>
          <urn:number>3</urn:number>
          <urn:datesList>
            <urn:date>20170504</urn:date>
            <urn:date>20170604</urn:date>
            <urn:date>20170704</urn:date>
          </urn:datesList>
          <urn:transactionReferencesList>
            <urn:transactionReference>tref1</urn:transactionReference>
            <urn:transactionReference>tref2</urn:transactionReference>
            <urn:transactionReference>tref3</urn:transactionReference>
          </urn:transactionReferencesList>
          <urn:amountsList>
            <urn:amount>10000</urn:amount>
            <urn:amount>20000</urn:amount>
            <urn:amount>30000</urn:amount>
          </urn:amountsList>
        </urn:instalmentData>
..
        <urn:paymentPattern>INSTALMENT</urn:paymentPattern>
..

Immediate payment

For immediate payment (available with certain means of payment only), the transaction is paid for during the online authorisation:

..
        <urn:captureMode>IMMEDIATE</urn:captureMode>
..

Multicurrency acceptance

For multicurrency transactions, the currency code must be specified in the request. The payment currency is specified in the acquiring contract.

..
        <urn:currencyCode>840</urn:currencyCode>
..

Payment in foreign currencies

Acceptance and payment are carried out in the same currency, which must be specified in the request. Payment in foreign currencies is an option of the acquiring contract.

..
        <urn:currencyCode>826</urn:currencyCode>
..

Dynamic Currency Conversion (DCC)

If a Dynamic Currency Conversion (DCC) service is used, the reference currency code must be specified:

..
        <urn:currencyCode>978</urn:currencyCode>
..

OneClick registration and payment

For OneClick payments, the customer's wallet ID must be provided in the merchantWalletId field.

..
        <urn:merchantWalletId>1205987</urn:merchantWalletId>
..

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:

..
        <urn:intermediateServiceProviderId>241591</urn:intermediateServiceProviderId>
..

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 with the result of the payment so you can make the right decision about it. For instance, if an error occurred, you may suggest to the customer to attempt the payment again. If the payment is successful, you can display a “thank you” message and start despatching the goods.

During the final step, a 'Continue' button is displayed on the Mercanet payment page, with a link that redirects the user to your site. When the customer clicks on this link, the Mercanet server redirects them to the URL contained in the normalReturnUrl field supplied in the request. The redirection is a HTTP(s) POST request that contains the data of the response as described above. It is your responsibility to retrieve these parameters 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 payment 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.

Attention: the automatic response is systematic, asynchronous and sent back through the network; it is inherently dependent on potential technical troubles on the various network elements and can now and then be received with a more or less substantial delay, or even never be received at all.

The automatic response is sent at the end of the payment. However, if your customer drops their purchase, for example by exiting their browser, the automatic response is sent when the user session expires (after 15 minutes of inactivity). Therefore, if your customer drops their purchase, you will only receive the automatic response (not the manual response), with an answer code set at 97, about 15 to 16 minutes after the customer has been redirected to the payment pages.

If an automatic response is not received after approximately 16 minutes, you can get the result of a payment by calling the getTransactionData method of the Office (M2M) interface, or by analysing the contents of the Transactions report. You may also search for a transaction and see its status using Mercanet 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

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

Note: The list of complex objects in this POST format has a structure that is similar to the JSON format

(see § Syntax of lists of complex objects in responses)

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, "acquirerResponseCode": "00", "acquirerResponseDescription": "Transaction approved or processed successfully",
  		"amount": 1000, "authorisationId": "858191", "captureDay": 0, "captureMode": "AUTHOR_CAPTURE", "cardScheme": "VISA",
  		"chargeAmount": 0, "currencyCode": "978", "customerIpAddress": "10.78.106.18", "guaranteeIndicator": "N",
  		"holderAuthentRelegation": "N", "holderAuthentStatus": "NOT_PARTICIPATING", "maskedPan": "############0600",
  		"merchantId": "039000254447216", "orderAmount": 1000, "orderChannel": "INTERNET", "panExpiryDate": "202401",
  		"paymentMeanBrand": "VISA", "paymentPattern": "ONE_SHOT", "responseCode": "00", "responseDescription": "Process succeeded",
  		"tokenPan": "490700h719850600", "transactionDateTime": "2022-11-14.11:19:39+0100", "transactionOrigin": "SIMS",
  		"transactionReference": "SIM20221114111757", "captureLimitDate": "20221114", "paymentMeanType": "CARD", "panEntryMode": "MANUAL",
  		"holderAuthentMethod": "NO_AUTHENT_METHOD", "holderAuthentProgram": "3DS_V2", "s10TransactionId": "5", "s10TransactionIdDate": "20221114",
  		"cardProductCode": "F", "cardProductName": "VISA CLASSIC", "cardProductProfile": "C", "issuerCode": "00000", "issuerCountryCode": "GRC",
  		"acquirerNativeResponseCode": "00", "sealAlgorithm": "sha256", "paymentMeanBrandSelectionStatus": "NOT_APPLICABLE",
  		"transactionPlatform": "PROD", "paymentAttemptNumber": 1, "acquirerContractNumber": "3863090010",
  		"schemeTransactionIdentifier": "79e70b862e5942ff86f31951235959a16f45f41f797f48129e",
  		"paymentAccountReference": "945dbb3e0b984bfc896a04c5bc273", "virtualCardIndicator": "N", "cardProductUsageLabel": "CREDIT",
  		"authorisationTypeLabel": "TRANSACTION DE PAIEMENT", "authorMessageReference": "179263", "acceptanceSystemApplicationId": "142000000001",
  		"issuingCountryCode": "GRC", "threeDLiabilityShift": "N", "threeDStatusCode": "NOT_PARTICIPATING", "threeDRelegationCode": "N",
  		"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"}
  		]
	}

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
IR_WS_3.x	JSON	JSON (JS_3.x)
HP_3.x	POST	POST (HP_3.x)
IR_WS_3.x	SOAP	POST (HP_3.x)

Choose response versions from the payment request

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

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

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

Attention: If versions entered in the request are incorrect, then the payment initialization 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 payment initialization 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 payment 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.
Context parameters cannot be added to the response URLs. However, some fields can still be used, e.g. the orderID or returnContext fields make it possible to provide extra parameters. You may also use the sessionId field to retrieve information about your customer at the end of the payment process.

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 the automatic and manual responses sent by Paypage is identical. This content may vary according to the payment result (successful or other).

Note: in the responses, depending on the transaction status and the payment mean chosen, some fields can be null, empty or not returned. Please refer to the payment means documentations to know the fields present in the responses.

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

Optional fields pertaining to fraud checks

Content of preAuthenticationRuleResult

Field	Version	Comments
ruleCode	HP_2.14
ruleType	HP_2.14
ruleWeight	HP_2.14
ruleSetting	HP_2.14
ruleResultIndicator	HP_2.14
ruleDetailedInfo	HP_2.14

Content of preAuthorisationRuleResult

Field	Version	Comments
ruleCode	HP_2.14
ruleType	HP_2.14
ruleWeight	HP_2.14
ruleSetting	HP_2.14
ruleResultIndicator	HP_2.14
ruleDetailedInfo	HP_2.14

Syntax of lists of complex objects in responses

The format of a list of complex objects in automatic and manual responses is defined as follows (bold text):

..|amount=1000|currencyCode=978|objectNameList=[{"field1":"value1a",
"field2":"value2a","field3":"value3a"…},{"field1":"value1b",
"field2":"value2b","field3":"value3b"}…]|transactionReference=1452687287828|..

The content of the list is in square brackets [ ].
Each entry of the list is in curly brackets { }.
Each field is represented as "fieldName" = "fieldValue".
Please note that the name and the value of the field are both in double quotes "".
Pairs of adjacent names/values are separated by a comma.

Sample preAuthorisationRuleResultList field

Breakdown of the fraud rules executed during preauthorisation (bold text):

..|amount=1000|currencyCode=978|preAuthorisationRuleResultList=[
{”ruleCode”:"SC",”ruleType”:"NG",”ruleWeight”:"I",”ruleSetting”:"S",
”ruleResultIndicator”:"0",“ruleDetailedInfo”:"TRANS=1:5;
CUMUL=1000:99999900"},{”ruleCode”:"GC",”ruleType”:"NG",”ruleWeight”:
"D",”ruleSetting”:"N",”ruleResultIndicator”:"0",“ruleDetailedInfo”:
""},{”ruleCode”:"CR",”ruleType”:"NG",”ruleWeight”:"D",”ruleSetting”
:"S",”ruleResultIndicator”:"N",“ruleDetailedInfo”:"CARD_COUNTRY=USA"}]
|transactionReference=1452687287828|..

Payment response analysis

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 transaction status is considered unknown, please leave the transaction as it is, contact the support and do not re-execute the transaction in any automated way.

Status	Response fields	Actions to be carried out
Payment accepted	responseCode = 00 acquirerResponseCode = 00 garanteeIndicator = Y,N,U, empty	You can deliver the order according to the guarantee level of your choosing (garanteeIndicator field).
Mercanet fraud refusal Go-No-Go	responseCode = 05 complementaryCode = XX preAuthorisationRuleResultList	The payment has been refused by the Mercanet fraud engine that you configured. Do not deliver the goods. Analyse in detail the fraud rules executed by Mercanet to know the reason for the refusal (preAuthorisationRuleResultList field).
Mercanet fraud refusal Business Score	responseCode = 05 scoreColor = RED, BLACK scoreValue = X (transaction score) scoreThreshold = X,Y (orange threshold, green threshold)	The payment has been refused by the Mercanet fraud engine that you configured. Do not deliver the goods. Analyse in detail the fraud rules executed by Mercanet to know the reason for the refusal (preAuthorisationRuleResultList field).
Mercanet fraud warning Business Score	responseCode = 05 scoreColor = ORANGE scoreValue = X (transaction score) scoreThreshold = X,Y (orange threshold, green threshold)	The acquirer has authorised the payment, but the Mercanet fraud engine issued a warning due to the rules you configured. Analyse in detail the fraud rules executed by Mercanet to know the reason for the warning (preAuthorisationRuleResultList field). If the transaction poses no risk, accept it using the acceptChallenge function. If the transaction poses a risk, refuse it using the refuseChallenge function. The acceptChallenge and refuseChallenge functions are available on the extranet and the Office (M2M) connectors.
3-D Secure refusal	reponseCode = 05 holderAuthenStatus = FAILURE	Customer authentication failed. This is not necessarily due to fraud. You can suggest to your customer to attempt the payment again with another means of payment, by generating a new request.
Banking refusal from the acquirer	responseCode = 05 acquirerResponseCode = XX	Authorisation refused for a reason not related to fraud. You can suggest to your customer to attempt the payment again with another means of payment, by generating a new request.
Soft decline	responseCode = 05 acquirerResponseCode = A1	The payment has been refused by the acquirer because the 3-D Secure data is missing in the authorisation request. Please try to pay again with a 3-D Secure payment process.
Fraud refusal from the acquirer	responseCode = 34 acquirerResponseCode = XX	Authorisation refused because of fraud. Do not deliver the order.
Refusal because the maximum number of attempts has been reached	responseCode = 75 acquirerResponseCode = XX	The customer made several failed attempts because the information entered was incorrect. There are two possibilities: Your customer has difficulties entering their card information. Carding attempt (search for possible card numbers). Please contact your customer to define what to do next.
Refusal due to a technical issue	responseCode = 90, 99 acquirerResponseCode = 90 to 98	Temporary technical issue while processing the transaction. Please tell your customer to attempt the payment again later.
Abandonment of payment	responseCode = 97 acquirerResponseCode = not filled	Do not deliver the order.

Status

Response fields

Actions to be carried out

Payment accepted

responseCode = 00

acquirerResponseCode = 00

garanteeIndicator = Y,N,U, empty

You can deliver the order according to the guarantee level of your choosing (garanteeIndicator field).

Mercanet fraud refusal

Go-No-Go

responseCode = 05

complementaryCode = XX

preAuthorisationRuleResultList

The payment has been refused by the Mercanet fraud engine that you configured.

Do not deliver the goods.

Analyse in detail the fraud rules executed by Mercanet to know the reason for the refusal (preAuthorisationRuleResultList field).

Mercanet fraud refusal

Business Score

responseCode = 05

scoreColor = RED, BLACK

scoreValue = X (transaction score)

scoreThreshold = X,Y (orange threshold, green threshold)

The payment has been refused by the Mercanet fraud engine that you configured.

Do not deliver the goods.

Analyse in detail the fraud rules executed by Mercanet to know the reason for the refusal (preAuthorisationRuleResultList field).

Mercanet fraud warning

Business Score

responseCode = 05

scoreColor = ORANGE

scoreValue = X (transaction score)

scoreThreshold = X,Y (orange threshold, green threshold)

The acquirer has authorised the payment, but the Mercanet fraud engine issued a warning due to the rules you configured.

Analyse in detail the fraud rules executed by Mercanet to know the reason for the warning (preAuthorisationRuleResultList field).

If the transaction poses no risk, accept it using the acceptChallenge function.

If the transaction poses a risk, refuse it using the refuseChallenge function.

The acceptChallenge and refuseChallenge functions are available on the extranet and the Office (M2M) connectors.

3-D Secure refusal

reponseCode = 05

holderAuthenStatus = FAILURE

Customer authentication failed. This is not necessarily due to fraud. You can suggest to your customer to attempt the payment again with another means of payment, by generating a new request.

Banking refusal from the acquirer

responseCode = 05

acquirerResponseCode = XX

Authorisation refused for a reason not related to fraud.

You can suggest to your customer to attempt the payment again with another means of payment, by generating a new request.

Soft decline

responseCode = 05

acquirerResponseCode = A1

The payment has been refused by the acquirer because the 3-D Secure data is missing in the authorisation request.

Please try to pay again with a 3-D Secure payment process.

Fraud refusal from the acquirer

responseCode = 34

acquirerResponseCode = XX

Authorisation refused because of fraud.

Do not deliver the order.

Refusal because the maximum number of attempts has been reached

responseCode = 75

acquirerResponseCode = XX

The customer made several failed attempts because the information entered was incorrect. There are two possibilities:

Your customer has difficulties entering their card information.
Carding attempt (search for possible card numbers).

Please contact your customer to define what to do next.

Refusal due to a technical issue

responseCode = 90, 99

acquirerResponseCode = 90 to 98

Temporary technical issue while processing the transaction.

Please tell your customer to attempt the payment again later.

Abandonment of payment

responseCode = 97

acquirerResponseCode = not filled

Do not deliver the order.

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/services/v2/paymentInit

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 Paypage SOAP, you can validate the connection to the production version of Paypage SOAP.

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.bnpparibas.net/services/v2/paymentInit
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 the proper functioning in the production environment

Immediately:

Make a transaction using a real payment card (your own, if possible). If the transaction is accepted, it will be sent to the bank to credit your merchant account and to debit the card account.
Check that your payment pages include your customisation settings.
Check the transaction via Mercanet Back Office, using the transactionReference.

The next day:

Make sure the transaction is in the Transactions report.
Check your account to make sure the operation was credited.
Refund the transaction via Mercanet Back Office (optional).

Two days later:

Check that the refund transaction is in the Operations report.
Make sure the debited amount has been refunded to your merchant account.

This validation process is also applicable to the PayPal means of payment.

Step 5: launching live operation

Once the validation for the transition to live operation has been carried out, make your site and/or application public so your customers can make purchases and payments.

On the same day:

Monitor acceptance rates (number of responseCode 00 per total number of transactions)
Check the nature of non-banking declines:
- technical issue: responseCode 90, 99
- fraud: responseCode 34
- maximum number of payment attempts reached: responseCode 75
- abandonment: responseCode 97

The next day:

Check that all transactions processed (accepted and refused) are in the Transactions report.
Check the operations you have carried out and remittances (report option) in the Operations report.

Paypage SOAP

Introduction

Who does this document target?

Prerequisites

Secret key management

Understanding payment with Paypage SOAP

Getting started with Paypage SOAP in 5 steps

Step 1: registering the shop

Step 2: making a payment

Generating the payment request

Request syntax

Request fields presence

Securing the request

How to secure the request

Calculating the Seal data element

HMAC-SHA algorithm

Hmac Sha256 sample code

Seal calculation validation

Sample redirection form to Paypage SOAP

Processing payment initialisation errors

Populating the request fields

Setting up the payment request

Dynamic display of the means of payment

Receipt display by Mercanet

Payment channel

End-of-day payment

Deferred payment

Payment upon shipping

Payment in instalments

Immediate payment

Multicurrency acceptance

Payment in foreign currencies

Dynamic Currency Conversion (DCC)

OneClick registration and payment

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

Optional fields pertaining to fraud checks

Syntax of lists of complex objects in responses

Payment response analysis

Step 3: testing in the test environment

Step 4: validating the switch to the production environment

How to validate the proper functioning in the production environment

Step 5: launching live operation

Need help?