Content


Introduction

This page specifies the parameters to be used for authentication and authorization of payments

  • recurring with a defined number of installments of the same amount;
  • other recurring, ie recurring payments of variable amounts and / or of indefinite duration;
  • soucription, also called NX or installments.

Workflow

These payments are realized in two steps :

  1. an order phase associated with the first installment payment, initiated by the buyer on the e-merchant pages called CIT, Customer Initiated Transaction ;
  2. a second realize payment requests for following installments initiated by the merchant called MIT Merchant Initiated Transaction. The shopper is not present.

The payment request for the first installment must be authenticated with a challenge.
The card number can be entered by the buyer or retrieved from a card on file created previously.

The following requests are transmitted :

  • without prior authentication request ;
  • by referencing the first authorization.


Validation of authentication and authorization requests

Here, you find the values ​​objects for web service interface (cf. authentication an dauthorization processing).

First, the ​​common values to authentication and authorization requests, then the authorization specifics value.


First request

Common values for authentication and authorization requests, then the specifics of the authorization

The tables below give the values ​​and the presence of the different fields for the specific case of NX and recurring payments


ParameterMandatoryComment
versionOLa version doit être supérieure ou égale à 28
Objet Payment
  amountF

Amount of the first installment. The other installments must have an amount less than or equal to that of the first.

  actionO

122 : authorization for a recurring payment with constant amount and fixed duration.

123 : authorization + capture for recurring payment with constant amount and fixed duration.

124 : authorization for an installment payment, NX, or installment.

125 : authorization + capture for an installment payment, NX, or installment.

128 : authorization for other recurring payments.

129 : authorization + capture for other recurring payments.

  modeOCPT
  cumulatedAmountO0
Objet Order
  amountF

Order total amount.

Objet Recurring
  firstAmountO

First installment amount (priority on payment.amount).

  amountC

Following installments amount.

Mandatory for action codes : 122, 123, 124, 125.

Empty for action codes : 128, 129.

  billingCycleC

Frequency, for example 40 for a monthly recurrence

Mandatory for action codes : 122, 123, 124, 125.

Empty for action codes : 128, 129.

  billingLeftC

Total installments number (3 for payment 3 times, ...).

Mandatory for action codes : 122, 123, 124, 125.

Empty for action codes : 128, 129.

  billingRankO

1 for fisrt installment.

  endDateC

Last installment date (take a margin that includes the time necessary to repeat the last payment request in error case).

Mandatory for action codes : 122, 123, 124, 125.

Empty for action codes : 128, 129.

Objet Buyer
  ipC

Must be valued when the buyer uses a web browser.

Objet ThreeDSinfo
  ChallengeIndF

Payline forces the challenge request into the request sent to the ACS.

This is a DSP2 regulatory.

The merchant is not required to complete this field.

  browserC

Must be valued when the buyer uses a web browser.

  sdkC

Must be valued when the buyer is logged in via a mobile application using a sdk plugin.

Spécificités autorisation

Authorization can be done with a

  • doAuthorization;
  • doImmediateWalletPayment;


ParameterMandatoryComment
authentication3DSecure.mdO
authentication3DSecure.paresO


Save payment data in Payline wallet

This step allows payment data to be stored in a Payline wallet.

It is only possible if the authorization has been done with a doAuthorization.

It is optional.

You must use the createWallet web service specifying:

  1. the contract number
  2. the wallet identifier
  3. the Payline transaction identifier given in response to the doAuthorization.


Other installments

Payment requests for other installments are initiated by the merchant without the shopper, there is no authentication.

Authorization settings

The authorization request can be realized using :


ParameterMandatoryComment
linkedTransactionIDC

Value returned in the first authorization response in the 'linkedTransactionId' parameter.

If the initial authorization is realized before the RTS SCA application, refer to "Grand fathering" description below.

Optional for 128/129 actions with using of doImmediateWalletPayment or doScheduledWalletPayment if the wallet was created with the first installment transaction (Payline uses the linkedTransactionID stored when the wallet was created).

Mandatory in other cases.

resultContainerC

Value returned in the first authorization response in the 'resultContainer' parameter.

Missing if Grand fathering,

Optional for 128/129 actions with using of doImmediateWalletPayment or doScheduledWalletPayment if the wallet was created with the first installment transaction (Payline uses the linkedTransactionID stored when the wallet was created).

Mandatory in other cases.

Objet Payment
  actionO

Same value as in previous calls.

  modeOCPT
  amountOInstallment amount (priority ib recurring.amount).
  cumulatedAmountC

Sum of amounts already authorized.

Missing for 'other recurring payments'.
Objet Recurring
  billingRankC

2 for the 2nd installment, 3 for the 3rd, etc ...

Mandatory for action codes : 122, 123, 124, 125.
Recommended for action codes : 128, 129, value strictly greater than 1.
.. others fields
Same value as in previous calls.




Authenticated amount

The table below specifies the amount to be provided for authentication request for each payment type.

PaymentPayment codeAuthenticated amount

recurring with defined installments number and same amount

122 or 123

Total amount : sum of installments amount

other installments128 or 129

First installment amount.

For American Express, Mastercard, the other installments amount must not exceed that of the first one.

(TO BE CONFIRMED).

NX, installments124 or 125Total amount : sum of installments amount

Grand fathering

This paragraph deals with recurring and Nx payments initiated before DSP2 application and which could not retrieve the initial authorization reference from the authorization server.

For each installment payment request, the merchant  :

  • sends as initial transaction identifier the value: '**PV4-999999999999'
  • retrieves the transaction identifier in the response to the payment request
  • if this identifier is different from '**PV4-999999999999', stores it and uses it as the initial transaction identifier in subsequent payment requests.

The resultContainer is never sent.

Card change and renewal

This paragraph process the case of changing the card for a recurring payment or n times in progress.

The change is realized by the buyer on the merchant web pages.

The merchant offers his shopper to modify his payment data.

The merchant realizes a recurring payment request with variable amount and with an unlimited duration (code 128).

The merchant retrieves the identifier (linkedTransactionId) and the resultContainer.

The merchant can continue the installment request using the new identifier and the new resultContainer.


Linked pages