Each Be2bill platform’s operation return a couple
MESSAGE to describe the result of the operation.
In case of a valid request, a
TRANSACTIONID is returned.
Make sure to store in your system the
TRANSACTIONIDfor later usage (refund, capture, support requests, matching … ).
Please note that not all of the operations listed below are available on all payment methods and integration modes.
payment operation is the simplest action available on the Be2bill platform.
It simply consists in requesting to debit a user of the amount you specify.
Authorization and capture
These 2 operations are tightly linked, they must be used for a 2 phase processing workflow.
First, you send an
authorization to initiate a transaction, and later a
capture operation to confirm the debit.
capture operation requires a valid
TRANSACTIONID from a previous, succeeded and still not captured transaction.
authorization does not affect the user account until you decide to capture it.
capture amount could be different from the
authorization amount but can not be higher.
capture workflow is well suited for delayed payment scenario.
authorizationcan only be captured once
Some payment methods require you to
authorizationwithin a limited timeframe. The expiration delay of an authorization depends on the payment method and its regulations. The standard timeframe is 7 calendar days.
A capture can be planned ahead by adding the parameter
CAPTUREDATE to your initial
capture, (triggered by the merchant with a server to server request or via the Be2bill Extranet), cancels the configured
CAPTUREDATEparameter must at least refer to the next day.
The schedule is configured on the Paris-Madrid timezone.
refund operation enables you to credit funds back to a end-user following a previous debit.
refund transaction is always linked to a successsful
capture transaction which it requires the original
The amount of a
refund transaction can be different from the original debit transaction but can not be higher.
refund several times a same debit transaction, but the sum of all the
refund operations can’t be higher that the original debit amount.
refund transaction has an impact on the user’s bank account since he will see the funds being credited on his bank statement.
Credit and Credit Fund Transfer
credit transaction is a special transaction type allowing to give money to the user.
This transaction type should be used in some very special cases (custom refund situations …).
credittransaction are not allowed to all customers by default. You have to contact your account manager to validate the usage conditions and to activate this feature.
If your activity is related to gambling, all your
credit operations will be processed as Credit Fund Transfer operation (CFT).
The only technical difference with a standard
credit transaction is that you have to provide a reference
TRANSACTIONID of a succeeded and authenticated transaction (
This operation can be used to cancel the very last operation of any transaction. (Except the
void operation itself, of course)
For example, once captured, an
authorization cannot be voided, only the capture could be.
You can only
void a transaction on the same day it was processed, that is to say before the funds are sent for compensation to the user’s bank.
It is possible to easily split a payment in several installments.
The Be2bill platform will process the first installment immediately and in case of acceptation of the first installment, the platform will process the following installments at the given dates.
All these installments will result in different transactions sharing the same
ORDERID field as the one in the first installment.
To initiate a split payment, you have to replace the
AMOUNT parameter by:
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.
For example, an
AMOUNTS for a 3 installments split:
- 200€ on 2018-02-01
- 100€ on 2018-03-04
- 100€ on 2018-04-04
A n-times transaction must follow these conditions:
- The time-zone you must use for any n-times transaction is UTC.
- The first installment must be on the day of the request and will be executed immediately.
- The interval between the first and last installment must not exceed 90 days.
- The last installment must occur before the card’s expiry date.
paymenttransactions can be split with n-times mode.
- If the first transaction is refused, the other scheduled transactions won’t be processed, the whole request is considered as refused
- Schedule dates should be supplied in UTC format.
AMOUNTScan not be used at the same time.
TRANSACTIONID of a n-times schedule will be the schedule reference:
We can configure automatic retries for each installments. To enable and configure this feature, please contact your payment manager.
N-times schedule can be canceled by using the
This operation is used to abort forthcoming installments of an n-times transaction, by providing its
Please note that the past installments won’t be refunded with this operation, you must use classic
refundoperation to refund each installment.
It is possible to implement tailor-made recurring payment workflows without storing any sensitive card data by simply using our aliasing features.
All you have to do is to add a
CREATEALIAS parameter in your
credit initial request.
In the request’s direct response, as well as redirection and notification, you will retrieve the parameter ALIAS:
Identifier of a previously processed payment method.
This parameter is a non-sensible reference for the used payment method in our platform. You have to store and keep this reference in your database for later use.
For each recurring transaction processed on the same
ALIAS for the same user on the same payment method, you don’t need to provide the usual payment method details (ie:
Identifier of a previously processed payment method.
Indicates the ALIAS usage mode:
oneclickindicates a one click or an online transaction;
subscriptionindicates an offline transaction.
oneclickyou can optionally ask the user for the cryptogram and supply it in the recurring request (parameter
CARDCVV). The cryptogram will be verified by the user’s bank to grant or deny the transaction.
Keep in mind that storing the cryptogram is forbidden.
In a hosted form integration, you can allow the user to choose to register to a recurring workflow or not by providing the parameter:
Display a checkbox on the hosted form to ask the user to save his card data for future usage.\ See the dedicated section.
When this parameter is valued to
true, the hosted form will display a check-box asking for granting Be2bill the permission to store payment method data for easier later re-use.
Authentication (3-D Secure / Secure Code / Safekey)
Almost every card scheme implements an authentication system : 3-D Secure for Visa, Secure Code for Mastercard, Safekey for American Express (…) 3-D Secure is an authentication protocol designed to be an additional security layer for online transactions. The 3-D Secure protocol helps you to mitigate fraud and provide a liability shift to your transactions in case of chargebacks.
Auto trigger rules can be set with the Payment Manager.
The 3-D Secure process concerns
To trigger a 3-D Secure authentication you should add the following parameters to your
Ask for a 3-D Secure authentication.
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.
Server to server integration
In case of server to server integration, you should redirect the user to the authentication page.
Once submitted and accepted by the Be2bill platform, the request will result in an
EXECCODE means that the transaction is waiting for the authentication process.
In case of
EXECCODE 0001, you will receive a new parameter in the response:
This parameter is a
html redirection code encoded with base64, so you have to base64_decode it and display it to the end user.
Because of the redirection, you have to wait for the user to come back to your platform to retrieve the transaction’s final result.
When you choose
3DSECUREDISPLAYMODE=raw you will receive these two parameters instead of
REDIRECTURL string(no length limit)
The url to redirect the user to continue the processing.
REDIRECTPOSTPARAMS string(no length limit)
The POST parameters to send when
3DSECUREDISPLAYMODEis valued to “raw”. The redirection should send the user to the url pointed by
Therefore, you have to redirect the user by yourself by making him submit a
POST request with
POST parameters to
REDIRECTURL as destination.
It’s possible to use your own 3-D Secure MPI, you have to ask the activation of this option to your payment manager and then add the following fields to your 3-D Secure transactions :
3DSECURE_XID hexadecimal (40 max)
3-D Secure X id.
3DSECURE_CAVV hexadecimal (2 max)
3-D Secure “Cardholder Authentication Verification Value”.
3DSECURE_CAVVALGORITHM int (1)
3-D Secure “Cardholder Authentication Verification Value” algorithm(0-9).
3DSECURE_RESULT hexadecimal (6)
3-D Secure result.
3DSECURE_ECI string (9)
Electronic Commerce Indicator.
Card’s enrollment status.
3-D Secure status.
In both server to server and hosted form modes, you will only receive the transaction’s final result once the user is redirected to your platform.
You can then display a confirmation message to the user and process the transaction in your application.
You have to check the received
HASHagainst the one you generate to confirm the request’s origin and integrity before redirecting the user. See this section for more information.
Additional notification parameters
3-D Secure transactions can be configured to receive some additional parameters:
Authentication status (Y = yes ; N = no ; U = unavailable; A = attempted).
Card 3-D Secure enrollment status.
For more information about these parameters or the activation of this feature please contact your payment manager.