Redirections and notifications

Introduction

Redirections occur when a carldholder (user) leaves current page (payment form page, 3-D Secure authentication page…) for a Be2bill 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.

Redirection specifics

Once the end-user finalized his transaction after being redirected (either on Be2bill or a supplier or a bank URL), he would be taken back to the REDIRECT_URL of your choice. This REDIRECT_URL has to be defined in the account configuration section of your Be2bill Extranet:

This REDIRECT_URL must be defined in the Be2bill Extranet:

scope

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

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

Among which:

You will retrieve the following GET parameters on your REDIRECT_URL:

  • EXECCODE string(4)

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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • HASH string(64)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • ORDERID string(1-40)

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

  • TRANSACTIONID string(1-32)

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

  • 3DSECURE no, yes

    Ask for a 3-D Secure authentication.

  • AMOUNT integer

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

  • CARDCODE string(12-19)

    The user’s bank card’s Primary Account Number (PAN)

  • CARDFULLNAME string(1-255)

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

  • CARDTYPE string

    The payment method type.

  • CARDVALIDITYDATE date(MM-YY)

    Card expiry date.

  • CARDCOUNTRY string(2)

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

  • CLIENTIDENT string(1-255)

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

  • CLIENTEMAIL email(5-255)

    The user’s email.

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

  • DESCRIPTOR string

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

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

    The action you want to process.

  • VERSION 3.0

    The API protocol version.

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

    Configure the hosted form display language.

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.

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 Be2bill platform responses are systematically signed with a HASH. It must be recalculated on the merchant’s side with all the Be2bill 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(be2bill_signature( BE2BILL_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 !
}

Transaction notifications

Each transaction (authorization, payment, refund, void, etc.) and each chargeback triggers an HTTP_request of the Be2bill 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), Be2bill 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:

  • EXECCODE string(4)

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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • HASH string(64)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • ORDERID string(1-40)

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

  • TRANSACTIONID string(1-32)

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

  • 3DSECURE no, yes

    Ask for a 3-D Secure authentication.

  • AMOUNT integer

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

  • CARDCODE string(12-19)

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

  • CARDFULLNAME string(1-255)

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

  • CARDTYPE string

    The payment method type.

  • CARDVALIDITYDATE date(MM-YY)

    Card expiry date.

  • CARDCOUNTRY string(2)

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

  • CLIENTIDENT string(1-255)

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

  • CLIENTEMAIL email(5-255)

    The user’s email.

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

  • DESCRIPTOR string

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

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

    The action you want to process.

  • VERSION 3.0

    The API protocol version.

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

    Configure the hosted form display language.

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.

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 Be2bill 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 Be2bill platform is then waiting a notification receipt acknowledgement by the merchant’s server before completing the transaction.

warning

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

Hash verification

The Be2bill platform responses are systematically signed with a HASH.
As for the redirection, it must be calculated on the merchant’s side with all the Be2bill 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(be2bill_signature( BE2BILL_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 be2bill IP ranges to be authorized

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

Chargeback notifications

Upon chargeback reception, Be2bill 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:

  • EXECCODE string(4)

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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • HASH string(64)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • ORDERID string(1-40)

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

  • TRANSACTIONID string(1-32)

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

  • 3DSECURE no, yes

    Ask for a 3-D Secure authentication.

  • 3DSECUREAUTHENTICATIONSTATUS y, n, u, a

    Authentication status (Y = yes ; N = no ; U = unavailable; A = attempted).

  • 3DSECURESIGNATURESTATUS y, n

    Signature status.

  • 3DSGLOBALSTATUS ok, not_enrolled, unavailable, not_required

    Global status.

  • AMOUNT integer

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

  • CARDCODE string(12-19)

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

  • CARDFULLNAME string(1-255)

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

  • CARDTYPE string

    The payment method type.

  • CARDVALIDITYDATE date(MM-YY)

    Card expiry date.

  • CARDCOUNTRY string(2)

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

  • CHARGEBACKTYPE chargeback, representment

    Chargeback type.

  • CHARGEBACKDATE date(YYYY-MM-DD)

    Chargeback date.

  • CHARGEBACKCODE int

    Chargeback transaction code.

  • CLIENTIDENT string(1-255)

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

  • CLIENTEMAIL email(5-255)

    The user’s email.

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

  • DESCRIPTOR string

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

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

    The action you want to process.

  • VERSION 3.0

    The API protocol version.

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

    Configure the hosted form display language.

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.