Authentication

Credentials

Be2bill technical accounts require credentials to be used.

There are 2 main kinds of credentials depending of the integration mode and your integration concerns.

Standard credentials

These identifiers are dedicated to most online store configurations.

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • ACCOUNT_KEY string (16)

    Account’s key associated with an IDENTIFIER.

security

The Be2bill ACCOUNT_KEY is confidential and should be kept safely.

API KEY credentials

These identifiers are dedicated to specific online store configurations, as mobile application or SDK, and make it possible to carry out a restricted list of operations.

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • APIKEY string (16)

    The API key, private or public value (depending on the API KEY type) associated with an APIKEYID.

  • APIKEYID string (36)

    An ID associated to the APIKEY. This parameter must be included in each transaction request.

info

An APIKEY is shared by all your technical accounts. To use a specific account, just use the corresponding IDENTIFIER with your APIKEY.

There are also 2 kinds of APIKEY credentials:

  • SDK: Dedicated for any SDK framework, please ask your account manager for further information;
  • Notification / redirection: Used to recalculate a notification and redirection HASH (Please refer to the dedicated chapter)

For each of them, the set IDENTIFIER + APIKEY, as well as all the parameters of the request are necessary to the calculation of the hash, as explained below.

HASH Generation

Every Be2bill request must be signed with a HASH parameter. This HASH parameter ensure the request’s origin (authentication) and integrity (no alteration by a third).

The HASH parameter must be composed of the following concatenation :

  • Your ACCOUNT_KEY or when appropriate, the APIKEY ;
  • All request parameters alphabetically ordered (A-Z) formatted FIELD=VALUE and separated by your key (ACCOUNT_KEY or APIKEY);
  • The resulting string must be hashed with a sha256 function.
warning

The Be2bill ACCOUNT_KEY is confidential and should be kept safely.

Examples

Standard credentials

Considering a request with these parameters:

{
    "ORDERID": "000123",
    "DESCRIPTION": "sample HASH",
    "AMOUNT": "1000",
    "IDENTIFIER": "SAMPLE_SHOP",
    "CLIENTIDENT": "client_123",
    "VERSION": "3.0",
    "OPERATIONTYPE": "payment"
}

And your key is “SECRET”, you will have to generate this clear text string

SECRETAMOUNT=1000SECRETCLIENTIDENT=client_123SECRETDESCRIPTION=sample HASHSECRETIDENTIFIER=SAMPLE_SHOPSECRETOPERATIONTYPE=paymentSECRETORDERID=000123SECRETVERSION=3.0SECRET

The sha256 to generate will be:

bc27d2033fc407300d0172b6886be8b00009e910d2a80fbbe420f2a90c0055e7

API KEY credentials

Considering a request with these parameters:

{
    "ORDERID": "000123",
    "DESCRIPTION": "sample HASH",
    "AMOUNT": "1000",
    "IDENTIFIER": "SAMPLE_SHOP",
    "CLIENTIDENT": "client_123",
    "VERSION": "3.0",
    "OPERATIONTYPE": "payment",
    "APIKEYID": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}

And your key is “SECRET”, you will have to generate this clear text string

SECRETAMOUNT=1000SECRETAPIKEYID=a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6SECRETCLIENTIDENT=client_123SECRETDESCRIPTION=sample HASHSECRETIDENTIFIER=SAMPLE_SHOPSECRETOPERATIONTYPE=paymentSECRETORDERID=000123SECRETVERSION=3.0SECRET

The sha256 to generate will be:

c9c21c6341431e4fa387805cac2fe04a3623802da52ac0361783dd9943cbfa87

General purpose

tips

The HASH parameter itself should not be include in the calculation.

info
  • The parameters that are not listed in the Be2bill documentation should not be included in the HASH calculation (e.g. submit button, hidden input, csrf token, etc.).
  • In case of server to server requests you won’t integrate method and params parameters in the HASH clear string.
warning

This HASH generation algorithm is intended to be really sensible to string variations. Pay attention when generating the clear string to respect the word case, the text encoding and any other possible source of variance which could impact the HASH generation.

Use cases

The HASH mechanism is used to protect the requests processed between Be2bill and your website against alteration (integrity) and unauthorized service use (authentication).

This mechanism is used for various operations of the Be2bill API.

You have to supply a well formatted HASH parameter in following cases (not exhaustive listing):

  • While submitting a request (server to server calls)
  • While redirecting a user with some parameters (e.g. hosted form)

The requests from the Be2bill platform to yours are protected with the same HASH mechanism. You definitively want to check the request integrity by comparing the supplied HASH with another one you have to generate from the request parameters.

You have to check the received HASH parameters in the following cases (not exhaustive listing):

  • Payment notification requests (IPN) on NOTIFICATION_URL from the Be2bill platform
  • Template url call on TEMPLATE_URL from the Be2bill platform
  • User redirect to your website through REDIRECT_URL from the Be2bill platform
danger

If you do not properly check the received HASH from a request sent by the Be2bill platform, you may suffer from severe security issues since anybody could create or alter the request and change some parameters.

Nested parameters

In specific cases, some nested parameters are used in a request.

Example
{
    "ORDERID": "000123",
    "AMOUNT": "1000",
    "IDENTIFIER": "SAMPLE_SHOP",
    "CART": [
      {
        "NAME": "product 1",
        "AMOUNT": 500
      },
      {
        "NAME": "product 2",
        "AMOUNT": 500
      }
    ],
    "VERSION": "3.0"
}

To calculate the HASH for a request containing nested parameters, you have to serialize them in the following order (API_SECRET_KEY = ‘SECRET’):

SECRETAMOUNT=1000SECRETCART[0][AMOUNT]=500SECRETCART[0][NAME]=product 1SECRETCART[1][AMOUNT]=500SECRETCART[1][NAME]=product 2SECRETIDENTIFIER=SAMPLE_SHOPSECRETORDERID=000123SECRETVERSION=3.0SECRET

The final resulting HASH after the sha256 processing would be:

18c9007f844333a91202470c38e49227966e0b7597d672357a8985062a33c6bf