Redirections and notifications

Introduction

Redirections occur when a carldholder (user) leaves current page (payment form page, 3-D Secure authentication page…) for a Payplug or supplier URL.

The REDIRECT_URL defines where the end user returns on the merchant website.

Besides, you will receive an Instant Payment Notification (IPN) when a transaction processing is over, to inform you of its status. These notifications are HTTPS requests sent to the NOTIFICATION_URL configured in your account settings.

tips

To circumvent potential redirection failures (after timeout, server unavailability, etc.), we strongly advise you to:

  1. Always use the transaction notification for order management and database updates;
  2. Systematically send an email to the customer confirming the transaction status.

Redirection specifics

Once the end-user finalized his transaction after being redirected (either on Dalenys or a supplier or a bank URL), he would be taken back to the REDIRECT_URL of your choice.

Default redirection

A default REDIRECT_URL has to be defined in the account configuration section of your Dalenys Dashboard:

scope

CANCEL_URL configuration is optional and summons a “cancel” button on the standard payment form.

Dynamic redirection

You can dynamically control the possible redirections after a payment by sending those two parameters:

  • REDIRECTURLCANCEL string(1-2048)

    URL to redirect end-user to after a cancellation.

    Example: http://mydomain.com/cancel

  • REDIRECTURLSUCCESS string(1-2048)

    URL to redirect end-user to after a successful payment.

    Example: http://mydomain.com/purchase-confirmation

info

Both REDIRECTURLSUCCESS and REDIRECTURLCANCEL must be specified.

tips

Dynamic redirection will override the default redirection.

Common details

Upon redirection to the defined REDIRECT_URL, following GET parameters related with the transactions are to be sent:

  • 3DSECURE no, yes

    Merchant’s request for 3D Secure authentication.

    Example: true

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • CARDCODE string(12-19)

    Last 4 digits of holder’s card. It is possible to receive the truncated pan (6 first digits, some X, 4 last digits) in a CARDCODE parameter by asking the activation of the option to your payment manager and by using a secure NOTIFICATION_URL (https).

    Example: XXXXXXXXXXXX4444

  • CARDCOUNTRY string(2)

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

    Example: US

  • CARDFULLNAME string(1-255)

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

    Example: JOHN SNOW

  • CARDNETWORK VISA, AMERICAN EXPRESS, MASTERCARD, BANCONTACT, CB, UNKNOWN

    The cardholder’s bank card network.

    Example:

  • CARDTYPE string

    The payment method type.

    Example: VISA

  • CARDVALIDITYDATE date(MM-YY)

    Card expiry date.

    Example: 12-17

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • CLIENTIDENThttps://myShop/com/redirect/

    Example:

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • CVVRESPONSECODE M, N, P, S, U, X, Y, Z

    Authentication status:

    M = CVV2/CVC2 Matches
    N = CVV2/CVC2 does not Match
    P = Not processed
    S = The CVV2 should be on the card but the merchant indicates it is not.
    U = CVV2/CVC2 Unavailable – issuer does not support this parameter
    X = No information (only for JCB)
    Y = CVC1 Incorrect
    Z = Information not provided

    Example: M

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • EXTRADATA string(1-255)

    Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).

    Example: referrer=myshop.com;order=premium

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

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

    Configure the hosted form display language.

    Example: en

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE authorization, payment, capture, refund, credit, void

    The action you want to process.

    Example: payment

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • SCHEMETRANSACTIONID string(1-55)

    Scheme transaction ID, retrieved in response to the authorization request.

    Example: 11034331402111290210

  • SELECTEDBRAND cb, visa, vpay, electron, mastercard, maestro

    Preferred brand.

    Example: CB

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

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.’

EXECCODE treatment is necessary to display an adequate transaction result to the end-user on the REDIRECT_URL. (Comprehensive list of execution codes)

reminder

To circumvent potential redirection failures (after timeout, server unavailability, etc.), we strongly advise you to:

  1. Always use the transaction notification for order management and database updates;
  2. Systematically send an email to the customer confirming the transaction status.

Hash verification

The Dalenys platform responses are systematically signed with a HASH. It must be recalculated on the merchant’s side with all the Dalenys parameters (except for the HASH itself) from the response, the same way it is done when calling the platform. Its validity insures the platform response is authentic.

Here is a pseudo-code example of a redirect hash validation:

if (dalenys_signature(DALENYS_PASSWORD, $_GET) == $_GET["HASH"]) {
    // Todo : Next operations ( Database records, email to the cardholder...)
    // ...And then, display a confirmation message (depending on the `EXECCODE`)
} else {
    // Suspicious redirection, the request integrity may have been compromised !
}

Notification (NPS) specifics

Each transaction (payment, refund, void, etc.) and each transaction update (chargebacks, SEPA Direct Debit transaction finalization, etc.) triggers an HTTP_request of the Dalenys platform.

This HTTP_REQUEST is composed of GET and POST parameters sent to the NOTIFICATION_URL or CHARGEBACK_URL of your choice:

scope

On this NOTIFICATION_URL (or CHARGEBACK_URL), Dalenys platform expects this exact and specific source code: OK.

It must be written in uppercase.

Any other wording would lead to the platform to consider the reception of the notification as failed.

In case of failure (not receiving OK, http code different from 200) a new attempt will be made by the platform.

Following POST parameters list should be found in the transaction notification:

You will retrieve the following `POST` parameters on your `NOTIFICATION_URL`:

  • 3DSECURE no, yes

    Merchant’s request for 3D Secure authentication.

    Example: true

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • CARDCODE string(12-19)

    Last 4 digits of holder’s card. It is possible to receive the truncated pan (6 first digits, some X, 4 last digits) in a CARDCODE parameter by asking the activation of the option to your payment manager and by using a secure NOTIFICATION_URL (https).

    Example: XXXXXXXXXXXX4444

  • CARDCOUNTRY string(2)

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

    Example: US

  • CARDFULLNAME string(1-255)

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

    Example: JOHN SNOW

  • CARDNETWORK VISA, AMERICAN EXPRESS, MASTERCARD, BANCONTACT, CB, UNKNOWN

    The cardholder’s bank card network.

    Example:

  • CARDTYPE string

    The payment method type.

    Example: VISA

  • CARDUSAGE enterprise, debit, credit, prepaid

    Card product code.

    Example:

  • CARDVALIDITYDATE date(MM-YY)

    Card expiry date.

    Example: 12-17

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • CVVRESPONSECODE M, N, P, S, U, X, Y, Z

    Authentication status:

    M = CVV2/CVC2 Matches
    N = CVV2/CVC2 does not Match
    P = Not processed
    S = The CVV2 should be on the card but the merchant indicates it is not.
    U = CVV2/CVC2 Unavailable – issuer does not support this parameter
    X = No information (only for JCB)
    Y = CVC1 Incorrect
    Z = Information not provided

    Example: M

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • EXTRADATA string(1-255)

    Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).

    Example: referrer=myshop.com;order=premium

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

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

    Configure the hosted form display language.

    Example: en

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE authorization, payment, capture, refund, credit, void

    The action you want to process.

    Example: payment

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • SCHEMETRANSACTIONID string(1-55)

    Scheme transaction ID, retrieved in response to the authorization request.

    Example: 11034331402111290210

  • SELECTEDBRAND cb, visa, vpay, electron, mastercard, maestro

    Preferred brand.

    Example: CB

  • STAN int(6)

    System Trace Audit Number.

    Example: 123456

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

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.’

EXECCODE parameter treatment is necessary to update transaction status database. (Comprehensive list of execution codes)

reminder

6x4 formatted PAN reception: ask your payment manager for activation and use a secure NOTIFICATION_URL (HTTPS).

Synchronous or asynchonous transaction notification

Asynchronous mode is used by default for notifications.

This means that notification requests can be sent to the merchant’s server after the end of the transaction (or sometimes even before).

Under some conditions, it is possible to configure the Dalenys account to receive the notification in synchronous mode.
This means the transaction notification will always be sent to the server before the transaction is completed.
The Dalenys platform is then waiting a notification receipt acknowledgement by the merchant’s server before completing the transaction.

warning

In synchronous mode, notification failures can lead to undesirable delays in direct results or redirections.

warning

All Dalenys accounts created before 2016 May 12th are configured by default with synchronous notifications ; Please ask your Dalenys account manager to activate the asynchronous notifications on your account.

Hash verification

The Dalenys platform responses are systematically signed with a HASH.
As for the redirection, it must be calculated on the merchant’s side with all the Dalenys response parameters (excepted the HASH itself), the same way it is done when calling the platform.
Its validity insures the platform response is authentic.

Here is a pseudo-code example of a redirect hash validation:

if (dalenys_signature(DALENYS_PASSWORD, $_GET) == $_GET["HASH"]) {
    // Todo : Next operations ( Database records, email to the cardholder...)
    // ...And then, display a confirmation message (depending on the `EXECCODE`)
} else {
    // Suspicious redirection, the request integrity may have been compromised !
}

Public Dalenys IP ranges to be authorized

You must grant all Dalenys IP to access at your server if you want to receive notification : see dedicated page .

Chargeback notifications

Upon chargeback reception, Dalenys platform will trigger a dedicated CHARGEBACK notification. CHARGEBACK notification structures are similar to other transaction notifications.

Chargeback notifications parameters:

You will retrieve the following `POST` parameters on your `NOTIFICATION_URL`:

  • 3DSECURE no, yes

    Merchant’s request for 3D Secure authentication.

    Example: true

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

    Authentication status:
    y: authentication successful
    n: not authenticated
    u: unavailable
    a: attempted
    c: cardholder challenge required
    r: rejected
    i: Informational Only
    empty: no 3-D Secure

    Example: y

  • 3DSECURESIGNATURESTATUS y, n

    Signature verification status. Possible values are:
    y: signature is present in PARes message
    n: no signature present in PARes message

    Example: y

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

    Global status.

    Example: ok

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • CARDCODE string(12-19)

    Last 4 digits of holder’s card. It is possible to receive the truncated pan (6 first digits, some X, 4 last digits) in a CARDCODE parameter by asking the activation of the option to your payment manager and by using a secure NOTIFICATION_URL (https).

    Example: XXXXXXXXXXXX4444

  • CARDCOUNTRY string(2)

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

    Example: US

  • CARDFULLNAME string(1-255)

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

    Example: JOHN SNOW

  • CARDTYPE string

    The payment method type.

    Example: VISA

  • CARDVALIDITYDATE date(MM-YY)

    Card expiry date.

    Example: 12-17

  • CHARGEBACKDATE date(YYYY-MM-DD)

    Chargeback date.

    Example: 2017-05-25

  • CHARGEBACKTYPE chargeback, representment

    Chargeback type.

    Example: chargeback

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

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

    Configure the hosted form display language.

    Example: en

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE authorization, payment, capture, refund, credit, void

    The action you want to process.

    Example: payment

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

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.’