Subscription payment via duplication

Introduction

Sogenactif 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 Sogenactif solution.

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

Functional presentation
Functionality set-up guide

Note: Sogenactif 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 Sogenactif 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 Sogenactif 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.).

Contacting the support

For any question or request for technical assistance, you can contact the usual Sogenactif support on 0 825 090 095 (0.15€/min + call charge - rate as of 02/11/2022) from Monday to Friday, from 9am to 7pm, excluding public holidays, or write to supportsogenactif@worldline.com specifying your VAD or MID contract number for a more efficient handling of your request.

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 Sogenactif connectors for subscription

Because Sogenactif 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	Sogenactif Paypage	Sogenactif Office Serveur	Sogenactif Office Serveur CSE	Sogenactif In-App	Sogenactif Office Batch	Sogenactif Gestion 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 Sogenactif 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 Sogenactif In-App.
You display and secure the pages for entering payment details	X	V	V	V	X	X	Sogenactif Office Serveur meets your need for e-commerce. For m-commerce, we recommend the use of Sogenactif 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	Sogenactif Office Batch file mode is the connector suitable for the massive recurring payment processing, but you can also use Sogenactif Office Serveur.
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 Sogenactif Office Serveur 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	Sogenactif Office Batch allows you to initialise the subscriber base from an existing database.

Implementation

Enrolling the subscriber (CIT)

Enrolling the subscriber with Sogenactif Paypage

The collection of payment details is done on Sogenactif 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 Sogenactif Paypage by including the transaction data in the request (amount of the first due date, currency, etc.).
Sogenactif displays the payment page, the subscriber provides their payment details and then validates.
Sogenactif performs the 3-D Secure checking.
Sogenactif performs anti-fraud checks.
Sogenactif sends an authorisation request to the acquirer.
Sogenactif saves the transaction in the back office.
Sogenactif returns you the manual and automatic responses containing the transaction details. You store your transaction reference and the card expiry date.
Sogenactif 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 Sogenactif Paypage request, please refer to one of the Sogenactif 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

Sogenactif returns a classic manual and automatic Sogenactif 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 Sogenactif Paypage connector guide to analyse the response from Sogenactif.

Enrolling the subcriber with Sogenactif Office Serveur

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 Sogenactif documentation to find out the full parameters of the request).
cardValidateAuthenticationAndOrder: cardholder authentication and authorisation request (see the JSON or SOAP Sogenactif 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 Sogenactif Office Batch

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

Description

You format a Sogenactif 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 Sogenactif via FTPS or SFTP.
Sogenactif retrieves the subscriber’s payment details.
Sogenactif runs fraud checks you set up on your shop.
Sogenactif sends the authorisation requests to acquirers.
Sogenactif stores the transaction in the back office.
Sogenactif formats the response file and returns it to you.
In the evening, Sogenactif sends the remittances for accepted transactions.

Please read the Sogenactif Office Batch XML or Sogenactif 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 Sogenactif Office Batch XML or Sogenactif 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 Sogenactif Office Batch connectors guides to analyse the response from Sogenactif.

Recurring payments with Sogenactif Office Serveur

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

Please refer to one of the Sogenactif Office Serveur 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	Sogenactif Paypage Sogenactif Office Serveur Sogenactif In-App	Sogenactif Office Serveur Sogenactif 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	Sogenactif Paypage Sogenactif Office Serveur Sogenactif In-App	Sogenactif Office Serveur Sogenactif 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 Sogenactif interfaces that meet your needs (see the 'Choosing the Sogenactif connectors for subscription' section), will you need to integrate the connectors to connect your site to Sogenactif and to follow the instructions in the 'Implementation' section.

Step 2 - Test the service on the test environment

Once you have implemented the Sogenactif 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-webinit-sogenactif.test.sips-services.com/paymentInit
Paypage JSON	https://payment-webinit-sogenactif.test.sips-services.com/rs-services/v2/paymentInit
Paypage SOAP	https://payment-webinit-sogenactif.test.sips-services.com/services/v2/paymentInit
Office	https://office-server-sogenactif.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 Sogenactif.

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

Your shop is already registered withSogenactif.

If your shop is already registered with Sogenactif, you must confirm with SG that you have access to Sogenactif Office Batch or Sogenactif Office Serveur.

Step 4 - Start and validate the service in production

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

Sogenactif URL	URL of the Sogenactif payment server retrieved by e-mail.
MerchantId	Shop ID received by e-mail.
SecretKey	Secret key you retrieve via the Sogenactif Téléchargement extranet.
KeyVersion	Secret key version retrieved on Sogenactif 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.