Bank card integration

CB_LOGO VISA_LOGO MASTERCARD_LOGO

Introduction

This section concerns bank card payment methods like

  • VISA
  • Mastercard
  • Carte Bancaire (french scheme)
reminder

A bank card is generally composed of:

  • A card number also known as Primary Account Number (PAN) with a length between 12 to 19 digits
  • An expiry date
  • A cryptogram
  • 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.

Online bank card transactions can be secured with the 3-D Secure authentication process.

warning

The 3-D Secure process can be triggered manually or automatically. So it is important to read the 3-D Secure section and to stay ready to process a 3-D Secure transaction.

Be2bill provides two types of accounts for VISA/MasterCard transactions:

  • A Carte Bancaire account which is the best account to process French transactions. This account being also connected to VISA/MasterCard, the processing of EURO transactions worldwide is possible.
  • A direct VISA/MasterCard account : you can find specifics about this account type in the VISA/Mastercard direct connection section.

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 Be2bill platform.

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

Payment / authorization

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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE payment,authorization

    The action you want to process.

  • ORDERID string(1-40)

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

  • AMOUNT integer

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

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

  • CLIENTREFERRER string(1-255)

    The user’s HTTP referrer URL.

  • CLIENTUSERAGENT string(1-255)

    The HTTP user agent.

  • CLIENTIP ipv4

    The user’s public IP address.

  • HFTOKEN string(1-36)

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

  • CARDFULLNAME string(1-255)

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

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

  • HASH string(64)

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

  • VERSION 3.0

    The API protocol version.

  • 3DSECURE no, yes

    Ask for a 3-D Secure authentication.

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

  • ALIAS string(1-40)

    Identifier of a previously processed payment method.

  • ALIASMODE oneclick, subscription

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

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

  • BILLINGADDRESS string(1-50)

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

  • BILLINGCOUNTRY string(2)

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

  • BILLINGFIRSTNAME string(1-15)

    The first name part of the billing address.

  • BILLINGLASTNAME string(1-15)

    The last name part of the billing address.

  • BILLINGPHONE string(1-32)

    Billing phone number in international format.

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

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

    Article brand.

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

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

    Delivery Date.

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

    Number of days for delivery.

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

    Delivery method name or description.

  • CART[X][DELIVERYSPEED] standard,express

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

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

    Delivery method.

  • CART[X][DISCOUNT] float

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

  • CART[X][MERCHANTITEMID] string

    Item ID in the merchant system.

  • CART[X][NAME] string

    Item name.

  • CART[X][PRICE] int

    Unit price in cents, including potential taxes and discounts.

  • CART[X][QUANTITY] integer

    Quantity of this item.

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

  • CART[X][TAX] float

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

  • CART[X][TOTALAMOUNT] integer

    Total amount based on PRICE and QUANTITY.

  • SHIPTOADDRESS string(1-50)

    The shipping address.

  • SHIPTOCOUNTRY string(2)

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

  • SHIPTOFIRSTNAME string(1-15)

    The first name part of the shipping address.

  • SHIPTOLASTNAME string(1-30)

    The last name part of the shipping address.

  • SHIPTOPHONE string(1-32)

    Shipping phone number in international format.

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

  • TIMEZONE string(1-128)

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

  • CLIENTEMAIL email(5-255)

    The user’s email.

  • CARDFULLNAME string(1-255)

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

  • CLIENTADDRESS string(1-510)

    The user’s address.

  • CLIENTDOB date(YYYY-MM-DD)

    The user’s date of birth.

  • CREATEALIAS boolean

    Ask for a payment method ALIAS creation.

  • DISPLAYCREATEALIAS boolean

    Display a checkbox on the hosted form to ask the user to save his card data for future usage.\ See the dedicated section.

  • EXTRADATA string(1-255)

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

  • HIDECARDFULLNAME no, yes

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

  • HIDECLIENTEMAIL no, yes

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

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

    Configure the hosted form display language.

  • METADATA string(1-255)

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

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

Request result

Here is the request result from the platform:

  • OPERATIONTYPE payment

    The action you want to process.

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • DESCRIPTOR string

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

  • TRANSACTIONID string(1-32)

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

  • ALIAS string(1-40)

    Identifier of a previously processed payment method.

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

  • REDIRECTHTML string(no length limit)

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

Notification result parameters

Please see the dedicated section about notification and redirection

You will retrieve the following POST parameters on your NOTIFICATION_URL:

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE payment, authorization

    The action you want to process.

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • TRANSACTIONID string(1-32)

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

  • AMOUNT integer

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

  • ORDERID string(1-40)

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

  • CLIENTEMAIL email(5-255)

    The user’s email.

  • CLIENTIDENT string(1-255)

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

  • VERSION 3.0

    The API protocol version.

  • HASH string(64)

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

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

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

    Configure the hosted form display language.

  • 3DSECURE no, yes

    Ask for a 3-D Secure authentication.

  • CARDCODE string(12-19)

    The last 4 digits of the card code.

  • CARDCOUNTRY string(2)

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

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

  • CHARGEBACKDATE date(YYYY-MM-DD)

    Chargeback date.

  • CHARGEBACKTYPE chargeback, representment

    Chargeback type.

  • DESCRIPTOR string

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

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

  • ALIAS string(1-40)

    Identifier of a previously processed payment method.

  • CARD3DSECUREENROLLED y, n, u

    Card 3-D Secure enrollment status.

  • TAGS string(no max length)

    Tags set by the Be2bill’s rule engine

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.

Form integration

In this mode, you have to redirect the user to the Be2bill 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 / authorization

Example

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

<form method="post" action="https://secure-test.be2bill.com/front/form/process">
    <input type="hidden" name="IDENTIFIER" value="YOUR_IDENTIFIER" />
    <input type="hidden" name="OPERATIONTYPE" value="payment" />
    <input type="hidden" name="ORDERID" value="1234" />
    <!-- 1000 => EUR 10 -->
    <input type="hidden" name="AMOUNT" value="1000" />
    <input type="hidden" name="CLIENTIDENT" value="john.snow" />
    <input type="hidden" name="DESCRIPTION" value="Knows nothing" />
    <!-- Generated hash -->
    <input type="hidden" name="HASH" value="15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" />
    <input type="hidden" name="VERSION" value="3.0" />
</form>

Parameters

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE payment, authorization

    The action you want to process.

  • ORDERID string(1-40)

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

  • AMOUNT integer

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

  • CLIENTIDENT string(1-255)

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

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

  • HASH string(64)

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

  • VERSION 3.0

    The API protocol version.

  • 3DSECURE no, yes

    Ask for a 3-D Secure authentication.

  • 3DSECUREDISPLAYMODE main, popup, top

    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.

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

  • APIKEYID string (36)

    ID used to authenticate a transaction using APIKEY.

  • BILLINGADDRESS string(1-50)

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

  • BILLINGCOUNTRY string(2)

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

  • BILLINGFIRSTNAME string(1-15)

    The first name part of the billing address.

  • BILLINGLASTNAME string(1-15)

    The last name part of the billing address.

  • BILLINGPHONE string(1-32)

    Billing phone number in international format.

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

  • CART[X][DISCOUNT] float

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

  • CART[X][MERCHANTITEMID] string

    Item ID in the merchant system.

  • CART[X][NAME] string

    Item name.

  • CART[X][PRICE] int

    Unit price in cents, including potential taxes and discounts.

  • CART[X][QUANTITY] integer

    Quantity of this item.

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

  • CART[X][TAX] float

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

  • CART[X][TOTALAMOUNT] integer

    Total amount based on PRICE and QUANTITY.

  • CLIENTEMAIL email(5-255)

    The user’s email.

  • CARDFULLNAME string(1-255)

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

  • CLIENTADDRESS string(1-510)

    The user’s address.

  • CLIENTDOB date(YYYY-MM-DD)

    The user’s date of birth.

  • CREATEALIAS boolean

    Ask for a payment method ALIAS creation.

  • DISPLAYCREATEALIAS boolean

    Display a checkbox on the hosted form to ask the user to save his card data for future usage.\ See the dedicated section.

  • EXTRADATA string(1-255)

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

  • HIDECARDFULLNAME no, yes

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

  • HIDECLIENTEMAIL no, yes

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

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

    Configure the hosted form display language.

  • METADATA string(1-255)

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

  • SHIPTOADDRESS string(1-50)

    The shipping address.

  • SHIPTOCOUNTRY string(2)

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

  • SHIPTOFIRSTNAME string(1-15)

    The first name part of the shipping address.

  • SHIPTOLASTNAME string(1-30)

    The last name part of the shipping address.

  • SHIPTOPHONE string(1-32)

    Shipping phone number in international format.

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

  • TIMEZONE string(1-128)

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

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

  • USETEMPLATE web, mobile

    Which custom payment form to use.

Redirection result parameters

You will retrieve the following GET parameters on your REDIRECT_URL:

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE authorization, payment

    The action you want to process.

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • TRANSACTIONID string(1-32)

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

  • AMOUNT integer

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

  • ORDERID string(1-40)

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

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

  • VERSION 3.0

    The API protocol version.

  • HASH string(64)

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

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

    Configure the hosted form display language.

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

  • EXTRADATA string(1-255)

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

  • CARDCODE string(12-19)

    The last 4 digits of the card code.

  • DESCRIPTOR string

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

  • 3DSECURE no, yes

    3-D Secure’s status.

  • CARD3DSECUREENROLLED y, n, u

    Card 3-D Secure enrollment status.

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

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.

Template parameters

When using a customized form, following parameters are expected to be sent by POST to your TEMPLATE_URL:

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE authorization, payment

    The action you want to process.

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

  • ORDERID string(1-40)

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

  • VERSION 3.0

    The API protocol version.

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

    Configure the hosted form display language.

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

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

  • METADATA string(1-255)

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

  • EXTRADATA string(1-255)

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

  • DESCRIPTOR string

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

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

  • HASH string(64)

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

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.

Notification result parameters

Exactly the same parameters result as 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 Be2bill platform.

Payment / authorization / credit

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[CARDCVV]=123" \
--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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

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

    The action you want to process.

  • ORDERID string(1-40)

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

  • AMOUNT integer

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

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

  • CLIENTREFERRER string(1-255)

    The user’s HTTP referrer URL.

  • CLIENTUSERAGENT string(1-255)

    The HTTP user agent.

  • CLIENTIP ipv4

    The user’s public IP address.

  • CARDCODE string(12-19)

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

  • CARDCVV string(3-4)

    The user’s bank card’s cryptogram

  • CARDVALIDITYDATE date(MM-YY)

    Card expiry date.

  • CARDFULLNAME string(1-255)

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

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

  • HASH string(64)

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

  • VERSION 3.0

    The API protocol version.

  • 3DSECURE no, yes

    Ask for a 3-D Secure authentication.

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

  • APIKEYID string (36)

    ID used to authenticate a transaction using APIKEY.

  • ALIAS string(1-40)

    Identifier of a previously processed payment method.

  • ALIASMODE oneclick, subscription

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

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

  • BILLINGADDRESS string(1-50)

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

  • BILLINGCOUNTRY string(2)

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

  • BILLINGFIRSTNAME string(1-15)

    The first name part of the billing address.

  • BILLINGLASTNAME string(1-15)

    The last name part of the billing address.

  • BILLINGPHONE string(1-32)

    Billing phone number in international format.

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

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

    Article brand.

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

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

    Delivery Date.

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

    Number of days for delivery.

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

    Delivery method name or description.

  • CART[X][DELIVERYSPEED] standard,express

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

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

    Delivery method.

  • CART[X][DISCOUNT] float

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

  • CART[X][MERCHANTITEMID] string

    Item ID in the merchant system.

  • CART[X][NAME] string

    Item name.

  • CART[X][PRICE] int

    Unit price in cents, including potential taxes and discounts.

  • CART[X][QUANTITY] integer

    Quantity of this item.

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

  • CART[X][TAX] float

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

  • CART[X][TOTALAMOUNT] integer

    Total amount based on PRICE and QUANTITY.

  • SHIPTOADDRESS string(1-50)

    The shipping address.

  • SHIPTOCOUNTRY string(2)

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

  • SHIPTOFIRSTNAME string(1-15)

    The first name part of the shipping address.

  • SHIPTOLASTNAME string(1-30)

    The last name part of the shipping address.

  • SHIPTOPHONE string(1-32)

    Shipping phone number in international format.

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

  • TIMEZONE string(1-128)

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

  • CLIENTEMAIL email(5-255)

    The user’s email.

  • CARDFULLNAME string(1-255)

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

  • CLIENTADDRESS string(1-510)

    The user’s address.

  • CLIENTDOB date(YYYY-MM-DD)

    The user’s date of birth.

  • CREATEALIAS boolean

    Ask for a payment method ALIAS creation.

  • DISPLAYCREATEALIAS boolean

    Display a checkbox on the hosted form to ask the user to save his card data for future usage.\ See the dedicated section.

  • EXTRADATA string(1-255)

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

  • HIDECARDFULLNAME no, yes

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

  • HIDECLIENTEMAIL no, yes

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

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

    Configure the hosted form display language.

  • METADATA string(1-255)

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

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

Request result

Here is the request result from the platform:

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

    The action you want to process.

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • DESCRIPTOR string

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

  • TRANSACTIONID string(1-32)

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

  • ALIAS string(1-40)

    Identifier of a previously processed payment method.

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

  • REDIRECTHTML string(no length limit)

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

Notification result parameters

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

Capture

Authorizations have to be captured by a server to server request.

info

You can only capture a succeeded authorization transaction and an authorization can only be captured once.

warning

A capture must be triggered within 7 days of an authorization, otherwise capture success is no longer guaranteed.

tips

The capture AMOUNT may be lower but cannot exceed the initial authorization’s AMOUNT.

Example

Here is a capture request example:

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

Parameters

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE capture

    The action you want to process.

  • TRANSACTIONID string(1-32)

    The authorization’s TRANSACTIONID you want to capture.

  • ORDERID string(1-40)

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

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

  • VERSION 3.0

    The API protocol version.

  • HASH string(64)

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

  • AMOUNT integer

    When not specified, 100% of the authorization amount is captured. Could not be higher than the authorization amount.

  • EXTRADATA string(1-255)

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

Request result

Here is the request result from the platform:

  • OPERATIONTYPE capture

    The action you want to process.

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • DESCRIPTOR string

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

  • TRANSACTIONID string(1-32)

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

Notification result parameters

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

Refund

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

info

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

Example

Here is a refund 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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE refund

    The action you want to process.

  • TRANSACTIONID string(1-32)

    The payment or capture’s TRANSACTIONID you want to refund.

  • ORDERID string(1-40)

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

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

  • VERSION 3.0

    The API protocol version.

  • HASH string(64)

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

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

  • EXTRADATA string(1-255)

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

Request result

Here is the request result from the platform:

  • OPERATIONTYPE refund

    The action you want to process.

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • DESCRIPTOR string

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

  • TRANSACTIONID string(1-32)

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

Notification result parameters

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

Stop n-times

Stop n-times have to be processed by a server to server request.

Example

Here is a stop n-times request example:

$> curl --request POST --url "https://secure-test.be2bill.com/front/service/rest/process" \
--data "method=stopntimes" \
--data "params[IDENTIFIER]=YOUR_IDENTIFIER" \
--data "params[OPERATIONTYPE]=stopntimes" \
--data "params[SCHEDULEID]=A123456" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

Parameters

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE stopntimes

    The action you want to process.

  • SCHEDULEID string(2-32)

    Schedule identifier.

  • VERSION 3.0

    The API protocol version.

  • HASH string(64)

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

Request result

Here is the request result from the platform:

  • OPERATIONTYPE stopntimes

    The action you want to process.

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

Notification result parameters

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

Void

Voids have to be processed by a server to server request.

info

Remember that only the last operation of a transaction history can be voided (ie an authorization can’t be voided if it’s already been captured).

tips

Voiding a transaction before sending it to remittance will result in removing the transaction from the remittance. The money won’t be compensated, the end user won’t see the transaction in his bank report.

Example

Here is a void request example:

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

Parameters

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE void

    The action you want to process.

  • TRANSACTIONID string(1-32)

    The operation’s ‘TRANSACTIONID you want to void.

  • ORDERID string(1-40)

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

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

  • VERSION 3.0

    The API protocol version.

  • HASH string(64)

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

  • EXTRADATA string(1-255)

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

Request result

Here is the request result from the platform:

  • OPERATIONTYPE void

    The action you want to process.

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • DESCRIPTOR string

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

  • TRANSACTIONID string(1-32)

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

Notification result parameters

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

Specific details

Authentication (3-D Secure)

For 3-D Secure transactions see the 3-D Secure section.

info

All transactions using Maestro cards are subject to 3-D Secure authentication.

Recurring transactions

For recurring transactions see the recurring section.

N-times transactions

For easy split transactions see the n-time section.

Market place

Please, see the dedicated section

Visa / MasterCard direct connection

Direct VISA/MasterCard accounts are directly linked to the VISA/MasterCard networks.

These accounts can be set-up to accept payments in all major currencies (including EUR/USD/GBP/SEK/HKD/AUD/etc.).

Each account is set up with one specific currency : multinational merchants will need multiple accounts.

warning
  • Multiple capture operations (as used in a Marketplace) are not allowed on these accounts.
  • void operation cannot be done on a credit transaction on these accounts.
  • On these accounts, credit operation must refer to a 3-D Secure successfully authenticated TRANSACTIONID.
  • Recurring payment is not available for Maestro cards.

Address Verification System (AVS)

For international transactions it is possible to process an additional address comparison between the one supplied at payment time and the one registered at the issuing bank.

Once this feature is enabled on your account, to activate the verification feature on a transaction you have to supply these fields in your request:

  • AVSPOSTALCODE string(1-9)

    The address postal code to submit to the Address Verification System.

  • AVSSTREETNAME string(4-50)

    The address street name to submit to the Address Verification System.

  • AVSSTREETNUMBER integer

    The address street number to submit to the Address Verification System.

The result of a transaction will contain two new fields:

info

This feature is only available for international transaction accounts.

info

This feature works with authorization and payment transaction types.

info

This feature only allows to compare address coherency. In case of address mismatch, the transaction won’t be rejected.

To activate this feature, please contact your payment manager.

Address Verification System result codes

Code Message
- AVS service is not available for the particular card
A Partial Match - Address match; Zip/Postal Code does not match
B Partial Match - Address match; Zip/Postal Code not supplied or not checked
C No Match – Address and Zip/Postal Code not verified
D Full Match - Address and Zip/Postal Code match
E AVS service is not available for the particular card
F Full Match - Address and Zip/Postal Code match (UK Only)
G No Match - Address not verified
I Address not verified
M Full Match - Address and Zip/Postal Code match
N No Match - Address and Zip/Postal Code do not match
P Partial Match - Zip/Postal Code matches; Address does not match
R Issuer system unavailable or timeout, Retry
S AVS not supported by issuer
U Address information unavailable
W For US addresses: Partial Match - nine-digit Zip Code matches; Address does not match. For addresses outside the US: Partial Match - Postal Code matches; Address does not match
X For US addresses: Full Match - nine-digit Zip Code and Address match
Y For US addresses: Full Match - five-digit Zip Code and Address match
Z For US addresses: Partial Match – five-digital ZIP Code matches; Address does not match

Credit Fund Transfer (CFT)

For Credit Fund Transfer transactions see the Credit and Credit Fund Transfer section.

Gambling merchants

Some constraints apply to Gambling merchants (MCC7994 / MCC7995) :

  • The CVV is required on every transaction, including onelick payments.
  • subscription, n-Times, refund and void operations are unavailable.

MCC 6012

Merchants whose activity corresponds to “Financial Institution MCC 6012” are subject to special rules :

  • The first transaction must be an authorization with an alias creation using CREATEALIAS=YES; whatever the AMOUNT, this request will be only used to register the card and will not trigger any debit.
  • Each subsequent transaction must use the ALIAS parameter;
  • Each transaction must include the following specific parameters :
  • SUBSCRIBERDOB date(YYYY-MM-DD)

    Subscriber’s date of birth.

  • SUBSCRIBERACCOUNT string(1-34)

    Subscriber’s IBAN.

  • SUBSCRIBERZIPCODE string(1-9)

    Subscriber’s address postal code.

  • SUBSCRIBERNAME string(1-255)

    Subscriber’s name.

warning

Maestro cards are not accepted on MCC 6012 accounts.

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 fake PAN
0000 4234603011240000
0001 4234604595740001
4001 4234607564194001
4002 4234604810334002
4003 4234606735474003
4004 4234609774004004
4005 4234600140624005
4006 4234606214104006
4007 4234609312714007 (not available for Direct VISA/MasterCard accounts)
4010 4234604450614010 (not available for Direct VISA/MasterCard accounts)
4011 4234609939944011
4012 4234604160524012
4013 4234608464714013
5001 4234609090495001
5002 4234604508525002
5003 4234608234385003 (not available for Direct VISA/MasterCard accounts)
5004 4234607483945004