SEPA

Last changes: 10-28-2022

Get Financial Institution Data
Initiate Storing of New Payment Option
Collect Payment Option Details via SDK
SEPA Mandate Acceptance Page
Complete Storing of ew Payment Option

1. Get Financial Institution Data

Before initializing the authorization process, call the API method 1.84 Get Financial Institution Data.

Get Financial Institution Data Request

Path:: GET {baseURL}/settings/getFinancialInstitutionData?localDate=2017-08- 21&localTime=170911&partnerReference=TEST-4H363TJC68
Header:: Content-Type: application/json
Accept-Language: en-US

This will provide you with information about the financial institution, which will act as a Creditor in the SEPA Direct Debit process. This information is necessary for the SEPA Mandate Acceptance Page.

Get Financial Institution Data Response

Status Code:: 200 (OK)
Header:: Content-Type: application/json
Accept-Language: en-US

{
    "name": "Volkswagen Payments S.A. (SANDBOX)",
    "addr1": "19-21, Route d’Arlon",
    "city": "Luxembourg",
    "state": "Strassen",
    "countryName": "Germany",
    "countryCode": "DE",
    "countryCode3": "DEU",
    "postCode": "L-8009",
    "creditorIdentifier": "DE98ZZZ09999999999",
    "contactPhone": "+49 892 488 5811",
    "contactEmail": "user@example.com",
    "partnerReference": "DEV-SVR001-DE_CUSTID-T8933PXJPK_CARTID-DJ7JKK662D_FK8K3MPJBQ",
    "localDate": "2018-10-24",
    "localTime": "093028",
    "sysDate": "2018-10-24",
    "sysTime": "073028",
    "responseCode": "0000",
    "responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

2. Initiate Storing of New Payment Option

SEPA
SEPA (Pay.ON)

The storing of a new payment option is initialized by calling the API method 1.53 Init Add Stored Payment Option.

In the example below, we initiate the storing of a SEPA payment option for the account number KDNR0001.

Initiate Storing of New Payment Option Request

Path:: POST {baseURL}/account/KDNR0001/storedPaymentOptions/initAdd
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
    "partnerReference": "DEV-SVR001-DE_CUSTID-XW27JWC32Q_CARTID-T9GKDRFGTY_QJYDTXD7K2",
    "programCode": "COMPANYDE",
    "accnoType": "00",
    "paymentOptionCode": "BNKACCT",
    "mandateReference": "446ED8B3F6FD4CC195FB4D6E860E675A",
    "mandateSignedDate": "2018-11-02",
    "mandateSignedTime": "145216",
    "criteria": [
        {
            "name": "callbackURL",
            "value": "https://example.com/Payment/CompleteAuthorize?SessionID=GP123EX456WC789"
        }
    ],
    "localDate": "2018-11-02",
    "localTime": "145216"
}

The mandate reference is a unique identification number for each SEPA direct debit signed by one of your customers. You are free in assigning the mandate reference as long as it is unique and does not exceed 35 characters.

The Mandate Time and Mandate Date provide a time stamp, which is crucial for potential refund deadlines.

The value of "callbackURL" (provided in "criteria") specifies the endpoint where you will receive a POST request once the payment details are committed. The Request Body must be passed as "paymentProviderResponse" in the subsequent "Complete Authorize" API Call.

Only URLs starting with "https://" are permitted as the value of "callbackURL"

As shown in the above example it is possible to add a "SessionID" parameter in the "callbackURL" so both the Redirect URL and POST Request can be easily identified for the relevant user payment instance.

Initiate Storing of New Payment Option Response

Status Code:: 201 (Created)
Header:: Content-Type: application/json
Accept-Language: en-US

{
    "accno": "KDNR0001",
    "authorizationToken": "yX15XwyXWe{partial omission for brevity}y5XwyXW9",
    "paymentOptionCode": "BNKACCT",
    "paymentProviderResponse": "yX15XwyXWe{partial omission for brevity}y5XwyXW9",
    "programCode": "COMPANYDE",
    "partnerReference": "DEV-SVR001-DE_CUSTID-XW27JWC32Q_CARTID-T9GKDRFGTY_QJYDTXD7K2",
    "localDate": "2018-11-02",
    "localTime": "145216",
    "sysDate": "2018-11-02",
    "sysTime": "135216",
    "responseCode": "0000",
    "responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

The response includes the desired authorization token under the return parameter "authorizationToken" which is needed to complete the storing of the payment option in further steps.

The storing of a new payment option is initialized by calling the API method 1.53 Init Add Stored Payment Option.

In the example below, we initiate the storing of a SEPA payment option for the account number KDNR0001.

Initiate Storing of New Payment Option Request

Path:: POST {baseURL}/account/KDNR0001/storedPaymentOptions/initAdd
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
    "partnerReference": "DEV-SVR001-DE_CUSTID-XW27JWC32Q_CARTID-T9GKDRFGTY_QJYDTXD7K2",
    "programCode": "COMPANYDE",
    "accnoType": "00",
    "paymentOptionCode": "BNKACCT",
    "mandateReference": "446ED8B3F6FD4CC195FB4D6E860E675A",
    "mandateSignedDate": "2018-11-02",
    "mandateSignedTime": "145216",
    "localDate": "2018-11-02",
    "localTime": "145216"
}

The Mandate Time and Mandate Date provide a time stamp, which is crucial for potential refund deadlines.

Initiate Storing of New Payment Option Response

Status Code:: 201 (Created)
Header:: Content-Type: application/json
Accept-Language: en-US

{
    "accno": "KDNR0001",
    "authorizationToken": "CBDD05A6B6A1507D182815CC89E29766.uat01-vm-tx02",
    "paymentOptionCode": "BNKACCT",
    "paymentProviderResponse": {
        "result": {
            "code": "000.200.100",
            "description": "successfully created checkout"
        },
        "buildNumber": "9b2e7602bf0051f076df6fcdfdbf9eea4c60a5dc@2018-10-31 07:33:28 +0000",
        "timestamp": "2018-11-02 13:52:16+0000",
        "ndc": "CBDD05A6B6A1507D182815CC89E29766.uat01-vm-tx02",
        "id": "CBDD05A6B6A1507D182815CC89E29766.uat01-vm-tx02"
    },
    "programCode": "COMPANYDE",
    "partnerReference": "DEV-SVR001-DE_CUSTID-XW27JWC32Q_CARTID-T9GKDRFGTY_QJYDTXD7K2",
    "localDate": "2018-11-02",
    "localTime": "145216",
    "sysDate": "2018-11-02",
    "sysTime": "135216",
    "responseCode": "0000",
    "responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

The response includes the desired authorization token under the return parameter "authorizationToken" which is needed to complete the storing of the payment option in further steps.

3. Collect Payment Option Details via SDK

SEPA
SEPA (Pay.ON)

The SDK renders a customizable payment form and sends the entered payment details directly from the customer's browser to us. We offer SDKs for the integration into websites as well as mobile applications (Android and iOS).

The example below shows only the relevant part of the Web SDK implementation for storing a SEPA payment option. A complete and detailed description of the Web SDK can be found here.

The Web SDK is used to securely collect the payment option details. The authorization token returned by the API method 1.53 Init Add Stored Payment Option which initiated the storing is used to associate the payment option details collected via the Web SDK with the storing process.

Collect Payment Option Details via Web SDK

cw.initialize (
{
   apiURL: {baseURL}, // KontoCloud API Base URL.
   bankAccountPaymentProvider: "sepa" // Required for SEPA payment provider.
 }
);

cw.PaymentForm(container, 
{
   authorizationToken: "yX15XwyXWe{partial omission for brevity}y5XwyXW9",
   paymentOptionCodes: ["BNKACCT"], 
   submitButtonTitle: "Continue",
   //Only as example. Use own SEPA Mandate Handler, with necessary data.
   onBeforeSubmit: function(data, submit, cancel) { // Show SEPA Mandate
      var mandate = confirm("Example SEPA Mandate Acceptance Page"+
      "Name = " + data.accountHolder +"\n"+ "IBAN = " + data.iban);
      if(mandate) { submit(); } // User Accepts SEPA Mandate
      else { cancel(); } // Mandate Rejected, Can Edit Form
    },
    onError: function(message) { 
     console.log(message); 
   }
}
);

Please contact your Payment Solutions Specialist to align on the {baseURL} that will be used as apiEndpoint.

Before the shopper can submit the payment, they must accept the SEPA Mandate. This can be ensured with the “onBeforeSubmit”-function (see example above). First, extract the IBAN from the payment form rendered by the Web SDK, and show it on the SEPA Mandate Acceptance Page.

The example below shows only the relevant part of the Web SDK implementation for storing a SEPA payment option. A complete and detailed description of the Web SDK can be found here.

Collect Payment Option Details via Web SDK

cw.PaymentForm(container,
{
    authorizationToken: "CBDD05A6B6A1507D182815CC89E29766.uat01-vm-tx02",
    callbackUrl: "https://www.example.com/StoredPaymentOptions/CompleteAdd",
    paymentOptionCodes: ["BNKACCT"],
    locale: "en-US",
    paymentProviderMode: "test",
    submitButtonTitle: "Continue",
    onBeforeSubmit: function (data, callback) {
        var iban = document.getElementsByClassName("wpwl-control-accountIban")[0].value;  // extract iban
        $('#modal').show();  // show mandate acceptance page
        $('#accept').select();  // ?
        document.getElementById("iban").innerHTML = iban;  // display iban in mandate acceptance page
        $('#accept').click(function () { callback() });  // mandate must be accepted before submit
    },
    onError: function(message) {
     console.log(message);
    }
}
);

The "callbackURL" should be replaced with the URL identifying the server side method which will call the next API method to complete the authorization (see 5. Complete Storing of New Payment Option).

Before the shopper can submit the new payment option, they must accept the SEPA Mandate. This can be ensured with the “onBeforeSubmit”-function (see example above). First, extract the IBAN from the payment formula rendered by the Web SDK, and show it on the SEPA Mandate Acceptance Page. The callback-function is not invoked until the user clicks the accept-button, thus submitting the payment form.

4. SEPA Mandate Acceptance Page

Each mandate must include certain mandatory legal wording and mandatory information. The page collects not only the details of customer (name, address, etc.) and creditor information (see 1. Get Financial Institution data), but also the mandate parameters (Mandate Reference Number, Date, Time). You must display the following standard authorization text (replacing {FI name} with the name of the creditor) clearly visible and close to the accept button.

With the SEPA direct debit authorization, you authorize {FI name} to send instructions to your bank account. You also authorize your bank to debit your account in accordance with the instructions from {FI name}. A refund must be claimed within 8 weeks, starting from the date on which your account was debited.

We suggest to display the mandate in a modal window as depicted in the mockup below.

We highly recommend to use a GUID (Globally Unique Identifier) with the canonical 8-4-4-4-12 format as the mandate reference number.

With accepting the SEPA Mandate, the customer authorizes you to collect payments for the specified amount from their bank account using SEPA Direct Debit and is redirected to the specified “callbackURL”.

5. Complete Storing of New Payment Option

SEPA
SEPA (Pay.ON)

When the POST request arrives at the specified "callbackURL" you can then proceed to call the 1.54 Complete Add Stored Payment Option API, providing the content of the POST request's body as an URL-Encoded string in the "paymentProviderResponse" parameter under the "criteria" array.

Complete Storing of New Payment Option Request

Path:: PUT {baseURL}/account/KDNR0001/storedPaymentOptions/completeAdd
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
    "partnerReference": "DEV-SVR001-DE_CUSTID-CJWWJW6VWF_CARTID-KTYXQRWGQV_86TCVCYR46",
    "programCode": "COMPANYDE",
    "accnoType": "00",
    "paymentOptionCode": "BNKACCT",
    "authorizationToken": "yX15XwyXWe{partial omission for brevity}y5XwyXW9",
    "criteria": [
        {
            "name": "paymentProviderResponse",
            "value": "data=a0%ln7fr4h{partial omission for brevity}fr4hK9Bl%0"
        }
    ],
    "useDifferentBillingAddress": false,
    "localDate": "2018-11-02",
    "localTime": "145841"
}

Complete Storing of New Payment Option Response

Status Code:: 200 (OK)
Header:: Content-Type: application/json
Accept-Language: en-US

{
    "accno": "KDNR0001",
    "paymentOptionCode": "BNKACCT",
    "storedPaymentOptionReference": "8ac7a4a266c593040166d4b7d08e2201",
    "initiationCountryCode": "DE",
    "initiationCountryCode3": "DEU",
    "programCode": "COMPANYDE",
    "partnerReference": "DEV-SVR001-DE_CUSTID-CJWWJW6VWF_CARTID-KTYXQRWGQV_86TCVCYR46",
    "localDate": "2018-11-02",
    "localTime": "145841",
    "sysDate": "2018-11-02",
    "sysTime": "135842",
    "responseCode": "0000",
    "responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
  
}

Since the SDK sends the payment option details directly to us, you have no knowledge about the current status of the storing process and if it got authorized. Therefore, call the API method 1.54 Complete Add Stored Payment Option from your server side method behind the “callbackURL”, which you specified in the SDK.

Note, that authorization token is attached to the “callbackUrl” (as query string parameter “id”). This approach avoids having to persist this variable on the server side and is thus recommended practice.

Complete Storing of New Payment Option Request

Path:: PUT {baseURL}/account/KDNR0001/storedPaymentOptions/completeAdd
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
    "partnerReference": "DEV-SVR001-DE_CUSTID-CJWWJW6VWF_CARTID-KTYXQRWGQV_86TCVCYR46",
    "programCode": "COMPANYDE",
    "accnoType": "00",
    "paymentOptionCode": "BNKACCT",
    "authorizationToken": "CBDD05A6B6A1507D182815CC89E29766.uat01-vm-tx02",
    "useDifferentBillingAddress": false,
    "localDate": "2018-11-02",
    "localTime": "145841"
}

In some cases (ex. where the user's device loses internet connectivity) the redirect to the specified "callbackUrl" does not take place. To prevent the storing from expiring despite it being successful, the API method 1.54 Complete Add Stored Payment Option should be called automatically from your backend 28 minutes after 1.53 Init Add Stored Payment Option has been called

Complete Storing of New Payment Option Response

Status Code:: 200 (OK)
Header:: Content-Type: application/json
Accept-Language: en-US

{
    "accno": "KDNR0001",
    "paymentOptionCode": "BNKACCT",
    "storedPaymentOptionReference": "8ac7a4a266c593040166d4b7d08e2201",
    "initiationCountryCode": "DE",
    "initiationCountryCode3": "DEU",
    "paymentProviderResponse": {
        "id": "8ac7a4a266c593040166d4b7d08e2201",
        "paymentBrand": "DIRECTDEBIT_SEPA",
        "result": {
            "code": "000.100.110",
            "description": "Request successfully processed in 'Merchant in Integrator Test Mode'"
        },
        "bankAccount": {
            "holder": "Jacob Smith",
            "number": "DE89370400440532013000",
            "iban": "DE89370400440532013000",
            "country": "DE"
        },
        "customer": {
            "ip": "198.51.100.0"
        },
        "customParameters": {
            "kcMandateSignedDate": "2018-11-02T14:52:16",
            "kcMandateReference": "446ED8B3F6FD4CC195FB4D6E860E675A"
        },
        "risk": {
            "score": "0"
        },
        "buildNumber": "9b2e7602bf0051f076df6fcdfdbf9eea4c60a5dc@2018-10-31 07:33:28 +0000",
        "timestamp": "2018-11-02 13:58:28+0000",
        "ndc": "CBDD05A6B6A1507D182815CC89E29766.uat01-vm-tx02"
    },
    "programCode": "COMPANYDE",
    "partnerReference": "DEV-SVR001-DE_CUSTID-CJWWJW6VWF_CARTID-KTYXQRWGQV_86TCVCYR46",
    "localDate": "2018-11-02",
    "localTime": "145841",
    "sysDate": "2018-11-02",
    "sysTime": "135842",
    "responseCode": "0000",
    "responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

The "responseCode" 0000 and the “responseDescription” indicate that the new payment option has been successfully stored.

The "storedPaymentOptionReference" parameter is used to identify the tokenized payment option as part of other API methods (see section Payment Process). You can either store it on your server or retrieve it via an API call (see section Get Stored Payment Options).

Previous

Next