SEPA Direct Debit (SDD) integration

Introduction

SEPA direct debits (SDD) is a payment method fully deployed in euro area countries.

It is a “pull” payment method that allows a merchant to directly debit a user’s bank account, as long as a valid mandate has been signed by the user to allow the merchant to withdraw money from his bank account.

It involves redirecting the user to a specific interface to enter his IBAN and finalize its transaction.

info

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

info

When processing the first successful transaction, an e-mandate is automatically generated by the platform and an ALIAS is also returned. This ALIAS should then be used to collect the linked mandate again.

warning

Final status of the transaction may not be known before a few working days.

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

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[CLIENTGENDER]=f" \
--data "params[BILLINGFIRSTNAME]=John" \
--data "params[BILLINGLASTNAME]=Doe" \
--data "params[BILLINGADDRESS]=285 Fulton Street" \
--data "params[BILLINGCITY]=New York" \
--data "params[BILLINGCOUNTRY]=US" \
--data "params[BILLINGMOBILEPHONE]=33666666666" \
--data "params[BILLINGPOSTALCODE]=10007" \
--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[DESCRIPTION]=Knows nothing" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

Parameters

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • 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

  • AMOUNT integer

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

    Example: 1000

  • CLIENTIDENT string(1-255)

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

    Example: john.snow

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • CLIENTGENDER m, f

    The cardholder gender.

    Example: f

  • 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

  • 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

  • BILLINGMOBILEPHONE string(1-32)

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

    Example: 33666666666

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

    Example: 10007

  • 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

  • CLIENTIP ipv4

    The user’s public IP address.

    Example: 10.1.1.1

  • 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

  • HASH string(64)

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

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

  • APIKEYID string (36)

    ID used to authenticate a transaction using APIKEY.

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

  • BILLINGPHONE string(1-32)

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

    Example: 33111111111

  • 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

  • SHIPTOADDRESS string(1-50)

    The shipping address.

    Example: 55 rue de la liberté

  • SHIPTOCITY string(1-255)

    The shipping city.

    Example: New York

  • 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

  • CARDFULLNAME string(1-255)

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

    Example: JOHN SNOW

  • 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

  • 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

  • METADATA string(1-255)

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

    Example: @METADATA-MYWEBSITE

Request result

Here is the request result from the platform:

  • OPERATIONTYPE payment

    The action you want to process.

    Example: payment

  • 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

  • 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

  • TRANSACTIONID string(1-32)

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

    Example: A1123456

  • ALIAS string(1-40)

    Identifier of a previously processed payment method.

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

  • REDIRECTHTML string(no length limit)

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

    Example:

info

0003 is returned as a first execcode when the transaction is validated. The final status of the transaction is communicated via a second notification after a few days.

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.

    Example: YOUR_IDENTIFIER

  • OPERATIONTYPE payment

    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

  • CLIENTIDENT string(1-255)

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

    Example: john.snow

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • ORDERID string(1-40)

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

    Example: 1234

  • AMOUNT integer

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

    Example: 1000

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

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

    Configure the hosted form display language.

    Example: en

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • 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

  • 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

  • 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

  • ALIAS string(1-40)

    Identifier of a previously processed payment method.

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

  • HASH string(64)

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

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

info

0003 is returned as a first execcode when the transaction is validated. The final status of the transaction is communicated via a second notification after a few days.

Refund

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

info

You can only refund a succeeded payment transaction. 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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • OPERATIONTYPE refund

    The action you want to process.

    Example: payment

  • TRANSACTIONID string(1-32)

    The payment’s TRANSACTIONID you want to refund.

    Example: A1123456

  • ORDERID string(1-40)

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

    Example: 1234

  • 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

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

  • HASH string(64)

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

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • 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

  • 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

Request result

Here is the request result from the platform:

  • OPERATIONTYPE refund

    The action you want to process.

    Example: payment

  • 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

  • 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

  • TRANSACTIONID string(1-32)

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

    Example: A1123456

Notification result parameters

Here is the request result from the platform:

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • 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

  • CLIENTIDENT string(1-255)

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

    Example: john.snow

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • ORDERID string(1-40)

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

    Example: 1234

  • AMOUNT integer

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

    Example: 1000

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

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

    Configure the hosted form display language.

    Example: en

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • 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

  • 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

  • HASH string(64)

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

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

Specific details

Recurring transactions

For recurring transactions see the recurring section.