Facily Pay integration

logo Facily Pay

Introduction

Facily Pay is an interest-free 3x or 4x payment method, for orders amounting between 150 and 2000€.

It involves redirecting the cardholder to Facily Pay to finalize its transaction.

info

Upon receipt of EXECCODE = 0002 in the synchronous response, you must redirect the cardholder to the Facily Pay form by displaying the content of the REDIRECTHTML parameter. (Base64 encoded)

After validating the payment on Facily Pay, the cardholder is redirected to the REDIRECT_URL.

The result of the transaction will also be transmitted by HTTP notification. (See the specifics of the notification)

When successful, an authorization is created and it would have up to 7 days to be captured.

warning

Only two authorization statuses can be observed: 0000 (success) or 0003 (waiting for approval). Without update of 0003 status within 6 days, authorization should be considered as expired (failed).

Compatible operations and options

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.

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=authorization" \
--data "params[OPERATIONTYPE]=authorization" \
--data "params[PAYMENTOPTION]=facilypay-3x" \
--data "params[IDENTIFIER]=YOUR_IDENTIFIER" \
--data "params[AMOUNT]=1000" \
--data "params[DESCRIPTION]=Knows nothing" \
--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[ORDERID]=1234" \
--data "params[CLIENTIDENT]=john.snow" \
--data "params[CLIENTEMAIL]=john.snow@example.com" \
--data "params[BILLINGTITLE]=mr" \
--data "params[BILLINGFIRSTNAME]=John" \
--data "params[BILLINGLASTNAME]=Doe" \
--data "params[BILLINGADDRESS]=285 Fulton Street" \
--data "params[BILLINGPOSTALCODE]=10007" \
--data "params[BILLINGCITY]=New York" \
--data "params[BILLINGCOUNTRY]=US" \
--data "params[BILLINGPHONE]=33111111111" \
--data "params[BILLINGMOBILEPHONE]=33666666666" \
--data "params[SHIPTOCOMPANYNAME]=MyShop.com" \
--data "params[SHIPTOTITLE]=mr" \
--data "params[SHIPTOFIRSTNAME]=Doe" \
--data "params[SHIPTOLASTNAME]=" \
--data "params[SHIPTOADDRESS]=55 rue de la liberté" \
--data "params[SHIPTOPOSTALCODE]=75001" \
--data "params[SHIPTOCITY]=New York" \
--data "params[SHIPTOCOUNTRY]=FR" \
--data "params[SHIPTOPHONE]=33111111111" \
--data "params[SHIPTOMOBILEPHONE]=33666666666" \
--data "params[CART[0][MERCHANTITEMID]]=REF-123456" \
--data "params[CART[0][NAME]]=Laser printer" \
--data "params[CART[0][PRICE]]=20000" \
--data "params[CART[0][QUANTITY]]=3" \
--data "params[CART[0][CATEGORY]]=electronics" \
--data "params[CART[0][BRAND]]=Micropple" \
--data "params[CART[0][DELIVERYTYPE]]=storepickup" \
--data "params[CART[0][DELIVERYLABEL]]=Micropple store" \
--data "params[CART[0][DELIVERYSPEED]]=express" \
--data "params[CART[0][DELIVERYEXPECTEDDATE]]=2017-06-20" \
--data "params[CART[0][DELIVERYEXPECTEDDELAY]]=2" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

Parameters

  • OPERATIONTYPE authorization

    The action you want to process.

  • PAYMENTOPTION facilypay-3x, facilypay-3xsansfrais, facilypay-4x, facilypay-4xsansfrais

    Facily Pay and ANCV payment options.

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • AMOUNT integer

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

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

  • CLIENTUSERAGENT string(1-255)

    The HTTP user agent.

  • CLIENTIP ipv4

    The user’s public IP address.

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

  • BILLINGTITLE mr, miss, mrs

    The title used for the billing address name.

  • BILLINGFIRSTNAME string(1-15)

    The first name part of the billing address.

  • BILLINGLASTNAME string(1-15)

    The last name part of the billing address.

  • BILLINGADDRESS string(1-50)

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

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

  • BILLINGCITY string(1-255)

    The billing city.

  • BILLINGCOUNTRY string(2)

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

  • BILLINGPHONE string(1-32)

    Billing phone number in international format.

  • BILLINGMOBILEPHONE string(1-32)

    Billing mobile phone number in international format.

  • SHIPTOCOMPANYNAME string(1-50)

    Name of the receiving company.

  • SHIPTOTITLE mr, miss, mrs

    Holder’s title in the shipping address.

  • SHIPTOFIRSTNAME string(1-15)

    The first name part of the shipping address.

  • SHIPTOLASTNAME string(1-30)

    The last name part of the shipping address.

  • SHIPTOADDRESS string(1-50)

    The shipping address.

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

  • SHIPTOCITY string(1-255)

    The shipping city.

  • SHIPTOCOUNTRY string(2)

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

  • SHIPTOPHONE string(1-32)

    Shipping phone number in international format.

  • SHIPTOMOBILEPHONE string(1-32)

    Shipping mobile phone number in international format.

  • 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][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][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][DELIVERYEXPECTEDDATE] date(YYYY-MM-DD)

    Delivery Date.

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

    Number of days for delivery.

  • HASH string(64)

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

  • VERSION 3.0

    The API protocol version.

  • APIKEYID string (36)

    ID used to authenticate a transaction using APIKEY.

  • CART[X][DISCOUNT] float

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

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

  • EXTRADATA string(1-255)

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

  • METADATA string(1-255)

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

Request result

Here is the request result from the platform:

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

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

  • 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

Here is the request result from the platform:

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE authorization

    The action you want to process.

  • TRANSACTIONID string(1-32)

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

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

  • AMOUNT integer

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

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

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

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

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 server to server 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

Here is the request result from the platform:

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE capture

    The action you want to process.

  • TRANSACTIONID string(1-32)

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

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

  • AMOUNT integer

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

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

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

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

Refund

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

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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE refund

    The action you want to process.

  • TRANSACTIONID string(1-32)

    The 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

Here is the request result from the platform:

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE refund

    The action you want to process.

  • TRANSACTIONID string(1-32)

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

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

  • AMOUNT integer

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

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

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

  • EXTERNALENTITYID int (1-10)

    Multibanco merchant account’s reference

  • EXTERNALREFERENCE int (9)

    Multibanco transaction’s reference (string left padded with 0 of 9 digits)

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

Sandbox test card numbers

You can use the following test card numbers (PANs) to trigger specific execution codes depending on your country in the sandbox environment:

CODE card number
0000 FR 5136780096925196

ES 5127290000000012