SEPA

SEPA Direct Debit

SEPA Direct Debit is based on the following concept: both debtor and creditor must hold an account with a financial service provider located within the SEPA area. The transfer of money between the debtor’s bank and the creditor’s bank always takes place in Euro.

Cashless transactions will be made and received in and between the SEPA member countries regardless of their location. Existing sorting codes and account numbers will be replaced by an International Bank Account Number (IBAN) and a Bank Identifier Code (BIC).

b4payment as an Acquirer

If b4payment is the chosen acquirer, the parameter CONSUMER_MERCHANT_CRM_ID must be added.

Hobex as an Acquirer

Hobex draws the direct debits from the debtor’s bank to one joint account, so no individual creditor IDs are available and any value within the request parameter CREDITOR_ID will be ignored.

Hobex is only available for customers in Germany, Austria or the Netherlands.

Commands

Pre Transaction Commands

The first step is to generate a unique order number with the command CREATEORDER.

Transaction Commands

INITIATEPAYMENT

Request Parameters
Table 1. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

INITTYPE

ORDERREFERENCE

PAYMENTTYPE

CUSTOMERSTATEMENT

AMOUNT

BANK_BIC

CURRENCY

MANDATE_ID

ORDERNUMBER

MANDATE_SIGNATURE_DATE

ORDERDESCRIPTION

DUE_DATE

BANK_ACCOUNT_OWNER

CREDITOR_ID

BANK_ACCOUNT_IBAN

APPLICATIONTYPE


1. The parameter CONSUMER_MERCHANT_CRM_ID is required when initiating a SEPA payment if used b4 as an acquirer, otherwise, this parameter is not required.

TRANSACTION_IDENTIFIER

ORIGINATOR

Table 2. Request Parameters
Required Parameters

MERCHANTKEY

COMMAND

INITTYPE

PAYMENTTYPE

AMOUNT

CURRENCY

ORDERNUMBER

ORDERDESCRIPTION

BANK_ACCOUNT_OWNER

BANK_ACCOUNT_IBAN


2. The parameter CONSUMER_MERCHANT_CRM_ID is required when initiating a SEPA payment if used b4 as an acquirer, otherwise, this parameter is not required.

Optional Parameters

LOGPATH

LANGUAGE

ORDERREFERENCE

CUSTOMERSTATEMENT

BANK_BIC

MANDATE_ID

MANDATE_SIGNATURE_DATE

DUE_DATE

CREDITOR_ID

APPLICATIONTYPE

TRANSACTION_IDENTIFIER

ORIGINATOR

Optional request parameters CUSTOMERSTATEMENT and ORDERREFERENCE, are more restricted about their length and allowed characters than usual.
Response Parameters
Table 3. Response Parameters
Required Parameters Optional Parameters

status

header

version

body

errorCode

message

paySysMessage

originator

Initialization example
Sepa payment method can be initialized if the merchant sends ELV for parameter INITTYPE.
Depending on which acquirer is chosen, the merchant sends the value WCP for b4payment or HOBEX for Hobex, with the parameter PAYMENTTYPE.
  1. Send a request.

    Example of Request for Initiation
    COMMAND=INITIATEPAYMENT&
    MERCHANTKEY=43gADp5.UOZxPTet6O8o8K6o-7RefQB3BO21OMu4chB65LJUI_&
    INITTYPE=ELV&
    PAYMENTTYPE=WCP&
    ORDERNUMBER=819913&
    LANGUAGE=en&
    AMOUNT=1&
    CURRENCY=EUR&
    APPLICATIONTYPE=S&
    SERVICEURL=http://yourimprint.com/&
    CUSTOMERSTATEMENT=eh3462t3hg346&
    SUCCESSURL=https://yoursuccessurl.com&
    ORDERDESCRIPTION=Test:0000&
    FAILUREURL=https://yourfailureurl.com&
    CONSUMER_MERCHANT_CRM_ID=13423072&
    BANK_ACCOUNT_OWNER=owner&
    BANK_ACCOUNT_IBAN=DE09100100101234567893&
  2. The response looks like this:

    Example of Respons for Initiation
    version=qtillserver+3.23.0.48&
    status=0

VERIFYPAYMENT

Request Parameters
Table 4. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

APPLICATIONTYPE

PAYMENTNUMBER

QTILL_CLIENT_IP_ADDRESS

ORIGINATOR

Response Parameters
Table 5. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator

Order as a basis type of properties in the response can be returned for this command.
The additional parameters will be returned.
Table 6. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator

Order as a basis type of properties in the response can be returned for this command.
The additional parameters will be returned.
Verifying payment example
  1. Send a request.

    Request Parameters
    MERCHANTKEY=43gADp5.UOZxPTet6O8o8K6o-7RefQB3BO21OMu4chB65LJUI_&
    COMMAND=VERIFYPAYMENT&
    APPLICATIONTYPE=S&
    ORDERNUMBER=819913&
    LANGUAGE=en&
  2. The response looks like this:

    Response Parameters
    order.1.amount=1.00&
    payment.1.1.paymentNumber=819913&
    payment.1.1.timeModified=08.11.2022+11%3A12%3A26&
    payment.1.1.operationsAllowed=DEPOSITREVERSAL&
    payment.1.1.paymentType=WCP&
    order.1.merchantNumber=840&
    order.1.depositAmount=1.00&
    payment.1.1.providerReferenceNumber=6164f57311394186ab50958ad439abc2&
    payment.1.1.orderNumber=819913&
    order.1.approveAmount=0&
    order.1.credits=0&
    payment.1.1.merchantNumber=840&
    order.1.payments=1&
    version=qtillserver+3.23.0.48&
    order.1.refundAmount=0&
    payment.1.1.currency=EUR&
    order.1.state=ORDERED&
    orders=1&
    payment.1.1.batchNumber=300000630&
    order.1.acquirer=QENTA+TEST&
    order.1.brand=ELV&
    status=0&
    payment.1.1.depositAmount=1.00&
    order.1.orderText=Test%3A0000&
    order.1.contractNumber=Qenta_Test1&
    payment.1.1.state=payment_deposited&
    order.1.customerStatement=eh3462t3hg346&
    order.1.providerContractNumber=Qenta_Test1&
    order.1.timeModified=08.11.2022+11%3A12%3A26&
    order.1.orderNumber=819913&
    payment.1.1.gatewayReferenceNumber=579f6fb9dddb497f902cac049702d518&
    payment.1.1.approveAmount=1.00&
    payment.1.1.mandateID=T000000840-100081991320221108111225&
    order.1.currency=EUR&
    order.1.timeCreated=08.11.2022+11%3A12%3A25&
    payment.1.1.mandateSignatureDate=08.11.2022&
    payment.1.1.timeCreated=08.11.2022+11%3A12%3A26&
    order.1.paymentType=WCP

Post Transaction Commands

GETORDERDETAILS

Request Parameters
Table 7. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

APPLICATIONTYPE

ADMIN_PASSWORD

ORIGINATOR

Response Parameters
Table 8. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator

Order as a basis type of properties in the response can be returned for this command.
The additional parameters will be returned.
Table 9. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator

Order as a basis type of properties in the response can be returned for this command.
The additional parameters will be returned.
Getting order details example
  1. Send a request.

    Request Parameters
    MERCHANTKEY=43gADp5.UOZxPTet6O8o8K6o-7RefQB3BO21OMu4chB65LJUI_&
    COMMAND=GETORDERDETAILS&
    ORDERNUMBER=819913&
    ADMIN_PASSWORD=9p3a0m5f&
    APPLICATIONTYPE=S&
  2. The response looks like this:

    Response Parameters
    order.1.amount=1.00&
    payment.1.1.paymentNumber=819913&
    payment.1.1.timeModified=08.11.2022+11%3A12%3A26&
    payment.1.1.operationsAllowed=DEPOSITREVERSAL&
    payment.1.1.paymentType=WCP&
    order.1.merchantNumber=840&
    order.1.depositAmount=1.00&
    payment.1.1.providerReferenceNumber=6164f57311394186ab50958ad439abc2&
    payment.1.1.orderNumber=819913&
    order.1.approveAmount=0&
    order.1.credits=0&
    payment.1.1.merchantNumber=840&
    order.1.payments=1&
    version=qtillserver+3.23.0.48&
    order.1.state=ORDERED&
    payment.1.1.currency=EUR&
    order.1.refundAmount=0&
    orders=1&
    order.1.brand=ELV&
    order.1.acquirer=QENTA+TEST&
    payment.1.1.batchNumber=300000630&
    status=0&
    payment.1.1.depositAmount=1.00&
    order.1.orderText=Test%3A0000&
    order.1.contractNumber=Qenta_Test1&
    payment.1.1.state=payment_deposited&
    order.1.customerStatement=eh3462t3hg346&
    order.1.providerContractNumber=Qenta_Test1&
    order.1.orderNumber=819913&
    order.1.timeModified=08.11.2022+11%3A12%3A26&
    payment.1.1.gatewayReferenceNumber=579f6fb9dddb497f902cac049702d518&
    objectsTotal=1&
    payment.1.1.approveAmount=1.00&
    payment.1.1.mandateID=T000000840-100081991320221108111225&
    order.1.currency=EUR&
    order.1.timeCreated=08.11.2022+11%3A12%3A25&
    payment.1.1.mandateSignatureDate=08.11.2022&
    order.1.orderDescription=Test%3A0000&
    payment.1.1.timeCreated=08.11.2022+11%3A12%3A26&
    order.1.paymentType=WCP

DEPOSIT

The transaction is automatically deposited by using the command INITIATEPAYMENT, in this case, the command DEPOSIT isn’t used. Look at the order flow diagram of the payment method for closer information.

SEPA transactions are by default set to be approved and deposited in one step, but it can be split it up into a two-step process. That allows distinguishing between approved and deposited payments and performing certain actions for each of them.

To separate the transaction flow into authorization and capture, get in contact with the integration specialists. Look at the order flow diagram of the payment method for closer information.

DEPOSITREVERSAL

Command DEPOSITREVERSAL is used only with Hobex as an acquirer.

RECURPAYMENT

Request Parameters
Table 10. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

APPLICATIONTYPE

SOURCEORDERNUMBER

CUSTOMERSTATEMENT

CURRENCY

ORIGINATOR

AMOUNT

ORDERDESCRIPTION

ADMIN_PASSWORD


3. The parameter CONSUMER_MERCHANT_CRM_ID is required when initiating a SEPA payment if used b4 as an acquirer, otherwise, this parameter is not required.
Response Parameters
Table 11. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator

Recurring payment example
  1. Send a request.

    Request Parameters
    MERCHANTKEY=43gADp5.UOZxPTet6O8o8K6o-7RefQB3BO21OMu4chB65LJUI_&
    COMMAND=RECURPAYMENT&
    ORDERNUMBER=747293&
    SOURCEORDERNUMBER=819913&
    CONSUMER_MERCHANT_CRM_ID=13423072&
    CURRENCY=EUR&
    AMOUNT=1.00&
    ADMIN_PASSWORD=9p3a0m5f&
    APPLICATIONTYPE=S&
    LANGUAGE=en&
  2. The response looks like this:

    Response Parameters
    version=qtillserver+3.23.0.48&
    status=0

Query Commands

For every payment method commands QUERYORDERS, QUERYCREDITS, and QUERYBATCHES are used.

Order Flow Diagram

Two Step Transaction

Contact our integration specialists to enable this workflow.
Image

To interpret this diagram, the successful completion of a NEW PAYMENT is assumed. Starting from this operation it’s possible to carry out different commands.

All possible commands for specific acquirers are found here.