Operations

Introduction

Each Dalenys platform’s operation return a couple EXECCODE MESSAGE to describe the result of the operation.

In case of a valid request, a TRANSACTIONID is returned.

tips

Make sure to store in your system the TRANSACTIONID for later usage (refund, capture, support requests, matching … ).

warning

Keep in mind that it is not allowed to launch multiple editing transactions at the same moment (concurrent accesses), (such as refunds or captures…) on the same initial transaction. This would result in a refusal to process these operations and an EXECCODE = 2017

Please note that not all of the operations listed below are available on all payment methods and integration modes.

Card information request

To simply get information about the user’s card, you can proceed an authorization operation by setting the AMOUNT parameter to 0.

This operation makes it possible to check the card information (PAN, expiry, cryptogram) without any impact on the end user payment limits.

info

In case the amount of the request is zero, the AUTHORIZATIONTYPE parameter is useless and would be ignored.

info

Card information requests cannot be captured or voided.

tips

For card registration, please refer to the recurring payment section.

The transaction return will contain some useful information as :

  • CARDTYPE string

    The payment method type.

    Example: VISA

  • CARDNETWORK VISA, AMERICAN EXPRESS, MASTERCARD, BANCONTACT, CARTE BLEUE, UNKNOWN

    The cardholder’s bank card network.

    Example:

  • CARDCOUNTRY string(2)

    The country code (format ISO_3166-1_alpha-2).

    Example: US

  • CARDCODE string(12-19)

    A truncated version of the card number.

    Example: 1111222233334444

  • CARDVALIDITYDATE date(MM-YY)

    Card expiry date.

    Example: 12-17

  • CARDFULLNAME string(1-255)

    The holder’s full name (as described on the payment method).

    Example: JOHN SNOW

Payment

The payment operation is the simplest action available on the Dalenys platform.

It simply consists in requesting to debit a user of the amount you specify.

Authorization

This operation makes it possible to hold the transaction’s amount on the cardholder bank account, for later collection triggerable with a capture operation.

info

An authorization can only be captured once.

warning

Some payment methods require you to capture an authorization within a limited timeframe. The expiration delay of an authorization depends on the payment method and its regulations. The standard timeframe is 7 calendar days.

Capture

The capture operation requires a valid TRANSACTIONID from a previous, succeeded and still not captured transaction. A single authorization does not affect the user account until you decide to capture it. The authorization / capture workflow is well suited for delayed payment scenario.

warning

Some payment methods authorize a partial capture of an authorization. To do so, just add the optional AMOUNT parameter to your capture request.
When not specified, 100% of the authorization amount is captured.
AMOUNT cannot be higher than the initial authorization amount.

info

An authorization can only be captured once.

warning

Some payment methods require you to capture an authorization within a limited timeframe. The expiration delay of an authorization depends on the payment method, its regulations and AUTHORIZATIONTYPE.

reminder
  • finalauthorization can be captured within 7 calendar days.
  • preauthorization can be captured within 30 calendar days.

Scheduled capture

A capture can be planned ahead by adding the parameter CAPTUREDATE to your initial authorization request.

info

A manual capture, (triggered by the merchant with a server to server request or via the Dalenys Extranet), cancels the configured CAPTUREDATE

info

The CAPTUREDATE parameter must at least refer to the next day.

info

The schedule is configured on the Paris-Madrid timezone.

Refund

A refund operation enables you to credit funds back to a end-user following a previous debit.

A refund transaction is always linked to a successsful payment or capture transaction which it requires the original TRANSACTIONID.

The amount of a refund transaction can be different from the original debit transaction but can not be higher.

You can refund several times a same debit transaction, but the sum of all the refund operations can’t be higher that the original debit amount.

A refund transaction has an impact on the user’s bank account since he will see the funds being credited on his bank statement.

Credit and Credit Fund Transfer

A credit transaction is a special transaction type allowing to give money to the user.

This transaction type should be used in some very special cases (custom refund situations …).

info

credit transaction are not allowed to all customers by default. You have to contact your account manager to validate the usage conditions and to activate this feature.

If your activity is related to gambling, all your credit operations will be processed as Credit Fund Transfer operation (CFT).

The only technical difference with a standard credit transaction is that you have to provide a reference TRANSACTIONID of a succeeded and authenticated transaction (3DSECURE).

Void

This operation can be used to cancel the very last operation of any transaction. (Except the void operation itself, of course)

For example, once captured, an authorization cannot be voided, only the capture could be.

All transactions except authorizations can only be voided on the same day they are processed, that is to say before the funds are sent for compensation to the user’s bank.

An authorization can be voided for the duration of its lifetime as long as it has not been captured.

N-times payment

It is possible to easily split a payment in several installments. The Dalenys platform will process the first installment immediately and in case of acceptation of the first installment, the platform will process the following installments at the given dates. All these installments will result in different transactions sharing the same ORDERID field as the one in the first installment.

To initiate a split payment, you have to replace the AMOUNT parameter by:

  • AMOUNTS hash

    A hash of keys / values where keys are dates and values are the amounts to process:
    Dates have to be in format YYYY-MM-DD;
    Amounts in the smallest money decimal (e.g. cents for euro);
    See the dedicated section.

    Example: {#<Date: 2016-01-01 ((2457389j,0s,0n),+0s,2299161j)>=>50000, #<Date: 2016-02-01 ((2457420j,0s,0n),+0s,2299161j)>=>20000, #<Date: 2016-03-01 ((2457449j,0s,0n),+0s,2299161j)>=>10000}

For example, an AMOUNTS for a 3 installments split:

  • 200€ on 2019-07-18
  • 100€ on 2019-08-18
  • 100€ on 2019-09-18
AMOUNTS[2019-07-18]=20000&AMOUNTS[2019-08-18]=10000&AMOUNTS[2019-09-18]=10000

A n-times transaction must follow these conditions:

  • The time-zone you must use for any n-times transaction is UTC.
  • The first installment must be on the day of the request and will be executed immediately.
  • The interval between the first and last installment must not exceed 90 days.
  • The last installment must occur before the card’s expiry date.
info
  • Only payment transactions can be split with n-times mode.
  • If the first transaction is refused, the other scheduled transactions won’t be processed, the whole request is considered as refused
  • Schedule dates should be supplied in UTC format.
tips

AMOUNT and AMOUNTS can not be used at the same time.

The first TRANSACTIONID of a n-times schedule will be the schedule reference: SCHEDULEID.

We can configure automatic retries for each installments. To enable and configure this feature, please contact your payment manager.

N-times schedule can be canceled by using the stopntimes operation.

Stop n-times

This operation is used to abort forthcoming installments of an n-times transaction, by providing its SCHEDULEID:

info

Please note that the past installments won’t be refunded with this operation, you must use classic refund operation to refund each installment.

Recurring payment

Basic usage

It is possible to implement tailor-made recurring payment workflows without storing any sensitive card data by simply using our aliasing features.

You have to add 2 parameters in your payment, authorization or credit initial request.

  • CREATEALIAS boolean

    Ask for a payment method ALIAS creation. Caution: this parameter is mutually exclusive with DISPLAYCREATEALIAS. See the dedicated section.

    Example: true

  • ALIASMODE oneclick, subscription

    Indicates the ALIAS usage mode:
    oneclick indicates a one click or an online transaction;
    subscription indicates an offline transaction.

    Example: oneclick

In the request’s direct response, as well as redirection and notification, you will retrieve the parameter ALIAS:

  • ALIAS string(1-40)

    Identifier of a previously processed payment method.

    Example: A1-fc5bafe3-8c12-4314-95c7-2e15ec3220e0

This parameter is a non-sensible reference for the used payment method in our platform. You have to store and keep this reference in your database for later use.

For each recurring transaction processed on the same ALIAS for the same user on the same payment method, you don’t need to provide the usual payment method details (ie: CARDCODE, CARDVALIDITYDATE, CARDCVV, CARDFULLNAME):

  • ALIAS string(1-40)

    Identifier of a previously processed payment method.

    Example: A1-fc5bafe3-8c12-4314-95c7-2e15ec3220e0

  • ALIASMODE oneclick, subscription

    Indicates the ALIAS usage mode:
    oneclick indicates a one click or an online transaction;
    subscription indicates an offline transaction.

    Example: oneclick

warning

In case of execcode 4018, fees could be applied for each new transaction attempt.

Example

Here is a server to server request example:

$> curl --request POST --url "https://secure-test.be2bill.com/front/service/rest/process" \
--data "method=payment" \
--data "params[IDENTIFIER]=YOUR_IDENTIFIER" \
--data "params[OPERATIONTYPE]=payment" \
--data "params[ORDERID]=1234" \
--data "params[ALIAS]=A1-fc5bafe3-8c12-4314-95c7-2e15ec3220e0" \
--data "params[ALIASMODE]=oneclick" \
--data "params[AMOUNT]=1000" \
--data "params[CLIENTIDENT]=john.snow" \
--data "params[CLIENTEMAIL]=john.snow@example.com" \
--data "params[CLIENTUSERAGENT]=Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0" \
--data "params[CLIENTIP]=10.1.1.1" \
--data "params[CARDFULLNAME]=JOHN SNOW" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

Oneclick with CVV

With ALIASMODE valued to oneclick you can optionally ask the user for the cryptogram and supply it in the recurring request (parameter CARDCVV). The cryptogram will be verified by the user’s bank to grant or deny the transaction.

The hosted-fields integration way of Oneclick transaction with CVV, allows you to implement a single CVV hosted-field.

security

Keep in mind that storing the cryptogram is forbidden.

Hosted-form option

In a hosted form integration, you can allow the user to choose to register to a recurring workflow or not by providing the parameter:

  • DISPLAYCREATEALIAS boolean

    Display a checkbox on the hosted form to ask the user to save his card data for future usage. Caution: this parameter is mutually exclusive with CREATEALIAS. See the dedicated section.

    Example: true

When this parameter is valued to true, the hosted form will display a check-box asking for granting Dalenys the permission to store payment method data for easier later re-use.

Authentication (3-D Secure / Secure Code / Safekey)

Almost every card scheme implements an authentication system : 3-D Secure for Visa, Secure Code for Mastercard, Safekey for American Express (…) 3-D Secure is an authentication protocol designed to be an additional security layer for online transactions. The 3-D Secure protocol helps you to mitigate fraud and provide a liability shift to your transactions in case of chargebacks.

tips

Auto trigger rules can be set with the Payment Manager.

info

The 3-D Secure process concerns payment and authorization transactions.

There is actually 2 versions of the 3-D Secure protocol: 3-D Secure 1.0 and 3-D Secure 2.0 which enforces security with strong customer authentication.

3-D Secure 1.0

The 3-D Secure V1 is the legacy authentication mode for bank card transactions.

Parameters

To trigger a 3-D Secure authentication you should add the following parameters to your authorization or payment request:

  • 3DSECURE boolean

    Ask for a 3-D Secure V1 authentication.

    Example: true

  • 3DSECUREDISPLAYMODE main,popup,top,raw

    Define the 3-D Secure authentication page display mode:
    main: in the current frame;
    popup: in a browser popup;
    top: in the parent frame (useful in case of iframe integration);
    raw: to handle the redirection by yourself.

    Example: main

info

On the Sandbox environment, you must use a specific PAN dedicated to trigger execcode 0001. Please consult the section “Sandbox test card numbers” of compatible payment methods.

Server to server integration

In case of server to server integration, you should redirect the user to the authentication page.

Once submitted and accepted by the Dalenys platform, the request will result in an EXECCODE 0001. This EXECCODE means that the transaction is waiting for the authentication process.

In case of EXECCODE 0001, you will receive a new parameter in the response: REDIRECTHTML. This parameter is a html redirection code encoded with base64, so you have to base64_decode it and display it to the end user.

Because of the redirection, you have to wait for the user to come back to your platform to retrieve the transaction’s final result.

When you choose 3DSECUREDISPLAYMODE=raw you will receive these two parameters instead of REDIRECTHTML:

  • REDIRECTURL string(no length limit)

    The url to redirect the user to continue the processing.

    Example: http://some_url?p1=v1

  • REDIRECTPOSTPARAMS string(no length limit)

    The POST parameters to send when 3DSECUREDISPLAYMODE is valued to “raw”. The redirection should send the user to the url pointed by REDIRECTURL.

    Example: p1=v1&p2=v2

Therefore, you have to redirect the user by yourself by making him submit a POST request with REDIRECTPOSTPARAMS as POST parameters to REDIRECTURL as destination.

3-D Secure 2.0

First of all, you have only small things to change to your implementation workflow regarding a classical 3-D Secure 1.0 implementation.

The Dalenys 3-D Secure 2.0 integration is similar to the former version one.

tips

During the migration to 3-D Secure 2.0, your have to ask an activation to your account manager.

Our gateway will automatically handle the confusing and complicated part of the 3-D Secure 2.0 protocol and transition:

  • Strong Customer Authentication exemption handling. This clearly allows you to benefit from optimal conversion rate.

  • Fallback to 3-D Secure 1.0 in case of the 2.0 version is not applicable to the payer card. In the first months we can easily suppose that all issuers won’t be ready to support 2.0 version. The fallback to former version will be automatically handled by our gateway.

3-D Secure 2.0 requires new input parameters in your payment and authorization requests. These parameters allow a better tracking of the card holder by the bank network. Some of these parameters are mandatory and some are optionals.

tips

In order to benefit of the best conversion rate, you have to supply as much information as possible. It will lead in an increase of frictionless rate.

Standard parameters

You have to include these parameters regardless of your integration mode.

  • BILLINGCITY string(1-255)

    The billing city.

    Example: New York

  • BILLINGCOUNTRY string(2)

    The country code (ISO_3166-1_alpha-2).

    Example: US

  • BILLINGADDRESS string(1-50)

    The billing address. Be careful not to integrate any line breaks.

    Example: 285 Fulton Street

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

    Example: 10007

  • SHIPTOCITY string(1-255)

    The shipping city.

    Example: New York

  • SHIPTOCOUNTRY string(2)

    The country code (ISO_3166-1_alpha-2 format)

    Example: US

  • SHIPTOADDRESS string(1-50)

    The shipping address.

    Example: 55 rue de la liberté

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

    Example: 10007

  • SHIPTOADDRESSTYPE billing, verified, new, storepickup, edelivery, travelpickup, other

    Shipping indicator. The parameter DELIVERYEMAIL is mandatory when edelivery mode is set.
    The other ship to address fields are optional when ‘storepickup’, travelpickup or other is set.

    Example: verified

  • 3DSECURECHALLENGEWINDOWSIZE 01, 02, 03, 04, 05

    Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width x height in pixels of the window displayed in the Cardholder browser window.

    By default, Dalenys will set the challenge window size to full size.

    Related resolutions (width x height):

    01 250 x 400
    02 390 x 400
    03 500 x 600
    04 600 x 400
    05 Full screen

    Example: 04

  • 3DSECUREDISPLAYMODE main,popup,top,raw

    Define the 3-D Secure authentication page display mode:
    main: in the current frame;
    popup: in a browser popup;
    top: in the parent frame (useful in case of iframe integration);
    raw: to handle the redirection by yourself.

    Example: main

  • 3DSECUREPREFERENCE sca, frictionless, nopref, scamandate

    3DS Requestor Challenge Indicator. Mandatory for CB.

    Acccepted values:

    sca ask for a strong authentication;
    frictionless ask for a frictionless authentication;
    nopref or absent, the decision will be made by Dalenys;
    scamandate strong authentication required by regulation;

    Example: sca

  • CLIENTAUTHMETHOD guest, credentials, federated, issuer, thirdparty, fido

    Mechanism used by the Cardholder to authenticate.

    Accepted values:

    guest: No merchant authentication occurred (i.e. cardholder “logged in” as guest);
    credentials: Login to the cardholder account at the merchant system using merchant’s own credentials;
    federated: Login to the cardholder account at the merchant system using federated ID;
    issuer: Login to the cardholder account at the merchant system using issuer credentials;
    thirdparty: Login to the cardholder account at the merchant system using third-party authentication;
    fido: Login to the cardholder account at the merchant system using FIDO Authenticator;

    Example: credentials

  • ACCOUNTCHANGEDATE date(YYYY-MM-DD)

    Date that the cardholder’s account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.

    Example: 2018-01-10

  • ACCOUNTCREATIONDATE date(YYYY-MM-DD)

    Date that the cardholder opened the account with the 3DS Requestor.

    Example: 2018-01-10

  • PASSWORDCHANGEDATE date(YYYY-MM-DD)

    Date that cardholder’s account with the 3DS Requestor had a password change or account reset.

    Example: 2018-01-10

  • LAST6MONTHSPURCHASECOUNT integer

    Number of purchases with this cardholder account during the previous six months.

    Example: 4

  • LAST24HOURSADDCARDATTEMPTS integer

    Number of “Add Card” attempts in the last 24 hours.

    Example: 2

  • LAST24HOURSTRANSACTIONCOUNT integer

    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.

    Example: 4

  • LAST12MONTHSTRANSACTIONCOUNT integer

    Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.

    Example: 4

  • CARDENROLLDATE date(YYYY-MM-DD)

    Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.

    Example: 2018-01-01

  • SHIPTOADDRESSDATE date(YYYY-MM-DD)

    Date when the shipping address used for this transaction was first used with the 3DS Requestor.

    Example: 2018-04-02

  • SUSPICIOUSACCOUNTACTIVITY yes, no

    Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.

    Example: `no`

  • BILLINGSTATE string

    The state or province of the Cardholder billing address associated with the card used for this purchase. Should be the country subdivision code defined in ISO 3166-2

    Example: FR-IDF

  • HOMEPHONE string(max 32)

    The home phone number provided by the Cardholder in international (E.164) format.

    Example: +33133333333

  • MOBILEPHONE string(max 32)

    The mobile phone number provided by the Cardholder in international (E.164) format.

    Example: +33633333333

  • SHIPTOSTATE string

    Shipping indicator.
    The parameter DELIVERYEMAIL is mandatory when edelivery mode is set.
    The other ship to address fields are optional when ‘storepickup’, travelpickup or other is set.

    Example: FR-IDF

  • WORKPHONE string(max 32)

    The work phone number provided by the Cardholder in international (E.164) format.

    Example: +33633333333

  • DELIVERYEMAIL email(5-255)

    For Electronic delivery, the email address to which the merchandise was delivered.

    Example: john.snow@example.com

  • DELIVERYTIMEFRAME electronic,sameday,overnight,longer,

    Indicates the merchandise delivery timeframe.

    Example: sameday

  • GIFTCARDAMOUNT integer

    For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in minor units (cents).

    Example: 100

  • GIFTCARDCOUNT integer

    For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.

    Example: 2

  • GIFTCARDCURRENCY string(3)

    For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.

    Example: EUR

  • PREORDERDATE date(YYYY-MM-DD)

    For a pre-ordered purchase, the expected date that the merchandise will be available.

    Example: 2018-02-01

  • ITEMAVAILABILITY yes, no

    Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

    Example: true

  • REORDERINGITEM yes, no

    Indicates whether the cardholder is reordering previously purchased merchandise.

    Example: false

  • RECURRINGEXPIRY date(YYYY-MM-DD)

    Date after which no further authorisations shall be performed in a recurring payment workwlow.

    Example: 2020-01-04

  • RECURRINGFREQUENCY integer

    Indicates the minimum number of days between authorisations.

    Example: 10

warning

Depending on the value of the SHIPTOADDRESSTYPE parameter, the mandatory status of some related parameters changes:

SHIPTOADDRESSTYPE values Affected parameters
EDELIVERY DELIVERYEMAIL becomes mandatory
VERIFIED, NEW or BILLING SHIPTOCOUNTRY, SHIPTOADDRESS, SHIPTOCITY and SHIPTOPOSTALCODE become mandatory
STOREPICKUP or TRAVELPICKUP or OTHER DELIVERYEMAIL, SHIPTOCOUNTRY, SHIPTOADDRESS, SHIPTOCITY , SHIPTOPOSTALCODE become optional
Server-to-server and hosted-fields integration modes

Some parameters become mandatory when integrating in server-to-server or hosted-fields mode:

  • CLIENTACCEPTHEADER string(max 2048)

    Browser HTTP accept header. Mandatory for server to server requests.

    Example: application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5

  • CLIENTIP ipv4

    The user’s public IP address.

    Example: 10.1.1.1

  • CLIENTJAVAENABLED yes, no

    Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.

    Example: `no`

  • LANGUAGE fr, en, de, es, it, nl, zh, ru, pt, cs

    Configure the hosted form display language.

    Example: en

  • CLIENTSCREENCOLORDEPTH int(1-2)

    Value representing the bit depth of the colour palette for displaying images, in bits per pixel.

    Obtained from Cardholder browser using the screen.colorDepth property.

    Accepted values:
    1 = 1 bit
    4 = 4 bits
    8 = 8 bits
    15 = 15 bits
    16 = 16 bits
    24 = 24 bits
    32 = 32 bits
    48 = 48 bits

    Example: 32

  • CLIENTSCREENHEIGHT int(1-6)

    Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property.

    Example: 1280

  • CLIENTSCREENWIDTH int(1-6)

    Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property.

    Example: 1024

  • TIMEZONE string(1-128)

    Timezone / default value : UTC. Please see the Data sheet dedicated list of available timezones.

    Example: Europe/Paris

  • CLIENTUSERAGENT string(1-255)

    The HTTP user agent.

    Example: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0

Browser parameters

You have to include these parameters in a client browser integration (web).

  • CLIENTACCEPTHEADER string(max 2048)

    Browser HTTP accept header. Mandatory for server to server requests.

    Example: application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5

  • CLIENTJAVAENABLED yes, no

    Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.

    Example: `no`

  • CLIENTSCREENCOLORDEPTH int(1-2)

    Value representing the bit depth of the colour palette for displaying images, in bits per pixel.

    Obtained from Cardholder browser using the screen.colorDepth property.

    Accepted values:
    1 = 1 bit
    4 = 4 bits
    8 = 8 bits
    15 = 15 bits
    16 = 16 bits
    24 = 24 bits
    32 = 32 bits
    48 = 48 bits

    Example: 32

  • CLIENTSCREENHEIGHT int(1-6)

    Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property.

    Example: 1280

  • CLIENTSCREENWIDTH int(1-6)

    Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property.

    Example: 1024

  • LANGUAGE fr, en, de, es, it, nl, zh, ru, pt, cs

    Configure the hosted form display language.

    Example: en

  • TIMEZONE string(1-128)

    Timezone / default value : UTC. Please see the Data sheet dedicated list of available timezones.

    Example: Europe/Paris

Mobile / SDK parameters

You have to include these parameters for mobile in-app integration:

  • 3DSECURESDKAPPID uuid(36)

    Universally unique ID created upon all installations and updates of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation or update. Canonical format as defined in IETF RFC 4122.

    Example: 4dc406b0-038d-43ef-a96c-c85352c5e2c0

  • 3DSECURESDKENCRYPTEDDATA string(1-64000)

    JWE Object as defined in Section 6.2.2.1 containing data encrypted by the SDK for the DS to decrypt. Note: This element is the only field encrypted in this version of the EMV 3-D Secure specification.

    Example:

  • 3DSECURESDKEPHEMPUBLICKEY string(1-256)

    Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS. In AReq, this data element is present as its own object.

    Example:

  • 3DSECURESDKMAXTIMEOUT integer(1-2)

    Indicates maximum amount of time (in minutes) for all exchanges. Must be equal or greater than 5.

    Example: 5

  • 3DSECURESDKREFERENCENUMBER string(1-32)

    Identifies the vendor and version for the 3DS SDK that is integrated in a 3DS Requestor App, assigned by EMVCo when the 3DS SDK is approved.

    Example:

  • 3DSECURESDKTRANSACTIONID string(1-36)

    Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.

    Canonical format as defined in IETF RFC 4122. This may utilise any of the specified versions as long as the output meets specified requirements.

    Example: 4dc406b0-038d-43ef-a96c-c85352c5e2c0

New return parameters

  • 3DSECUREVERSION 1, 2

    The version of the 3-D Secure protocol.

    Example: 2

  • REDIRECTURL string(no length limit)

    The url to redirect the user to continue the processing.

    Example: http://some_url?p1=v1

  • REDIRECTPOSTPARAMS string(no length limit)

    The POST parameters to send when 3DSECUREDISPLAYMODE is valued to “raw”. The redirection should send the user to the url pointed by REDIRECTURL.

    Example: p1=v1&p2=v2

New notification parameters

  • 3DSECURECHALLENGESTATUS y, n, u, a, r

    Challenge result:

    y = authentication successful
    n = not authenticated
    u = unavailable
    a = attempted
    r = rejected

    Example: y

  • 3DSECUREMODE sca, frictionless

    sca ask for a strong authentication;
    frictionless ask for a frictionless authentication;\

    Example: `sca`

  • 3DSECUREVERSION 1, 2

    The version of the 3-D Secure protocol.

    Example: 2

External MPI

It’s possible to use your own 3-D Secure MPI, you have to ask the activation of this option to your payment manager and then add the following fields to your 3-D Secure transactions :

Here are the parameters for 3-D Secure 1.0 requests:

  • 3DSECUREXID hexadecimal string(max 40)

    3-D Secure X id.

    Example:

  • 3DSECURECAVV hexadecimal string(max 40)

    3-D Secure “Cardholder Authentication Verification Value”.

    Example: 8c47ab90f2b9c3219208115b182f520360000000

  • 3DSECURECAVVALGORITHM int (1)

    3-D Secure “Cardholder Authentication Verification Value” algorithm(0-9).

    Example: 3

  • 3DSECURERESULT int (6)

    6 character value composed of 3DSECURESTATUS converted to hexadecimal concatenated with the result VRes converted to hexadecimal

    Example: 590040

  • 3DSECUREECI string (1)

    Electronic Commerce Indicator.

    Example: 5

  • 3DSECURECARDENROLLED u, n, y

    Card’s enrollment status.

    Example: y

  • 3DSECURESTATUS u, n, a, y, r

    3-D Secure status:

    y = authentication successful
    n = not authenticated
    u = authentication unavailable
    a = authentication attempted
    r = authentication rejected

    Example: y

  • 3DSECUREVERSION 1, 2

    The version of the 3-D Secure protocol.

    Example: 2

Here are the parameters for 3-D Secure 2.0 requests

info

A 3-D Secure authentication is not required for out of scope transactions. Therefore, the 3-D Secure 2.0 required parameters become optional if 3DSECUREOUTOFSCOPEREASON is sent.

  • 3DSECUREDSTRANSACTIONID string(max 26)

    Directory Server transaction id.

    Example: 456456465sdfsdfsd564

  • 3DSECURECAVV hexadecimal string(max 40)

    3-D Secure “Cardholder Authentication Verification Value”.

    Example: 8c47ab90f2b9c3219208115b182f520360000000

  • 3DSECURECAVVALGORITHM int (1)

    3-D Secure “Cardholder Authentication Verification Value” algorithm(0-9).

    Example: 3

  • 3DSECUREECI string (1)

    Electronic Commerce Indicator.

    Example: 5

  • 3DSECURESTATUS u, n, a, y, r

    3-D Secure status:

    y = authentication successful
    n = not authenticated
    u = authentication unavailable
    a = authentication attempted
    r = authentication rejected

    Example: y

  • 3DSECURETRANSACTIONSTATUSREASON string(2)

    Transaction status reason. Mandatory for CB transactions.

    Accepted values:

    01 = Card authentication failed
    02 = Unknown Device
    03 = Unsupported Device
    04 = Exceeds authentication frequency limit
    05 = Expired card
    06 = Invalid card number
    07 = Invalid transaction
    08 = No Card record
    09 = Security failure
    10 = Stolen card
    11 = Suspected fraud
    12 = Transaction not permitted to cardholder
    13 = Cardholder not enrolled in service
    14 = Transaction timed out at the ACS
    15 = Low confidence
    16 = Medium confidence
    17 = High confidence
    18 = Very High confidence
    19 = Exceeds ACS maximum challenges
    20 = Non-Payment transaction not supported
    21 = 3RI transaction not supported
    22–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
    80–99 = Reserved for DS use

    Example: 01

  • 3DSECURESCORE string(2)

    CB scoring. Mandatory for CB transactions.

    Example: 25

  • 3DSECUREPREFERENCE sca, frictionless, nopref, scamandate

    3DS Requestor Challenge Indicator. Mandatory for CB.

    Acccepted values:

    sca ask for a strong authentication;
    frictionless ask for a frictionless authentication;
    nopref or absent, the decision will be made by Dalenys;
    scamandate strong authentication required by regulation;

    Example: sca

  • 3DSECUREMODE sca, frictionless

    Applied authentification mode:

    sca Strong authentication;
    frictionless Frictionless authentication;

    Example: `sca`

  • 3DSECUREVERSION 1, 2

    The version of the 3-D Secure protocol.

    Example: 2

  • 3DSECURECHALLENGECANCELATION string(2)

    Challenge Cancellation Indicator. Mandatory for CB transactions.

    Accepted values:

    01 = Cardholder selected “Cancel”
    02 = 3DS Requestor cancelled Authentication
    03 = Transaction Abandoned
    04 = Transaction Timed Out at ACS—other timeouts
    05 = Transaction Timed Out at ACS—First CReq not received by ACS
    06 = Transaction Error
    07 = Unknown
    08-79 = Reserved for future EMVCo use (values invalid until defined by EMVCo)
    80–99 = Reserved for future DS use

    Example: 01

  • 3DSECURECARDENROLLED u, n, y

    Card’s enrollment status.

    Example: y

  • 3DSECUREOUTOFSCOPEREASON mit, moto, one_leg_out, anonymous_prepaid_card

    3-D Secure out of scope reason. Shall be used if the transaction type is out of scope of Strong Customer Authentication (SCA). The following transaction types are out of scope of SCA:

    mit Merchant Initiated Transactions
    moto Mail Order/Telephone Order
    one_leg_out
    anonymous_prepaid_card

    Example: mit

Redirection result

In both server to server and hosted form modes, you will only receive the transaction’s final result once the user is redirected to your platform.

You can then display a confirmation message to the user and process the transaction in your application.

security

You have to check the received HASH against the one you generate, to confirm the request’s origin and integrity before redirecting the user. See this section for more information. Other parameters relating to the original request as AMOUNT and ORDERID must be verified.

Additional notification parameters

3-D Secure transactions can be configured to receive some additional parameters:

  • 3DSECUREAUTHENTICATIONSTATUS y, n, u, a, c, r, empty

    Authentication status:

    y = authentication successful
    n = not authenticated
    u = unavailable
    a = attempted
    c = cardholder challenge required
    r = rejected
    empty = no 3-D Secure

    Example: y

  • 3DSECURESIGNATURESTATUS y, n

    Signature status.

    Example: y

  • 3DSGLOBALSTATUS ok, not_enrolled, unavailable, not_required, ko

    Global status.

    Example: ok

  • CARD3DSECUREENROLLED y, n, u

    Card 3-D Secure enrollment status.

    Example: y

For more information about these parameters or the activation of this feature please contact your payment manager.