Bancontact integration

logo Bancontact

Introduction

This section concerns bank card payment methods using Bancontact (formerly known as Bancontact Mister Cash).

reminder

A Bancontact card should be composed of:

  • A card number also known as Primary Account Number (PAN) with a length of 17 digits
  • An expiry date
  • The full name of the card holder
  • A magnetic stripe and/or a chip
security

Storing or processing sensitive card data (like card code, cryptogram…) is regulated by PCI-DSS standards. Basically, you are not allowed to store these data unless you are a PCI-DSS certified entity. For more information: PCI-DSS standard reference.

Transactions made by Bancontact cards are systematically secured with Belfius Card Reader authentication process.

danger

This payment method is not compatible with iframe integration, be sure to display your bancontact form outside any iframe.

Compatible operations and options

Hosted-fields integration

In this mode, you have to generate a hosted-fields’ HFTOKENS with our client side library then you have to send a POST request containing your order’s parameters including the HFTOKEN over HTTPS to the Dalenys platform.

To generate a token, please report to the hosted-fields integration section.

Payment

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[AMOUNT]=1000" \
--data "params[CLIENTIDENT]=john.snow" \
--data "params[CLIENTEMAIL]=john.snow@example.com" \
--data "params[CLIENTREFERRER]=https://your_shop.com/order?id=1234" \
--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[HFTOKEN]=17730892-b3f7-4411-bc81-557471ffcede" \
--data "params[CARDFULLNAME]=JOHN SNOW" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

Parameters

  • 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

  • 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

  • AMOUNT integer

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

    Example: 1000

  • 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}

  • BILLINGADDRESS string(1-50)

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

    Example: 285 Fulton Street

  • BILLINGCITY string(1-255)

    The billing city.

    Example: New York

  • BILLINGCOUNTRY string(2)

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

    Example: US

  • BILLINGFIRSTNAME string(1-15)

    The first name part of the billing address.

    Example: John

  • BILLINGLASTNAME string(1-15)

    The last name part of the billing address.

    Example: Doe

  • BILLINGPHONE string(1-32)

    Billing phone number in international (E.164) format.

    Example: 33111111111

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

    Example: 10007

  • CARDFULLNAME string(1-255)

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

    Example: JOHN SNOW

  • CARDFULLNAME string(1-255)

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

    Example: JOHN SNOW

  • CART[X][BRAND] string(1-100)

    Article brand.

    Example: Micropple

  • CART[X][CATEGORY] computersandsoftware, electronics, appliances, homeandgarden, fashion, healthandbeauty, jewellery, sport, leisureandhobbies, carsandmotorbikes, furniture, kidsandbaby, videogamesandconsoles, toysandgames, pets, foodanddrink, giftandflowers, entertainment, travel, auctionsandgroupbuying, servicesforindividuals, servicesforprofessionals

    Article category.

    Example: electronics

  • CART[X][DELIVERYEXPECTEDDATE] date(YYYY-MM-DD)

    Delivery Date.

    Example: 2017-06-20

  • CART[X][DELIVERYEXPECTEDDELAY] int (1-3)

    Number of days for delivery; must be greater than 0.

    Example: 2

  • CART[X][DELIVERYLABEL] string(1-100)

    Delivery method name or description.

    Example: Micropple store

  • CART[X][DELIVERYSPEED] standard,express

    Speed of the delivery method. (Specify EXPRESS if under 48h).

    Example: express

  • CART[X][DELIVERYTYPE] storepickup, networkpickup, travelpickup, carrier, edelivery, other

    Delivery method:

    storepickup: collection of the goods in the merchant store
    networkpickup: collection in a third party point (like ups, alveol, etc.)
    travelpickup: collection in an airport, train station or travel agency
    carrier: carrier such as La Poste, Colissimo, UPS, DHL…or any private carrier
    edelivery: electronic ticket issuance, download, etc.

    Example: storepickup

  • CART[X][DISCOUNT] float

    Applied discount in percentage. The decimal separator is the dot symbol.

    Example: 10.5

  • CART[X][MERCHANTITEMID] string

    Item ID in the merchant system.

    Example: REF-123456

  • CART[X][NAME] string

    Item name.

    Example: Laser printer

  • CART[X][PRICE] int

    Unit price in cents, including potential taxes and discounts.

    Example: 20000

  • CART[X][QUANTITY] integer

    Quantity of this item.

    Example: 3

  • CART[X][SUBMERCHANTEXTERNALID] string

    Submerchant account identifier in the marketplace. This field allow a special value “OPERATOR” when the item is sold by the marketplace itself (and not a sub-merchant).

    Example: shop1.com

  • CART[X][TAX] float

    Applied taxes in percentage. The decimal separator is the dot symbol.

    Example: 19.5

  • CART[X][TOTALAMOUNT] integer

    Total amount based on PRICE and QUANTITY.

    Example: 60000

  • CLIENTADDRESS string(1-510)

    The user’s address.

    Example: 285 Fulton Street.

  • CLIENTDOB date(YYYY-MM-DD)

    The user’s date of birth.

    Example: 1982-06-20

  • 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

  • CLIENTIP ipv4

    The user’s public IP address.

    Example: 10.1.1.1

  • CLIENTREFERRER string(1-255)

    The user’s HTTP referrer URL.

    Example: https://your_shop.com/order?id=1234

  • 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

  • CREATEALIAS boolean

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

    Example: true

  • DESCRIPTION string(1-510)

    A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.

    Example: Knows nothing

  • 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

  • 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

  • HFTOKEN string(1-36)

    A token to use with hosted fields integration. This token replace card holder data in a hosted field payment request.

    Example: 17730892-b3f7-4411-bc81-557471ffcede

  • HIDECARDFULLNAME no, yes

    Hide the fullname input on the hosted form. You must supply the CARDFULLNAME. See the dedicated section for more informations.

    Example: true

  • HIDECLIENTEMAIL no, yes

    Hide the CLIENTEMAIL input on the hosted form. You must supply the CLIENTEMAIL. See the dedicated section for more informations.

    Example: true

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

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

    Configure the hosted form display language.

    Example: en

  • METADATA string(1-255)

    Additional transactional data. Contact your account manager for more informations.

    Example: @METADATA-MYWEBSITE

  • OPERATIONTYPE payment

    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

  • SHIPTOADDRESS string(1-50)

    The shipping address.

    Example: 55 rue de la liberté

  • SHIPTOCOUNTRY string(2)

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

    Example: US

  • SHIPTOFIRSTNAME string(1-15)

    Holder’s first name in the shipping address.

    Example: John

  • SHIPTOLASTNAME string(1-30)

    Holder’s last name in the shipping address.

    Example: Doe

  • SHIPTOPHONE string(1-32)

    Shipping phone number in international (E.164) format.

    Example: 33111111111

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

    Example: 10007

  • TIMEZONE string(1-128)

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

    Example: Europe/Paris

  • TRANSACTIONEXPIRATIONDATE datetime(yyyy-MM-dd HH:mm:ss)

    Form expiration date. By default, the date is UTC, the timezone can be specified by using the TIMEZONE parameter.

    Example:

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Request result

Here is the request result from the platform:

  • ALIAS string(1-40)

    Identifier of a previously processed payment method.

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

  • 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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE payment

    The action you want to process.

    Example: payment

  • REDIRECTHTML string(no length limit)

    HTML content to display to the user to continue the processing. The string is base64 encoded.

    Example:

  • 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

  • REDIRECTURL string(no length limit)

    The url to redirect the user to continue the processing.

    Example: http://some_url?p1=v1

  • TRANSACTIONID string(1-32)

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

    Example: A1123456

Notification result parameters

Please see the dedicated section about notification and redirection

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)

    The last 4 digits of the card code.

    Example: 1111222233334444

  • 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, CARTE BLEUE, 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

  • 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

  • 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, cs

    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 payment

    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.

Form integration

In this mode, you have to redirect the user to the Dalenys platform by sending a POST request containing your order’s parameters.

To do so, you need to build a form using POST method on your merchant site beforehand, following the instructions below.

Payment

Example

Here is a simple example of a payment form. Submitting this form will redirect to the hosted form.

<form method="post" action="https://secure-test.be2bill.com/front/form/process">
    <input type="hidden" name="IDENTIFIER" value="" />
    <input type="hidden" name="OPERATIONTYPE" value="`payment`" />
    <input type="hidden" name="ORDERID" value="" />
    <input type="hidden" name="AMOUNT" value="" />
    <input type="hidden" name="CLIENTIDENT" value="" />
    <input type="hidden" name="DESCRIPTION" value="" />
    <input type="hidden" name="HASH" value="" />
    <input type="hidden" name="VERSION" value="" />
</form>

Parameters

  • AMOUNT integer

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

    Example: 1000

  • APIKEYID string (36)

    ID used to authenticate a transaction using APIKEY.

    Example: a688b3a1-d227-4cdd-9454-5d7cfcc74ef9

  • BILLINGADDRESS string(1-50)

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

    Example: 285 Fulton Street

  • BILLINGCITY string(1-255)

    The billing city.

    Example: New York

  • BILLINGCOUNTRY string(2)

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

    Example: US

  • BILLINGFIRSTNAME string(1-15)

    The first name part of the billing address.

    Example: John

  • BILLINGLASTNAME string(1-15)

    The last name part of the billing address.

    Example: Doe

  • BILLINGPHONE string(1-32)

    Billing phone number in international (E.164) format.

    Example: 33111111111

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

    Example: 10007

  • CARDFULLNAME string(1-255)

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

    Example: JOHN SNOW

  • CART[X][DISCOUNT] float

    Applied discount in percentage. The decimal separator is the dot symbol.

    Example: 10.5

  • CART[X][MERCHANTITEMID] string

    Item ID in the merchant system.

    Example: REF-123456

  • CART[X][NAME] string

    Item name.

    Example: Laser printer

  • CART[X][PRICE] int

    Unit price in cents, including potential taxes and discounts.

    Example: 20000

  • CART[X][QUANTITY] integer

    Quantity of this item.

    Example: 3

  • CART[X][SUBMERCHANTEXTERNALID] string

    Submerchant account identifier in the marketplace. This field allow a special value “OPERATOR” when the item is sold by the marketplace itself (and not a sub-merchant).

    Example: shop1.com

  • CART[X][TAX] float

    Applied taxes in percentage. The decimal separator is the dot symbol.

    Example: 19.5

  • CART[X][TOTALAMOUNT] integer

    Total amount based on PRICE and QUANTITY.

    Example: 60000

  • CLIENTADDRESS string(1-510)

    The user’s address.

    Example: 285 Fulton Street.

  • CLIENTDOB date(YYYY-MM-DD)

    The user’s date of birth.

    Example: 1982-06-20

  • 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

  • DESCRIPTION string(1-510)

    A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.

    Example: Knows nothing

  • 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

  • HIDECARDFULLNAME no, yes

    Hide the fullname input on the hosted form. You must supply the CARDFULLNAME. See the dedicated section for more informations.

    Example: true

  • HIDECLIENTEMAIL no, yes

    Hide the CLIENTEMAIL input on the hosted form. You must supply the CLIENTEMAIL. See the dedicated section for more informations.

    Example: true

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

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

    Configure the hosted form display language.

    Example: en

  • METADATA string(1-255)

    Additional transactional data. Contact your account manager for more informations.

    Example: @METADATA-MYWEBSITE

  • OPERATIONTYPE payment

    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

  • SHIPTOADDRESS string(1-50)

    The shipping address.

    Example: 55 rue de la liberté

  • SHIPTOCOUNTRY string(2)

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

    Example: US

  • SHIPTOFIRSTNAME string(1-15)

    Holder’s first name in the shipping address.

    Example: John

  • SHIPTOLASTNAME string(1-30)

    Holder’s last name in the shipping address.

    Example: Doe

  • SHIPTOPHONE string(1-32)

    Shipping phone number in international (E.164) format.

    Example: 33111111111

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

    Example: 10007

  • TIMEZONE string(1-128)

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

    Example: Europe/Paris

  • TRANSACTIONEXPIRATIONDATE datetime(yyyy-MM-dd HH:mm:ss)

    Form expiration date. By default, the date is UTC, the timezone can be specified by using the TIMEZONE parameter.

    Example:

  • USETEMPLATE web, mobile

    Which custom payment form to use.

    Example: web

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Redirection result parameters

You will retrieve the following GET parameters on your REDIRECT_URL:

  • 3DSECURE no, yes

    3-D Secure’s status.

    Example: true

  • AMOUNT integer

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

    Example: 1000

  • CARDCODE string(12-19)

    The last 4 digits of the card code.

    Example: 1111222233334444

  • 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

  • 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, cs

    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 payment

    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.

Template parameters

When using a customized form, following parameters are expected to be sent by POST to your TEMPLATE_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

  • 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

  • DESCRIPTION string(1-510)

    A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.

    Example: Knows nothing

  • 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

  • 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, cs

    Configure the hosted form display language.

    Example: en

  • METADATA string(1-255)

    Additional transactional data. Contact your account manager for more informations.

    Example: @METADATA-MYWEBSITE

  • OPERATIONTYPE payment

    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

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

Notification result parameters

Exactly the same result parameters than with hosted-fields integration.

Server to server integration

In this mode, you have to send a POST request containing your order’s parameters over HTTPS to the Dalenys platform.

Payment

security

The server to server integration mode requires you to receive sensitive card holder data and has a important impact on the your platform’s security. See PCI-DSS standard reference

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[AMOUNT]=1000" \
--data "params[CLIENTIDENT]=john.snow" \
--data "params[CLIENTEMAIL]=john.snow@example.com" \
--data "params[CLIENTREFERRER]=https://your_shop.com/order?id=1234" \
--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[CARDCODE]=1111222233334444" \
--data "params[CARDVALIDITYDATE]=12-17" \
--data "params[CARDFULLNAME]=JOHN SNOW" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

Parameters

  • AMOUNT integer

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

    Example: 1000

  • 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}

  • APIKEYID string (36)

    ID used to authenticate a transaction using APIKEY.

    Example: a688b3a1-d227-4cdd-9454-5d7cfcc74ef9

  • BILLINGADDRESS string(1-50)

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

    Example: 285 Fulton Street

  • BILLINGCITY string(1-255)

    The billing city.

    Example: New York

  • BILLINGCOUNTRY string(2)

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

    Example: US

  • BILLINGFIRSTNAME string(1-15)

    The first name part of the billing address.

    Example: John

  • BILLINGLASTNAME string(1-15)

    The last name part of the billing address.

    Example: Doe

  • BILLINGPHONE string(1-32)

    Billing phone number in international (E.164) format.

    Example: 33111111111

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

    Example: 10007

  • CARDCODE string(12-19)

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

    Example: 1111222233334444

  • CARDFULLNAME string(1-255)

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

    Example: JOHN SNOW

  • CARDFULLNAME string(1-255)

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

    Example: JOHN SNOW

  • CARDVALIDITYDATE date(MM-YY)

    Card expiry date.

    Example: 12-17

  • CART[X][DISCOUNT] float

    Applied discount in percentage. The decimal separator is the dot symbol.

    Example: 10.5

  • CART[X][MERCHANTITEMID] string

    Item ID in the merchant system.

    Example: REF-123456

  • CART[X][NAME] string

    Item name.

    Example: Laser printer

  • CART[X][PRICE] int

    Unit price in cents, including potential taxes and discounts.

    Example: 20000

  • CART[X][QUANTITY] integer

    Quantity of this item.

    Example: 3

  • CART[X][SUBMERCHANTEXTERNALID] string

    Submerchant account identifier in the marketplace. This field allow a special value “OPERATOR” when the item is sold by the marketplace itself (and not a sub-merchant).

    Example: shop1.com

  • CART[X][TAX] float

    Applied taxes in percentage. The decimal separator is the dot symbol.

    Example: 19.5

  • CART[X][TOTALAMOUNT] integer

    Total amount based on PRICE and QUANTITY.

    Example: 60000

  • CLIENTADDRESS string(1-510)

    The user’s address.

    Example: 285 Fulton Street.

  • CLIENTDOB date(YYYY-MM-DD)

    The user’s date of birth.

    Example: 1982-06-20

  • 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

  • CLIENTIP ipv4

    The user’s public IP address.

    Example: 10.1.1.1

  • CLIENTREFERRER string(1-255)

    The user’s HTTP referrer URL.

    Example: https://your_shop.com/order?id=1234

  • 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

  • DESCRIPTION string(1-510)

    A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.

    Example: Knows nothing

  • 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, cs

    Configure the hosted form display language.

    Example: en

  • METADATA string(1-255)

    Additional transactional data. Contact your account manager for more informations.

    Example: @METADATA-MYWEBSITE

  • OPERATIONTYPE payment,refund

    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

  • SHIPTOADDRESS string(1-50)

    The shipping address.

    Example: 55 rue de la liberté

  • SHIPTOCOUNTRY string(2)

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

    Example: US

  • SHIPTOFIRSTNAME string(1-15)

    Holder’s first name in the shipping address.

    Example: John

  • SHIPTOLASTNAME string(1-30)

    Holder’s last name in the shipping address.

    Example: Doe

  • SHIPTOPHONE string(1-32)

    Shipping phone number in international (E.164) format.

    Example: 33111111111

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

    Example: 10007

  • TIMEZONE string(1-128)

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

    Example: Europe/Paris

  • TRANSACTIONEXPIRATIONDATE datetime(yyyy-MM-dd HH:mm:ss)

    Form expiration date. By default, the date is UTC, the timezone can be specified by using the TIMEZONE parameter.

    Example:

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Request result

Here is the request result from the platform:

  • 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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE payment,refund

    The action you want to process.

    Example: payment

  • REDIRECTHTML string(no length limit)

    HTML content to display to the user to continue the processing. The string is base64 encoded.

    Example:

  • TRANSACTIONID string(1-32)

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

    Example: A1123456

Notification result parameters

Exactly the same parameters result as with hosted-fields integration.

Refund

Refunds can either be processed through server-to-server request or Dalenys Extranet.

info

You can only refund a succeeded payment. A transaction can be refunded several times, up to the original transaction AMOUNT.

Example

Here is a server to server request example:

$> curl --request POST --url "https://secure-test.be2bill.com/front/service/rest/process" \
--data "method=refund" \
--data "params[IDENTIFIER]=YOUR_IDENTIFIER" \
--data "params[OPERATIONTYPE]=refund" \
--data "params[TRANSACTIONID]=A1123456" \
--data "params[ORDERID]=1234" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[VERSION]=3.0" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \

Parameters

  • AMOUNT integer

    The amount to refund. When not specified, refund 100% of the initial transaction resting amount. Could not be higher than the resting amount.

    Example: 1000

  • DESCRIPTION string(1-510)

    A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.

    Example: Knows nothing

  • 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

  • OPERATIONTYPE refund

    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)

    The payment’s TRANSACTIONID you want to refund.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Request result

Here is the request result from the platform:

  • 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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE refund

    The action you want to process.

    Example: payment

  • TRANSACTIONID string(1-32)

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

    Example: A1123456

Notification result parameters

Exactly the same result parameters than with hosted-fields integration.

Specific details

Authentication (Belfius Card Reader)

Transactions made by Bancontact cards are systematically secured with Belfius Card Reader authentication process which operates in the same manner as the 3-D Secure.

No iframe integration

danger

This payment method is not compatible with iframe integration, be sure to display your bancontact form outside any iframe.

Sandbox test card numbers

You can simulate the EXECCODEs from the list bellow, using fake card numbers (PAN), the last 4 digits of which correspond to the desired EXECCODE.

CODE description fake PAN
0000 Successful operation 67033000968180000
4001 Transaction declined by the banking network 67033000695014001
4002 Insufficient funds 67033000844264002
4003 Card declined by the banking network 67033000582394003
4010 Invalid transaction 67033000910664010
4012 Invalid card data 67033000427454012
5001 Exchange protocol failure 67033000379435001
5002 Banking network error 67033000478835002
5004 Time out, the response will be sent to the notification URL 67033000896285004