Subscription payment via duplication

Introduction

Mercanet is a secure, multichannel 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 of the subscription-based payment solution up to the start of production.

Who does this document target

This document is intended to help you implement the recurring payments for the services they provide to their customers (hereinafter referred to as subscribers).

The purpose is to present the features of subscription payments and explain how to implement them with the Mercanet solution.

To get an overview of the Mercanet solution, we advise you to consult the following documents:

Functional presentation
Functionality set-up guide

Note: Mercanet does not manage the subscribers personal details (first name, surname, address, age, email, telephone, etc.), just the payment details that let you debit or credit your subscribers.

Prerequisites

Subscription payments require your subscribers' payment details to be stored by Mercanet to ensure that you can make payments.

Therefore, here are some points to address before you can get started:

To comply with the GDPR, you must complete your internal personal data processing register, specifying that the card details are stored in Mercanet platform. For more information on the GDPR, please refer to our Sips information systems security.
Inform your customers that their recurring payment details and methods will be stored (duration, amount, frequency etc.).

Subscription Service Overview

Subscription payment has several parts:

subscriber enrolment and authentication (CIT);
debits for the occurrences of the subscription (MIT) by duplicating the CIT ;
managing the subscriber's means of payment expiry

The means of payment for recurring payments are :

CB, Visa, Mastercard, Amex, Bancontact (WIP option required)
SEPA Direct Debit (SDD) Mandate

Data to retain

When enrolling the subscriber (CIT), please keep the following information:

the CIT reference to allow duplication of the CIT to create the MIT(field transactionReference or s10TransactionId/s10TransactionDate)
the expiry date of the card to know when you have to call your subscriber back to enrol their new card (field cardExpiryDate)

You can then debit your subscriber on a recurring basis, by file transfer or online.

Choosing the Mercanet connectors for subscription

Because Mercanet offers several interfaces to deal with subscription taking out and with recurring payments, you have to analyse your business need so as to choose the connectors best suited to your situation.

The table below helps you make your choice.

Use case	Paypage	Office (M2M)	Office (M2M) CSE	In-App	Office Batch	Mercanet Back Office Back Office	Choice of connector
Subscription taking out
You want to get free from PCI requirements.	V	X	V	V	X	X	If you use Paypage to process your payments, you can capitalise on this existing integration to handle the subscription taking out. For m-commerce, we recommend the use of In-App.
You display and secure the pages for entering payment details	X	V	V	V	X	X	Office (M2M) meets your need for e-commerce. For m-commerce, we recommend the use of In-App.
Recurring payments
You debit or credit your subscribers at due dates (in the case of packages or services billed after consumption).	X	V	X	X	V	V	Office Batch file mode is the connector suitable for the massive recurring payment processing, but you can also use Office (M2M).
You debit or credit your subscribers at different due dates (in the case of prepaid services where the subscriber has to charge his account before consuming).	X	V	X	X	X	V	The transactional mode is Office (M2M) the connector that is suitable for debiting or crediting your subscribers with varying due dates.
Means of payment expiry
Renew the subscriber's means of payment.	Renewal is treated as subscription taking out.						Reuse the same connector used for subscription taking out.
Initialising the subscriber base
You are migrating an existing subscriber base.	X	X	X	X	V	X	Office Batch allows you to initialise the subscriber base from an existing database.

Implementation

Enrolling the subscriber (CIT)

Enrolling the subscriber with Paypage

The collection of payment details is done on Paypage.

If the subscriber's means of payment is a card:

The subscriber must necessarily authenticate himself with the 3-D Secure system.
You can use the field authenticationData.authentAmount to authenticate an amount different from the amount to be paid on the first due date.
You must keep the transaction reference in your information system, in order to debit your subscriber for future due dates.

Description

During the subscription taking out phase, you redirect the new subscriber to Paypage by including the transaction data in the request (amount of the first due date, currency, etc.).
Mercanet displays the payment page, the subscriber provides their payment details and then validates.
Mercanet performs the 3-D Secure checking.
Mercanet performs anti-fraud checks.
Mercanet sends an authorisation request to the acquirer.
Mercanet saves the transaction in the back office.
Mercanet returns you the manual and automatic responses containing the transaction details. You store your transaction reference and the card expiry date.
Mercanet sends or does not send the transaction based on the terms you set in the payment request.

Setting up the request

This consists in a classic Paypage request, please refer to one of the Paypage guides to learn how to populate the request based on your business needs.

However, the following fields have a particular behaviour and should be valued like this:

Field	Value
`paymentPattern`	RECURRING_1
`challengeMode3DS`	CHALLENGE_MANDATE
`captureDay`	0 to 6
`captureMode`	AUTHOR_CAPTURE or VALIDATION
`amount`	amount of the first due date (can be valued at 0 if the first due date is free or if the first payment takes place later)
`authentAmount`	to be valued if the amount field = 0 with the average amount of a payment occurrence of the subscription. If the field is not filled in, the authentication amount will be the same as the one indicated in the amount field.

Analysing the response

Mercanet returns a classic manual and automatic Paypage response.

The fields pertaining to subscription taking out are as follows:

Status	Response fields	Actions to perform
Transaction accepted (subscription taken out successfully)	`ResponseCode` = 00 `AcquirerResponseCode` = 00	Store the transaction reference in your customer base: `TransactionReference` or the `s10TransactionReference.s10TransactionId` / `ss10TransactionReference.s10TransactionDate` pair `PanExpiryDate` `MaskedPAN` You can submit recurring payments.
Transaction declined (subscription taking out declined)	`ResponseCode` = XX (not 00)	Read the Paypage connector guide to analyse the response from Mercanet.

Enrolling the subcriber with Office (M2M)

Collecting payment details is done on your e-commerce site.

You then use two methods:

cardCheckEnrollment: checks the 3-D Secure enrollment of the card (see the JSON or SOAP Mercanet documentation to find out the full parameters of the request).
cardValidateAuthenticationAndOrder: cardholder authentication and authorisation request (see the JSON or SOAP Mercanet documentation to find out the full parameters of the request).

For the cardCheckEnrollment method, these fields have a particular behaviour and should be valued as follows:

Field	Value
`paymentPattern`	RECURRING_1
`challengeMode3DS`	CHALLENGE_MANDATE
`authenticationData.authentAmount`	amount of the first due date of the subscription (may be valued at 0 if the first due date is free of charge, for example, or if the first payment is not made until later)
`authentAmount`	to be valued if the amount field = 0 with the average amount of a payment occurrence of the subscription. If the field is not filled in, the authentication amount will be the same as the one indicated in the amount field.
`captureDay`	0 to 6
`captureMode`	AUTHOR_CAPTURE or VALIDATION

Attention: You must keep the transaction reference in your information system, in order to debit your subscriber for future due dates.

Charging the subscriber (MIT)

Recurring payments with Office Batch

Once the subscription taking out is accepted, you can debit subscriber batches using file transfer with Office Batch, thanks to transaction duplication. Transactions are automatically chained by Mercanet.

Description

You format a Office Batch file consisting of duplicate requests.

Each duplicate record includes:

The transaction reference of the subscription taking out (FromTransactionReference field or the s10FromTransactionReference.s10FromTransactionId / s10FromTransactionReference.s10FromTransactionIdDate pair).
The amount of the due date.

The chain of steps is as follows:

You send the file to Mercanet via FTPS or SFTP.
Mercanet retrieves the subscriber’s payment details.
Mercanet runs fraud checks you set up on your shop.
Mercanet sends the authorisation requests to acquirers.
Mercanet stores the transaction in the back office.
Mercanet formats the response file and returns it to you.
In the evening, Mercanet sends the remittances for accepted transactions.

Please read the Office Batch XML or Office Batch CSV guides for details on the implementation (file structure, records description, file transfer, error handling, etc.).

Setting up the request

To generate a recurring payment using the duplicate method, you need to populate the following fields:

Field	Value	Comment
`FromTransactionReference` or `fromS10TransactionReference.fromS10TransactionId` / `fromS10TransactionReference.fromS10TransactionIdDate` pair	The reference of the transaction made when taking out the subscription or The reference of the transaction made on the last modification of the means of payment
`amount`	The amount of the due date

Please refer to the Office Batch XML or Office Batch CSV guides to find out how to populate the other fields in the request depending on your business need.

Analysing the response

Status	Response fields	Actions to perform
Transaction accepted	`ResponseCode` = 00	The next day, check in the Transactions report that the sending for remittance has been completed (`TransactionStatus` = CAPTURED).
Transaction refused	`ResponseCode` = XX	Please refer to the Office Batch connectors guides to analyse the response from Mercanet.

Recurring payments with Office (M2M)

The Office (M2M) JSON/SOAP connector also provides the duplicate method in message mode with the same rules as Office Batch for request formatting and response analysis.

Please refer to one of the Office (M2M) guides for implementation details.

Means of payment expiry

Since you have stored the means of payment expiry date when taking out a subscription, you can alert your subscriber long enough before the expiry date, so as to ask them to return to your e-commerce site and renew their means of payment.

The renewal of the means of payment must be handled in the same way as when taking out a subscription. Once the new means of payment has been entered and validated, store the new means of payment expiry date and the new transaction reference for use at future recurring debits.

Summary

Subscription with 1st payment within 6 days

Here is an example of a subscription payment with a first due date within 6 days:

Connectors :

	CIT	MIT
Connector	Paypage Office (M2M) In-App	Office (M2M) Office Batch

Parameters of the request :

champ	CIT	MIT
`paymentPattern`	RECURRING_1	X
`ChallengeMode3DS`	CHALLENGE_MANDATE	X
`captureDay`	[ 0 , 6 ]	[ 0 , 99 ]
`captureMode`	AUTHOR_CAPTURE VALIDATION	AUTHOR_CAPTURE VALIDATION
`amount`	Amount of the fisrt due date	amount of nth due date
`authentAmount`	Average amount of due dates	X

Subscription with 1st payment in more than 6 days

Here is an example of a subscription payment with a first due date of more than 6 days:

Connecteurs :

	CIT	MIT
Connecteur	Paypage Office (M2M) In-App	Office (M2M) Office Batch

Paramètres de la requête :

champ	CIT	MIT
`paymentPattern`	RECURRING_1	X
`ChallengeMode3DS`	CHALLENGE_MANDATE	X
`captureDay`	0	[ 0 , 99 ]
`captureMode`	X	AUTHOR_CAPTURE VALIDATION
`amount`	0	amount of nth due date
`authentAmount`	Average amount of due dates	X

Starting subscription in 4 steps

Step 1 - implement the service

When you have chosen the Mercanet interfaces that meet your needs (see the 'Choosing the Mercanet connectors for subscription' section), will you need to integrate the connectors to connect your site to Mercanet and to follow the instructions in the 'Implementation' section.

Step 2 - Test the service on the test environment

Once you have implemented the Mercanet connectors, you can do some tests to validate your integration.

test data
merchantId	201000076690001
secret key	p64ifeYBVIaRcjaWoahCiw9L8wokNLqG2_YOj_POD4g
secret key version	1
test cards	Cf. the "Test cards" page

Server	Test URL
Paypage POST	https://payment-web-mercanet.test.sips-services.com/paymentInit
Paypage JSON	https://payment-web-mercanet.test.sips-services.com/rs-services/v2/paymentInit
Paypage SOAP	https://payment-web-mercanet.test.sips-services.com/services/v2/paymentInit
Office	https://office-server-mercanet.test.sips-services.com/

IMPORTANT: the test shop is configured in "transactionReference mode", with no automatic generation of the transactionReference. Therefore, you need to send the populated transactionRefence field in your test requests.

Step 3 - Subscribe to the production service

Your shop is not registered with Mercanet.

If your shop has not yet been registered, you must fill in the registration form and return it to BNP Paribas.

Your shop is already registered withMercanet.

If your shop is already registered with Mercanet, you must confirm with BNP Paribas that you have access to Office Batch or Office (M2M).

Step 4 - Start and validate the service in production

You must change the URL to connect to the Mercanet production server using the credentials you received when registering merchangtId, secretKey, and keyVersion.

Mercanet URL	URL of the Mercanet payment server retrieved by e-mail.
MerchantId	Shop ID received by e-mail.
SecretKey	Secret key you retrieve via the Mercanet Téléchargement extranet.
KeyVersion	Secret key version retrieved on Mercanet Téléchargement (obviously 1 for the 1st key).

Tip: a common mistake is to forget one of these four parameters, which always leads to an error.

If you want to customize your payment pages, please follow the procedure described in the Custompages documentation.