Redirections and notifications
- Introduction
- Redirection specifics
- Notification (NPS) specifics
- Public Dalenys IP ranges to be authorized
- Chargeback 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:
- Always use the transaction notification for order management and database updates;
- 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:
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
andREDIRECTURLCANCEL
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 secureNOTIFICATION_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 providedExample: 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 asAMOUNT
andORDERID
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:
- Always use the transaction notification for order management and database updates;
- 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:
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 secureNOTIFICATION_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 providedExample: 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 asAMOUNT
andORDERID
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
,empty
Authentication status:
y
: authentication successful
n
: not authenticated
u
: unavailable
a
: attempted
c
: cardholder challenge required
r
: rejected
empty
: no 3-D SecureExample: y
-
3DSECURESIGNATURESTATUS
y
,n
Signature verification status. Possible values are:
y
: signature is present in PARes message
n
: no signature present in PARes messageExample: 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 secureNOTIFICATION_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 asAMOUNT
andORDERID
must be verified.’