SEPA Direct Debit Preapproval Request

General information to be known for SEPA Direct Debit:

  • The customer’s bank needs to be enrolled in the SEPA Direct Debit CORE scheme or this service needs to be activated on the customer’s bank account.
  • Ask customer to make sure they have the necessary funds in their account. Up to 80% of payments failures are caused by insufficient amount.
  • According to SEPA Direct Debit rules, the customers can Reverse/Cancel a Direct Debit (claim the money back) in 8 weeks, no questions asked and up to 13 months, if his bank agrees. If this happens, you will receive a Reversed notification with ReasonCode and Reason (R-Transaction) which you should properly handle on your side.
  • For B2B transactions please add the CompanyName parameter.
  • The currency for SEPA Direct Debit CORE is EUR, however the customers can use their account although this is not an EUR account as long as the bank is enrolled in SEPA Direct Debit CORE scheme. In this case, some exchange fees might be charged by their bank.
  • Merchants/Users can decide the actual ExecutionDate of a mandate – they can send the date on which the amount will actually be debited from the Debtor’s account.

Checkout the below example of a preapproval request for SEPA Direct Debit (84), where MethodOptionID parameter is mandatory to be sent in the initial payment request.

Please note that if you have a Company, you also need to send the Company parameter in the request.

A 201 HTTP response (Created) is returned if the payment was correctly initialized.

Request:

POST https://paytest.smart2pay.com/v1/preapprovals
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Preapproval": {
    "MerchantPreapprovalID": "s2ptest_h11",
    "Description": "SEPA DD preapproval request",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "MethodID": 84,
    "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "youremail@gmail.com",
      "Phone": "+31651111111"
    },
    "BillingAddress": {
      "Street": "Brink",
      "StreetNumber": "27c",
      "ZipCode": "1251",
      "City": "Laren",
      "Country": "NL"
    },
    "MethodOptionID": 1
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Preapproval": {
        "ID": 13199,
        "Created": "20181101142508",
        "MethodID": 84,
        "SiteID": 30201,
        "MerchantPreapprovalID": "s2ptest_h11",
        "RecurringPeriod": 0,
        "PreapprovedMaximumAmount": null,
        "Currency": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "SEPA DD preapproval request",
        "Customer": {
            "ID": 135127,
            "MerchantCustomerID": null,
            "Email": "youremail@gmail.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "SocialSecurityNumber2": null,
            "Phone": "+31651111111",
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 5103,
            "City": "Laren",
            "ZipCode": "1251",
            "State": null,
            "Street": "Brink",
            "StreetNumber": "27c",
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "NL"
        },
        "Status": {
            "ID": 1,
            "Info": "Pending",
            "Reasons": null
        },
        "RedirectURL": "https://europaytest.smart2pay.com/SlimPay/Landing/PreapprovalLanding.aspx?ID=10084&Hash=CD71CA781BD1F59F52F8F0B2D20A807E",
        "MethodOptionID": 1,
        "PreapprovedFrequency": null,
        "MandateReference": null
    }
}

Redirect the customer to the RedirectURL where he will approve the automatic debit. Once the Customer approves the debit, he will receives via email the digital signed mandate.

SEPA Direct Debit Preapproval Notification

Upon successful approval, we will notify you about the new status of the preapproval to the URL you setup in the Merchant Dashboard.

You need to respond with HTTP Status 204 (No Content)!

Preapproval notification for status Open (2):

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Preapproval": {
    "ID": 13199,
    "Created": "20181101142508",
    "MethodID": 84,
    "SiteID": 30201,
    "MerchantPreapprovalID": "s2ptest_h11",
    "RecurringPeriod": 0,
    "PreapprovedMaximumAmount": null,
    "Currency": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "SEPA DD preapproval request",
    "Customer": {
      "ID": 135127,
      "MerchantCustomerID": null,
      "Email": "youremail@gmail.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": null,
      "SocialSecurityNumber2": null,
      "Phone": "+31651111111",
      "Company": null,
      "DateOfBirth": null
    },
    "BillingAddress": {
      "ID": 5103,
      "City": "Laren",
      "ZipCode": "1251",
      "State": null,
      "Street": "Brink",
      "StreetNumber": "27c",
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "NL"
    },
    "Status": {
      "ID": 2,
      "Info": null,
      "Reasons": null
    },
    "RedirectURL": null,
    "MethodOptionID": 0,
    "PreapprovedFrequency": null,
    "MandateReference": "SLMP004606504"
  }
}

Response:

204 No Content

The message contains a Preapproval object with an updated Status, which can have the following meanings:

PREAPPROVAL STATUS
ID Info Description
1 Pending The customer needs to confirm the preapproval
2 Open The customer confirmed and you can use the preapproval to initiate recurring payments
4 ClosedByCustomer The preapproval is closed and can no longer be used to initiate recurring payments

If the mandate is cancelled by the customer or there is an error in the creation process than a notification with the specific reason is sent.

Preapproval notification for status ClosedByCustomer (4):

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Preapproval": {
    "ID": 729222,
    "Created": "20181025083420",
    "MethodID": 84,
    "SiteID": 30025,
    "MerchantPreapprovalID": "preapptestingS4526352",
    "RecurringPeriod": 0,
    "PreapprovedMaximumAmount": null,
    "Currency": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "sample description",
    "Customer": {
      "ID": 341703,
      "MerchantCustomerID": null,
      "Email": "youremail@gmail.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": "",
      "SocialSecurityNumber2": null,
      "Phone": "+40765260000",
      "Company": "Smart2Pay",
      "DateOfBirth": null
    },
    "BillingAddress": {
      "ID": 8438,
      "City": "Iași",
      "ZipCode": "23900000",
      "State": null,
      "Street": "Sf. Lazar",
      "StreetNumber": "1",
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "RO"
    },
    "Status": {
      "ID": 4,
      "Info": null,
      "Reasons": [
        {
          "Code": "246",
          "Info": "Preapproval cancelled by consumer"
        }
      ]
    },
    "RedirectURL": null,
    "MethodOptionID": 0,
    "PreapprovedFrequency": null,
    "MandateReference": null
  }
}

For more information about the reasons of a wrong request response see our section GlobalPay Return Codes.

SEPA Direct Debit Recurring Payment

Direct Debits can be initiated based on the PreapprovalID received in the Preapproval response. If you wish to have the Direct Debit executed at a specific date, you only need to send in the request the ExecutionDate parameter.

  • Recurring payment request for SEPA Direct Debit (84) that is based on the PreapprovalID (also send in the request the Description parameter and Country parameter that should be the same with the ones sent in the Preapproval request):

    Request:

    POST https://paytest.smart2pay.com/v1/payments/recurrent
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
 "Payment": {
   "PreapprovalID":13199,
   "MerchantTransactionID": "s2ptest_h13",
   "Amount": 100,
   "Currency": "EUR",
   "MethodID": 84,
   "Description":"SEPA DD recurrent payment",
   "BillingAddress": {
     "Country": "NL"
    }
  }
}
  • Recurring payment request for SEPA Direct Debit (84) that includes ExecutionDate parameter:

    Execution day for a SEPA Direct Debit – the moment funds are transferred from debtor’s bank to the merchant’s SEPA DD account.This can be setup by the Merchant/customer by sending ExecutionDate in the Direct Debit payment request or it can be set by default by the SEPA DD provider (which is usually set at 1-2 days from the Direct Debit payment request date).

    Request:

    POST https://paytest.smart2pay.com/v1/payments/recurrent
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
 "Payment": {
   "PreapprovalID":13165,
   "MerchantTransactionID": "s2ptest_h19",
   "Amount": 100,
   "Currency": "EUR",
   "MethodID": 84,
   "Description":"SEPA recurrent payment with executiondate",
   "BillingAddress": {
     "Country": "NL"
    },
   "ExecutionDate": "20200805"
  }  
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 4167022,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20181101145456",
        "MerchantTransactionID": "s2ptest_h13",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": null,
        "ReturnURL": null,
        "Description": "SEPA DD recurrent payment",
        "MethodID": 84,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": {
            "ID": 309,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "NL"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": 13199,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
    }
}

SEPA Direct Debit Recurring Payment Notification

You need to respond with HTTP code 204 (No Content)!

Payment notification for status Success (2):

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "ID": 4167022,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20181101145458",
    "MerchantTransactionID": "s2ptest_h13",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "EUR",
    "ReturnURL": "",
    "Description": null,
    "MethodID": 84,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30201,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": 13199,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": null
    },
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
  }
}

Response:

204 No Content

The message contains a Payment object with an updated Status, which can have the following meanings:

RECURRING PAYMENT STATUS
ID Info Description
2 Success The transaction is successfully settled by the bank.
4 Failed The transaction has failed.
16 Reversed The customer did not recognize the payment and requested the funds back from his bank.

  • In case of a Failed or Reversed status, you will be given in the notification message the reasons why the payment got to that status. Additional information will be sent in the Reasons Code and Reasons Info fields. For a complete list of possible return codes please see our section GlobalPay Return Codes.

SEPA Direct Debit Return Codes
Return Code Description
221 R-Transaction : AC01 – Account Identifier incorrect (i.e. invalid IBAN of the Debtor).
222 R-Transaction : AC04 – Account closed.
223 R-Transaction : AC06 – Account blocked.
224 R-Transaction : AC13 – Debtor account is a consumer account.
225 R-Transaction : AC13 – Debtor account is a consumer account.
226 R-Transaction : AG02 – Operation code/transaction code/sequence type incorrect, invalid file format.
227 R-Transaction : AM04 – Insufficient funds.
228 R-Transaction : AM05 – Duplicate collection.
229 R-Transaction : BE05 – Identifier of the Creditor Incorrect.
230 R-Transaction : CNOR – Creditor Bank is not registered under this BIC in the CSM.
231 R-Transaction : DNOR – Debtor Bank is not registered under this BIC in the CSM.
232 R-Transaction : FF01 – File Format incomplete or invalid.
233 R-Transaction : MD01 – No mandate.
234 R-Transaction : MD02 – Mandate data missing or incorrect.
235 R-Transaction : MD06 – Disputed authorized transaction.
236 R-Transaction : MD07 – Debtor Deceased.
237 R-Transaction : MS02 – Refusal by the Debtor.
238 R-Transaction : MS03 – Reason not specified.
239 R-Transaction : RC01 – Bank Identifier (BIC) Incorrect.
240 R-Transaction : RR01 – Regulatory Reason.
241 R-Transaction : RR02 – Regulatory Reason.
242 R-Transaction : RR03 – Regulatory Reason.
243 R-Transaction : RR04 – Regulatory Reason.
244 R-Transaction : SL01 – Specific Service offered by the Debtor Bank.

Payment notification for status Failed with reason code and description.

Payment notification for status Failed (4):

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "ID": 4157363,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20181029134811",
    "MerchantTransactionID": "testCORE00001",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "EUR",
    "CapturedAmount": null,
    "ReturnURL": "",
    "Description": "test Smart2Pay",
    "MethodID": 84,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30151,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": {
      "ID": 1720,
      "City": null,
      "ZipCode": null,
      "State": null,
      "Street": null,
      "StreetNumber": null,
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "NL"
    },
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": 13165,
    "Status": {
      "ID": 4,	
      "Info": "Failed",
      "Reasons": [
        {	
          "Code": "227",
          "Info": "R-Transaction : AM04 - Insufficient funds"
        }	
      ]	
    },	
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
  }
}

Response:

204 No Content

Payment notification for status Reversed with reason code and description.

Payment notification for status Reversed (16):

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "ID": 4157363,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20181029134811",
    "MerchantTransactionID": "testCORE00001",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "EUR",
    "CapturedAmount": null,
    "ReturnURL": "",
    "Description": "test Smart2Pay",
    "MethodID": 84,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30151,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": {
      "ID": 1720,
      "City": null,
      "ZipCode": null,
      "State": null,
      "Street": null,
      "StreetNumber": null,
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "NL"
    },
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": 13165,
    "Status": {
      "ID": 16,	
      "Info": "Reversed",
      "Reasons": [
        {	
          "Code": "235",
          "Info": "R-Transaction : MD06 - Disputed authorized transaction."
        }	
      ]	
    },	
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
  }
}

Response:

204 No Content

SEPA Direct Debit Timeline

Checkout the below SEPA Direct Debit Timeline explained:

  • D-14: Pre-notification for recurrent Direct Debits;
  • D-2: The merchant initiates a SEPA DD – the payment has status Open. If the Direct debit request fails for technical reasons (e.g connection time out), the payment status moves to Failed with ReasonCode and Reason. This is not an incident (R-transaction), it is only a technical failure of the request;
  • D-1: The provider submits the SEPA DD into the network. If the SEPA DD is initiated early in the morning, then it will be submitted in the network in the same day D-1;
  • D: The D day is known as the Execution day for a SEPA Direct Debit – funds are transferred from debtor’s bank to the merchant’s SEPA DD account.;
  • D -> D+5: the payment remains Open unless an incident (R-Transaction) is reported. If an incident – reject, refusal, return – is registered, a notification for status Failed with ReasonCode and Reason (including the R-Transaction code) will be sent to the merchant;
  • D+6: If no incident occurred until D+5, the transaction is settled and the SEPA DD updates to status Success. Now the merchant can provide the product/service to the customer;
  • D+6 -> D+8 weeks / D+13 months: If the customer does not recognize the Direct Debit, he can claim the money back in 8 weeks, no questions asked and up to 13 months, if the customer’s bank agrees. This situation is also considered an incident (R-Transaction). If this happens, you will receive a Reversed notification with ReasonCode and Reason (including the R-Transaction) which you should properly handle on your side.

All days should be considered banking days!

Pre-notification:

Debtor pre-notification: is a 14 days notification period (this can be reduced upon debtor agreement).

This pre-notification must include the following information: the payment due date, the payment amount, the Unique Mandate Reference and the merchant Creditor Identifier. There is no requirement regarding the method of communication, meaning that this can be done through agreement on General Terms and Conditions, it can be solely written on an invoice, it can be displayed in an online customer account.