Introduction

Our API is based on the REST software architectural style and provides a secure and comfortable way to perform payments.

API errors are indicated by the corresponding HTTP response codes. This topic is further described in the section Error Handling

In addition to our payment solutions, the API supports mutliple features like our Auxiliary Services. Have a look into our Documentation to gain a deeper understanding of our various products.

Having a 90 second timeout interval allows handling of delays dependent on different queries and responses form external systems and payment providers.

 API Authentication

A web client integration must include an authentication token as part of the HTTP header for all but a few anonymous API methods. Use the provided credentials when requesting an authentication token via the API method 1.45 Issue Token.

The response will include the JWT authentication token under the return parameter "token" which you include in the HTTP header when calling other API methods via the custom header field "X-Auth-Token" or "Authorization".

Authentication means one of the following:
A security token in the form of JWT to be present in the custom authentication header. To get an assertion, call the "Issue Token" or the "Issue Oauth Token" method.
A request signed by a non-expired certificate that belongs to active and not-locked user.

Please note, that authentication tokens have a limited validity period - their expiration time (UTC) is communicated to you via the return parameter "validUntil". The token can be used until the expiration time and should be replaced by a new one shortly before the expiration. By persisting the token alongside the expiration time, it is possible to call multiple API methods with the same token until it expires. It is recommended that tokens are reused instead of requested for each API method call in order to avoid a perception of a performance issue in web applications.

 1.45 Issue Token

post {baseURL}/user/{userId}/issue

This method is called to authenticate the caller and get a security token. Attach this security token to all other API method calls.

Request parameters

userId
String Length: 255 Required

Caller user identifier in the KontoCloud system.

password
String Length: 128 Required

Caller password in the KontoCloud system.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:

POST {baseURL}/user/user@example.com/issue

Header:

Content-Type: application/json
Accept-Language: en-US

{
  "password": "3x4mpl3Pa$$w0rd",
  "localDate": "2020-12-31",
  "localTime": "235959"
}

Response parameters

token
String Length: 32768

Security token.

validUntil
YYYY-MM-DD Length: 24

Token validity period in UTC.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
  "token": "eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=",
  "validUntil": "2020-12-31T23:59:59.001Z",
  "localDate": "2020-12-31",
  "localTime": "235959",
  "sysDate": "2020-12-31",
  "sysTime": "235959",
  "responseCode": "0000",
  "responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 Error Handling

The platform has standardized error codes made up of four digits, which are returned under the “responseCode” return parameter. i.e. these do not change and should be used as part of exception handling logic.

Errors can be broadly classified as Logical Errors and Unexpected Errors.

Communication of errors to end users

Technical error codes or other details of why a request could not be completed, must not be disclosed to an end user directly, as this might increase the risk of fraudulent activity.

Especially when it comes to credit card fraud, fraudsters often target websites that give a different response to different types of declination (e.g. where one response is returned for the amount exceeding the available credit and another where a card is flagged as stolen).

Thus in the interest of data protection and to prevent malicious activity, we recommend having a single response towards the end user for all types of declined transactions:

Currently your request cannot be processed, error code xxx. Please retry using a different payment option and if the issue persists contact our support team by email ({0}) or by phone ({1})”

Doing so increases the difficulty of malicious activity especially the probing of automatically generated card numbers.

From the end user's perspective this means that after the first payment failure, they should be prompted to retry having validated their entered payment option details. They should also be advised that if the payment option continues to fail, that they should contact their bank (or other financial institution) to ascertain the exact reason(s) of declination or to try an alternative payment option.

In the cases when a service request needs to be submitted, please include the following technical identifiers:

  • the 4-digit numeric responseCode (error)
  • "requestId" (returned in the api response)
  • "partnerReference" (request & response)
  • "uniqueReference" (if such is applicable)
  • the timestamp of when the error occurred
  • the user's account number (if applicable)

Capture Error Handling

An authorization is generally a guarantee that a capture should succeed. However a capture can nonetheless fail due to errors between the Gateway and Acquirer. You can retry your request up to 3 times. If the error continues to persist, you can contact Customer Support for details.

Logical Errors

On the right you find a response sample of a handled exception. The Response Code 0001 indicates that mandatory fields are missing or syntax errors (e.g. wrong datatype, spelling) exist in the API request.

Another important exception has the response code 0096 and occurs when the user tries to perform an unauthorized API call. This means that the provided X-Auth-Token in the HTTP-Header is either missing or invalid (see section API Authentication).

Please note, that the response codes 0058 and 0098 allow a retry of the API call up to 3 times.

In most cases, the response code provides enough information, which allow you to further investigate the source of the error. Otherwise you can contact our Customer Support.

 

 

 

Response sample

Status Code:

400 (Bad Request)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "78838436FDD0445081099C7D931F7041",
"responseCode": "0001",
"responseDescription": "One or more of the required fields has not been sent or was not properly received by the API: 'programCode'.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

Unexpected Errors

On the right you find a response sample of an unhandled exception.

You can retry your request up to 3 times. If the error continues to persist, you can contact our Customer Support for details.

 

Response sample

Status Code:

500 (Internal Server Error)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "78838436FDD0445081099C7D931F7041",
"sysDate": "2021-02-20",
"sysTime": "054749",
"responseCode": "0099",
"responseDescription": "Unexpected server error occurred.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 Account Management

 1.1 Create Account

put {baseURL}/account

This method is used to create an e-wallet account.

Request parameters

externalAccountReference
String Length: 255

Account reference to identify the account in the future by the partners in their system.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accountApplicationFlowCode
String Length: 10

Code of the account application flow. A program default flow of Type "E-Wallet User" is used if a value is not provided.

currCode
String Length: 3 Required

Currency code of the account to be opened.

validFrom
YYYY-MM-DD Length: 10

Start date of the account.

validUntil
YYYY-MM-DD Length: 10

Expiry date of the account.

Deprecated and ignored field.

loginID
String Length: 255

Login ID of the customer using the service.

title
String Length: 2

Customer's title. See Title Codes in the Lookups.

lastName
String Length: 100 Required

Customer's last name.

firstName
String Length: 100 Required

Customer's first name.

culture
String Length: 14

User culture, based on RFC 4646. For example, "de-DE".

addr1
String Length: 60 Required

Address line 1.

addr2
String Length: 60

Address line 2.

addr3
String Length: 60

Address line 3.

houseNumber
String Length: 10

House number.

city
String Length: 50 Required

City name.

state
String Length: 50

State name.

countryCode
String Length: 3 Required

Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

postCode
String Length: 10 Required

Postal code.

dob
YYYY-MM-DD Length: 10 Required

Date of birth.

placeOfBirth
String Length: 100

Place of birth.

landlinePhone
String Length: 30

Landline phone number.

mobilePhone
String Length: 30

Mobile phone number.

emailAddress
String Length: 255 Required

Email address for any notification.

useDifferentCorrespondenceAddress
Boolean Required

Defines whether a different correspondence address is used. If true, the fields 'correspondenceAddr1', 'correspondenceCity', 'correspondenceCountryCode', 'correspondencePostCode' are required. If false, the fields listed above are optional.

correspondenceAddr1
String Length: 60

Correspondence address line 1.

correspondenceAddr2
String Length: 60

Correspondence address line 2.

correspondenceAddr3
String Length: 60

Correspondence address line 3.

correspondenceHouseNumber
String Length: 10

Correspondence house number.

correspondenceCity
String Length: 50

Correspondence city name.

correspondenceState
String Length: 50

Correspondence state name.

correspondenceCountryCode
String Length: 3

Correspondence country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

correspondencePostCode
String Length: 10

Correspondence postal code.

occupation
String Length: 50

A job or profession.

nationality
String Length: 3 Required

The ISO2 or ISO3 code of a country a new user is a national of.

taxId
String Length: 50

Tax identification number.

identificationDocumentType
String Length: 50

Type of the new user's identification document e.g. passport.

identityNumber
String Length: 20

Identification document number.

documentIssuingCountryCode
String Length: 3

The ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of a country that issued the identification document.

dateOfExpiry
YYYY-MM-DD Length: 10

Expiry date of the identification document.

sourceOfWealth
String Length: 50

The activity which generated the new user's total net worth.

sourceOfFunds
String Length: 50

The main activity which generates the new user's funds for this ewallet.

isPep
Boolean

Is the new user or his/her family member a politically exposed person.

isBusinessUser
Boolean

Defines whether business information is provided for a user.
Default value is false.

If true, the fields 'businessCompanyName', 'businessCompanyType', 'businessCompanyRegistrationNumber', 'businessCompanyRegistrationCountry', 'businessAddr1', 'businessCity', 'businessPostCode', 'businessCountryCode' are required.

If false, the fields listed above are optional.

businessCompanyName
String Length: 201

Company legal name.

businessCompanyType
String Length: 100

Company legal type.

businessCompanyRegistrationNumber
String Length: 50

Company registration number.

businessCompanyRegistrationCountryCode
String Length: 3

Company registration country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

businessAddr1
String Length: 60

Company address line 1.

businessAddr2
String Length: 60

Company address line 2.

businessAddr3
String Length: 60

Company address line 3.

businessHouseNumber
String Length: 10

Company house number.

businessCity
String Length: 50

Company city name.

businessPostCode
String Length: 10

Company post code.

businessState
String Length: 50

Company state name.

businessCountryCode
String Length: 3

Company country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

businessUrl
String Length: 255

Company website URL.

userAgreementReference
String Length: 36

Reference to the user agreement text.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

PUT {baseURL}/account

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
 "externalAccountReference": "CUSTID1234567890",
 "partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
 "programCode": "COMPANY123",
 "accountApplicationFlowCode": "BIZ",
 "currCode": "EUR",
 "validFrom": "2016-01-31",
 "loginID": "firstname_lastname",
 "title": "1",
 "lastName": "Lastname",
 "firstName": "Firstname",
 "addr1": "123 Anystreet",
 "addr2": "Building 1a",
 "city": "Anycity",
 "state": "Anystate",
 "countryCode": "DE",
 "postCode": "POSTCOD123",
 "dob": "1990-01-31",
 "placeOfBirth": "Anycountry, Anycity",
 "landlinePhone": "+49 1234 567 890",
 "mobilePhone": "+49 1234 567 890",
 "emailAddress": "user@example.com",
 "useDifferentCorrespondenceAddress": true,
 "correspondenceAddr1": "Anystreet 321",
 "correspondenceAddr2": "Tower 1",
 "correspondenceCity": "Anycity",
 "correspondenceState": "Anystate",
 "correspondenceCountryCode": "DE",
 "correspondencePostCode": "12345",
 "occupation": "Computer systems analyst",
 "nationality": "DE",
 "identificationDocumentType": "Passport",
 "identityNumber": "P1234567890",
 "documentIssuingCountryCode": "DE",
 "dateOfExpiry": "2123-01-31",
 "sourceOfWealth": "Inheritance and Savings from Employment Income",
 "sourceOfFunds": "Insurance Payout",
 "isPep": false,
 "isBusinessUser": true,
 "businessCompanyName": "Anycompany Name",
 "businessCompanyType": "Ltd",
 "businessCompanyRegistrationNumber": "12345678",
 "businessCompanyRegistrationCountryCode": "DE",
 "businessAddr1": "Anystreet 456",
 "businessAddr2": "Building 2b",
 "businessCity": "Anycity",
 "businessState": "CA",
 "businessPostCode": "EC4M 7LS",
 "businessCountryCode": "DE",
 "businessUrl": "https://www.example.com",
 "userAgreementReference": "4CE1ABB1676E3DF5BB4450F45B51E07D",
 "localDate": "2016-01-31",
 "localTime": "131415"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

productCode
String Length: 10

Account product of the new account.

accTypeCode
String Length: 10

Account type code of the account.

custCode
String Length: 10

Customer identifier generated by KontoCloud.

externalAccountReference
String Length: 255

Account reference to identify the account in the future by the partners in their system.

accno
String Length: 255

Account number.

statusCode
String Length: 10

Status code of the account. See Account Status Codes in the Lookups.

twoFAStatusCode
String Length: 10

Two Factor Authentication Status Code. Refer to Two Factor Authentication Status Codes in the Lookups.

accFlowStatusCode
String Length: 10

Status code of the account flow. See Account Flow Status Codes in the Lookups.

validFrom
YYYY-MM-DD Length: 10

Start date of the account.

validUntil
YYYY-MM-DD Length: 10

Expiry date of the account.

Deprecated and ignored field.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

201 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"productCode": "EWLTDBT",
"accTypeCode": "STARTBIZ",
"custCode": "22",
"externalAccountReference": "CUSTID1234567890",
"accno": "1000104149",
"statusCode": "ACTIVE",
"twoFAStatusCode": "2FADIS",
"validFrom": "2016-01-31",
"validUntil": "2999-12-31",
"accFlowStatusCode": "POPENDING",
"partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
"programCode": "COMPANY123",
"localDate": "2016-01-31",
"localTime": "131415",
"sysDate": "2016-01-31",
"sysTime": "114249",
"responseCode": "0000",
"responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.4 Update Account Information

post {baseURL}/account/{accno}/updateInfo

Provides the ability to update an account holder's information.

Request parameters

accno
String Length: 255 Required

Account number.

externalAccountReference
String Length: 255

Account reference to identify the account in the future by the partners in their system.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

accTypeCode
String Length: 10

Account type code of the account.

title
String Length: 2

Customer's title. See Title Codes in the Lookups.

lastName
String Length: 100 Required

Customer's last name.

firstName
String Length: 100 Required

Customer's first name.

addr1
String Length: 60 Required

Address line 1.

addr2
String Length: 60

Address line 2.

addr3
String Length: 60

Address line 3.

houseNumber
String Length: 10

House number.

city
String Length: 50 Required

City name.

postCode
String Length: 10 Required

Postal code.

state
String Length: 50

State name.

countryCode
String Length: 3 Required

Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

dob
YYYY-MM-DD Length: 10 Required

Date of birth.

landlinePhone
String Length: 30

Landline phone number.

mobilePhone
String Length: 30

Mobile phone number.

emailAddress
String Length: 255 Required

Email address for any notification.

nationality
String Length: 3 Required

The ISO2 or ISO3 code of a country a new user is a national of.

culture
String Length: 14

User culture, based on RFC 4646. For example, "de-DE".

timeZone
String Length: 50

User time zone id. For example, "Central European Standard Time". See Time Zone in the Lookups.

useDifferentCorrespondenceAddress
Boolean Required

Defines whether a different correspondence address is used. If true, the fields 'correspondenceAddr1', 'correspondenceCity', 'correspondenceCountryCode', 'correspondencePostCode' are required. If false, the fields listed above are optional.

correspondenceAddr1
String Length: 60

Correspondence address line 1.

correspondenceAddr2
String Length: 60

Correspondence address line 2.

correspondenceAddr3
String Length: 60

Correspondence address line 3.

correspondenceHouseNumber
String Length: 10

Correspondence house number.

correspondenceCity
String Length: 50

Correspondence city name.

correspondenceState
String Length: 50

Correspondence state name.

correspondenceCountryCode
String Length: 3

Correspondence country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

correspondencePostCode
String Length: 10

Correspondence postal code.

taxId
String Length: 50

Tax identification number.

identificationDocumentType
String Length: 50

Type of the new user's identification document e.g. passport.

identityNumber
String Length: 20

Identification document number.

documentIssuingCountryCode
String Length: 3

The ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of a country that issued the identification document.

dateOfExpiry
YYYY-MM-DD Length: 10

Expiry date of the identification document.

notifyUser
Boolean

Defines whether the account owner is notified of the account information change. Default value is false.

businessCompanyName
String Length: 201

Company legal name.

businessCompanyType
String Length: 100

Company legal type.

businessCompanyRegistrationNumber
String Length: 50

Company registration number.

businessCompanyRegistrationCountryCode
String Length: 3

Company registration country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

businessAddr1
String Length: 60

Company address line 1.

businessAddr2
String Length: 60

Company address line 2.

businessAddr3
String Length: 60

Company address line 3.

businessHouseNumber
String Length: 10

Company house number.

businessCity
String Length: 50

Company city name.

businessState
String Length: 50

Company state name.

businessPostCode
String Length: 10

Company post code.

businessCountryCode
String Length: 3

Company country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

businessUrl
String Length: 255

Company website URL.

userAgreementReference
String Length: 36

Reference to the user agreement text.

oneTimePassword
Number Length: 8

One Time Password used for confirmation during Two Factor Authentication.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

POST {baseURL}/account/XXX-123456/updateInfo

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
"partnerReference": "1234567890",
"externalAccountReference": "CUSTID1234567890",
"userAgreementReference": "4CE1ABB1676E3DF5BB4450F45B51E07D",
"programCode": "PROG",
"accnoType": "00",
"accTypeCode": "MA-FVFD",
"title": "1",
"lastName": "Lastname",
"firstName": "Firstname",
"addr1": "Address 1",
"addr2": "",
"city": "City",
"state": "State",
"countryCode": "DE",
"postCode": "12345",
"dob": "1990-01-01",
"landlinePhone": "+49123456789",
"mobilePhone": "+491234567890",
"emailAddress": "user@example.com",
"nationality": "DE",
"culture": "de-DE",
"timeZone": "Central European Standard Time",
"useDifferentCorrespondenceAddress": true,
"correspondenceAddr1": "Address 1",
"correspondenceCity": "City",
"correspondenceCountryCode": "DE",
"correspondencePostCode": "12345",
"oneTimePassword": 123456,
"localDate": "2014-03-12",
"localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"programCode": "PROG",
"accno": "XXX-123456",
"providerResponse":
{
"complianceData":
{
"archiveId": "4108000025015465",
"trafficLight": "YELLOW",
"hitType": "SL",
"manualReview": true,
"details":
[
{
"name": "Lastname Firstname",
"birthdate": "19900101"
},
{
"name": "Firstname Lastname",
"birthdate": "19900101"
}
]
}
},
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.5 Get Account Information

get {baseURL}/account/{accno}?partnerReference={partnerReference}&programCode={programCode}&accnoType={accnoType}&localDate={localDate}&localTime={localTime}

Returns the account holder information.

Request parameters

accno
String Length: 255 Required

Account number.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

GET {baseURL}/account/XXX-123456?partnerReference=50F45B51E07D4CE1ABB1676E3DF5BB44&programCode=COMPANY123&accnoType=01&localDate=2016-01-31&localTime=131415

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=


Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

externalAccountReference
String Length: 255

Account reference to identify the account in the future by the partners in their system.

merchantName
String Length: 201

Merchant name.

title
Number Length: 1

Customer's title. See Title Codes in the Lookups.

lastName
String Length: 100

Customer's last name.

firstName
String Length: 100

Customer's first name.

addr1
String Length: 60

Address line 1.

addr2
String Length: 60

Address line 2.

addr3
String Length: 60

Address line 3.

houseNumber
String Length: 10

House number.

city
String Length: 50

City name.

state
String Length: 50

State name.

countryName
String Length: 100

Country name.

countryCode
String Length: 3

Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

postCode
String Length: 10

Postal code.

dob
YYYY-MM-DD Length: 10

Date of birth.

landlinePhone
String Length: 30

Landline phone number.

mobilePhone
String Length: 30

Mobile phone number.

emailAddress
String Length: 255

Email address for any notification.

loginID
String Length: 255

Login ID of the customer using the service.

culture
String Length: 14

User culture, based on RFC 4646. For example, "de-DE".

timeZone
String Length: 50

User time zone id. For example, "Central European Standard Time". See Time Zone in the Lookups.

useDifferentCorrespondenceAddress
Boolean

Defines whether a different correspondence address is used.

correspondenceAddr1
String Length: 60

Correspondence address line 1.

correspondenceAddr2
String Length: 60

Correspondence address line 2.

correspondenceAddr3
String Length: 60

Correspondence address line 3.

correspondenceHouseNumber
String Length: 10

Correspondence house number.

correspondenceCity
String Length: 50

Correspondence city name.

correspondenceState
String Length: 50

Correspondence state name.

correspondenceCountryName
String Length: 100

Correspondence country name.

correspondenceCountryCode
String Length: 2

Correspondence country ISO 3166-1 alpha-2 code.

correspondenceCountryCode3
String Length: 3

Correspondence country ISO 3166-1 alpha-3 code.

correspondencePostCode
String Length: 10

Correspondence postal code.

nationality
String Length: 2

The user national country ISO2 code.

nationality3
String Length: 3

The user national country ISO3 code.

taxId
String Length: 50

Tax identification number.

currCode
String Length: 3

Currency code of the account.

accTypeName
String Length: 100

Account type of the account.

accTypeCode
String Length: 10

Account type code of the account.

maximumAllowedBalance
Decimal Length: 18

Account's maximum allowed balance.

minimumAllowedBalance
Decimal Length: 18

Account's minimum allowed balance.

statusCode
String Length: 10

Status code of the account. See Account Status Codes in the Lookups.

twoFAStatusCode
String Length: 10

Two Factor Authentication Status Code. Refer to Two Factor Authentication Status Codes in the Lookups.

accFlowStatusCode
String Length: 10

Status code of the account flow. See Account Flow Status Codes in the Lookups.

isEmailVerified
Boolean

Defines whether the user's email is verified.

isMobilePhoneVerified
Boolean

Defines whether the user's mobile phone number is verified.

isUserActive
Boolean

Defines whether the user is active.

isUserLocked
Boolean

Defines whether the user is locked.

lastLoginDate
YYYY-MM-DD Length: 10

Last user login date into the Kontocloud system.

lastLoginTime
HHMMSS Length: 6

Last user login time into the Kontocloud system.

isMtanEnabled
Boolean

Defines whether MTAN support is enabled.

isBusinessUser
Boolean

Defines whether business information is provided for a user.

businessCompanyName
String Length: 201

Company legal name.

businessCompanyType
String Length: 100

Company legal type.

businessCompanyRegistrationNumber
String Length: 50

Company registration number.

businessCompanyRegistrationCountryCode
String Length: 2

Company registration country ISO 3166-1 alpha-2 code.

businessCompanyRegistrationCountryCode3
String Length: 3

Company registration country ISO 3166-1 alpha-3 code.

businessAddr1
String Length: 60

Company address line 1.

businessAddr2
String Length: 60

Company address line 2.

businessAddr3
String Length: 60

Company address line 3.

businessHouseNumber
String Length: 10

Company house number.

businessCity
String Length: 50

Company city name.

businessPostCode
String Length: 10

Company post code.

businessCountryCode
String Length: 2

Company country ISO 3166-1 alpha-2 code.

businessCountryCode3
String Length: 3

Company country ISO 3166-1 alpha-3 code.

businessUrl
String Length: 255

Company website URL.

userAgreementReference
String Length: 36

Reference to the user agreement text.

isUserAgreementUpToDate
Boolean

Identifies the User Agreement actuality.

accountValidUntil
YYYY-MM-DD Length: 10

The latest account validity date.

accountCreationDate
YYYY-MM-DD Length: 10

The account creation date.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"accno": "1000104149",
"title": 1,
"externalAccountReference": "CUSTID1234567890",
"lastName": "Lastname",
"firstName": "Firstname",
"addr1": "123 Anystreet",
"addr2": "Building 1a",
"addr3": null,
"houseNumber": null,
"city": "Anycity",
"state": "Anystate",
"countryCode": "DE",
"countryName": "Germany",
"postCode": "POSTCOD123",
"dob": "1990-01-31",
"landlinePhone": "+49 1234 567 890",
"mobilePhone": "+49 1234 567 890",
"emailAddress": "user@example.com",
"currCode": "EUR",
"accTypeName": "Starter Business",
"accTypeCode": "STARTBIZ",
"maximumAllowedBalance": "1000.00",
"minimumAllowedBalance": "0.00",
"statusCode": "ACTIVE",
"twoFAStatusCode": "2FADIS"
"accFlowStatusCode": "SDDAPPNDNG",
"isEmailVerified": false,
"isUserActive": true,
"isUserLocked": false,
"lastLoginDate": null,
"lastLoginTime": null,
"isMtanEnabled": false,
"culture": null,
"timeZone": "W. Europe Standard Time",
"useDifferentCorrespondenceAddress": true,
"correspondenceAddr1": "Tower 1",
"correspondenceAddr2": null,
"correspondenceAddr3": null,
"correspondenceHouseNumber": null,
"correspondenceCity": "Anycity",
"correspondenceState": "Anystate",
"correspondenceCountryCode": "DE",
"correspondenceCountryName": "Germany",
"correspondencePostCode": "12345",
"nationality": "DE",
"nationality3": "DEU",
"taxId": "9181081508155",
"isBusinessUser": true,
"businessCompanyName": "Anycompany Name",
"businessCompanyType": "Ltd",
"businessCompanyRegistrationNumber": "12345678",
"businessCompanyRegistrationCountryCode": "DE",
"businessAddr1": "Anystreet 456",
"businessAddr2": "Building 2b",
"businessAddr3": null,
"businessHouseNumber": null,
"businessCity": "Anycity",
"businessPostCode": "EC4M 7LS",
"businessCountryCode": "DE",
"businessUrl": "https://www.example.com",
"partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
"programCode": "COMPANY123",
"userAgreementReference": "4CE1ABB1676E3DF5BB4450F45B51E07D",
"isUserAgreementUpToDate": true,
"accountValidUntil": "2999-12-31",
"accountCreationDate": "2016-01-31",
"localDate": "2016-01-31",
"localTime": "000000",
"sysDate": "2016-06-15",
"sysTime": "114249",
"responseCode": "0000",
"responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.73 Close Account

post {baseURL}/account/{accno}/close

The Close Account call will set the status of the account to "Closed", thus disabling the further usage of the account.

Request parameters

accno
String Length: 255 Required

Account number.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

isDataDeleted
Boolean

Whether data deletion is required or not. To delete data, a data deletion request is created. "False" is used, if it is not provided.

externalRequestReference
String Length: 100

A reference assigned to the Data Deletion Request in the external system.

closingReason
String Length: 1024 Required

Reason for closing the accountand data deletion (if it is needed).

storedPaymentOptionReference
String Length: 36

Stored payment option reference to payout the account balance.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

statusCode
String Length: 10

Status code of the account. See Account Status Codes in the Lookups.

dateClosed
YYYY-MM-DD Length: 10

Calendar date when the account was closed.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"programCode": "PROG",
"accno": "XXX-123456",
"statusCode": "CLOSED",
"dateClosed": "2014-03-12",
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 Payment Option Management

 1.53 Init Add Stored Payment Option

post {baseURL}/account/{accno}/storedPaymentOptions/initAdd

This interface method is used to initialize storing a payment option to an e-wallet user or merchant account. The returned 'authorizationToken' is used for communication with the external provider.

Request parameters

accno
String Length: 255 Required

Account number.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

paymentOptionCode
String Length: 10

Payment option code.

externalChannelReference
String Length: 100

External payment provider channel.

mandateReference
String Length: 35

Mandate reference.

mandateSignedDate
YYYY-MM-DD Length: 10

Mandate signing date.

mandateSignedTime
HHMMSS Length: 6

mandateSignedTime

useDifferentBillingAddress
Boolean Required

Defines whether the stored address or a custom billing address is used.

If true, the fields 'customerFullName', 'addr1', 'city', 'countryCode', 'postCode', 'emailAddress' are required.

If false, the account owner address is used.

customerFullName
String Length: 201

Customer full name consisting of the first name and last name.

emailAddress
String Length: 255

Email address.

addr1
String Length: 60

Address line 1.

addr2
String Length: 60

Address line 2.

addr3
String Length: 60

Address line 3.

houseNumber
String Length: 10

House number.

city
String Length: 50

City name.

state
String Length: 50

State name.

countryCode
String Length: 3

Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

postCode
String Length: 10

Postal code.

phone
String Length: 30

Phone number.

currCode
String Length: 3

Currency code of the payment option to be stored.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

POST {baseURL}/account/XXX-123456/storedPaymentOptions/initAdd

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
"partnerReference": "1234567890",
"programCode": "PROG",
"accnoType": "00",
"paymentOptionCode": "MSTRCRD",
"useDifferentBillingAddress": true,
"customerFullName": "Jacob Smith",
"emailAddress": "user@example.com",
"addr1": "Anystreet",
"houseNumber": "321",
"city": "Anycity",
"countryCode": "DE",
"postCode": "12345",
"localDate": "2014-03-12",
"localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

authorizationToken
String Length: 8192

Unique authorization token assigned by an external payment provider.

paymentOptionCode
String Length: 10

Payment option code.

paymentProviderResponse
Object

Complete payment provider response.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"programCode": "PROG",
"accno": "XXX-123456",
"authorizationToken": "0C64A8CAD371F2A1177A9B1B2F505B13.sbg-vm-fe02",
"paymentOptionCode": "MSTRCRD",
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.54 Complete Add Stored Payment Option

put {baseURL}/account/{accno}/storedPaymentOptions/completeAdd

This interface method is used to complete storing a payment option to an e-wallet user or merchant account.

Request parameters

accno
String Length: 255 Required

User or merchant account number.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

paymentOptionCode
String Length: 10

Payment option code.

authorizationToken
String Length: 8192 Required

Unique authorization token assigned by an external payment provider.

useDifferentBillingAddress
Boolean Required

Defines whether the stored address or a custom billing address is used.

If true, the fields 'customerFullName', 'addr1', 'city', 'countryCode', 'postCode', 'emailAddress' are required.

If false, the account owner address is used.

customerFullName
String Length: 201

Customer full name consisting of the first name and last name.

emailAddress
String Length: 255

Email address.

addr1
String Length: 60

Address line 1.

addr2
String Length: 60

Address line 2.

addr3
String Length: 60

Address line 3.

houseNumber
String Length: 10

House number.

city
String Length: 50

City name.

state
String Length: 50

State name.

countryCode
String Length: 3

Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

postCode
String Length: 10

Postal code.

phone
String Length: 30

Phone number.

externalChannelReference
String Length: 100

External payment provider channel.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

PUT {baseURL}/account/XXX-123456/storedPaymentOptions/completeAdd

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
"partnerReference": "1234567890",
"programCode": "PROG",
"accnoType": "00",
"paymentOptionCode": "MSTRCRD",
"authorizationToken": "0C64A8CAD371F2A1177A9B1B2F505B13.sbg-vm-fe02",
"useDifferentBillingAddress": false,
"localDate": "2014-03-12",
"localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

paymentOptionCode
String Length: 10

Payment option code.

storedPaymentOptionReference
String Length: 36

Stored payment option reference.

initiationCountryCode
String Length: 2

Stored Payment Option issuer country ISO2 code.

initiationCountryCode3
String Length: 3

Stored Payment Option issuer country ISO3 code.

paymentProviderResponse
Object

Complete payment provider response.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

201 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"programCode": "PROG",
"accno": "XXX-123456",
"paymentOptionCode": "MSTRCRD",
"storedPaymentOptionReference": "5e71b97bd8aa446ba35161ec5c7af3f2",
"initiationCountryCode": "DE",
"initiationCountryCode3": "DEU",
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.56 Init Verify Stored Payment Option

post {baseURL}/account/{accno}/storedPaymentOptions/{storedPaymentOptionReference}/initVerify

Initiates verification of an e-wallet user or merchant account preferred payment option.

Request parameters

accno
String Length: 255 Required

User or merchant account number.

storedPaymentOptionReference
String Length: 36 Required

Stored payment option reference.

partnerReference
String Length: 64 Required

Partner service call identifier.

programAccno
String Length: 255 Required

Program account number.

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

POST {baseURL}/account/XXX-123456/storedPaymentOptions/5e71b97bd8aa446ba35161ec5c7af3f2/initVerify

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
   "partnerReference": "1234567890",
   "programAccno": "123456",
   "accnoType": "00",
   "localDate": "2014-03-12",
   "localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
   "partnerReference": "1234567890",
   "programCode": "PROG",
   "accno": "XXX-123456",
   "localDate": "2014-03-12",
   "localTime": "163835",
   "sysDate": "2014-03-12",
   "sysTime": "153837",
   "responseCode": "0000",
   "responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.57 Complete Verify Stored Payment Option

post {baseURL}/account/{accno}/storedPaymentOptions/{storedPaymentOptionReference}/completeVerify

Completes verification of an e-wallet user or merchant account preferred payment option.

Request parameters

accno
String Length: 255 Required

User or merchant account number.

storedPaymentOptionReference
String Length: 36 Required

Stored payment option reference.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

verificationCode
Number Length: 6 Required

Payment option verification code.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

POST {baseURL}/account/XXX-123456/storedPaymentOptions/5e71b97bd8aa446ba35161ec5c7af3f2/completeVerify

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
"partnerReference": "1234567890",
"programCode": "PROG",
"accnoType": "00",
"verificationCode": "123456",
"localDate": "2014-03-12",
"localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"programCode": "PROG",
"accno": "XXX-123456",
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.55 Delete Stored Payment Option

del {baseURL}/account/{accno}/storedPaymentOptions/{storedPaymentOptionReference}

Deletes a preferred payment option from an e-wallet user or merchant account.

Request parameters

accno
String Length: 255 Required

User or merchant account number.

storedPaymentOptionReference
String Length: 36 Required

Stored payment option reference.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

DELETE {baseURL}/account/XXX-123456/storedPaymentOptions/5e71b97bd8aa446ba35161ec5c7af3f2

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
   "partnerReference": "1234567890",
   "programCode": "PROG",
   "accnoType": "00",
   "localDate": "2014-03-12",
   "localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
   "partnerReference": "1234567890",
   "programCode": "PROG",
   "accno": "XXX-123456",
   "localDate": "2014-03-12",
   "localTime": "163835",
   "sysDate": "2014-03-12",
   "sysTime": "153837",
   "responseCode": "0000",
   "responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.79 Set Default Stored Payment Option

post {baseURL}/account/{accno}/storedPaymentOptions/{storedPaymentOptionReference}/setDefault

Sets a default stored payment option for an e-wallet user or merchant account.

Request parameters

accno
String Length: 255 Required

User or merchant account number.

storedPaymentOptionReference
String Length: 36 Required

Stored payment option reference.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
   "partnerReference": "1234567890",
   "programCode": "PROG",
   "accno": "XXX-123456",
   "localDate": "2014-03-12",
   "localTime": "163835",
   "sysDate": "2014-03-12",
   "sysTime": "153837",
   "responseCode": "0000",
   "responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.21 Get Payment Options

get {baseURL}/account/{accno}/paymentOptions?partnerReference={partnerReference}&programCode={programCode}&accnoType={accnoType}&transactionTypeCode={transactionTypeCode}&localDate={localDate}&localTime={localTime}

Returns the payment options available for the account's account type.

Request parameters

accno
String Length: 255 Required

Account number.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

transactionTypeCode
String Length: 10 Required

Transaction type. See Transaction Type in the Lookups.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

GET {baseURL}/account/XXX-123456/paymentOptions?partnerReference=1234567890&programCode=PROG&accnoType=00&transactionTypeCode=AUTH&localDate=2014-03- 12&localTime=163835

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=


Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

transactionTypeCode
String Length: 10

Transaction type. See Transaction Type in the Lookups.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"programCode": "PROG",
"accno": "XXX-123456",
"transactionTypeCode": "AUTH",
"paymentOptions": [
{
"name": "Mastercard",
"code": "MSTRCRD",
"paymentGroup": "Cards",
"paymentGroupCode": "CARDS",
"paymentSubGroup": "Credit Cards",
"paymentSubGroupCode": "CRDTCRD",
"isStorable": true,
"iconUrl": "http://www.google.com"
},
{
"name": "VISA",
"code": "VISA",
"paymentGroup": "Cards",
"paymentGroupCode": "CARDS",
"paymentSubGroup": "Credit Cards",
"paymentSubGroupCode": "CRDTCRD",
"isStorable": true,
"iconUrl": "http://www.google.com"
}
],
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.26 Get Stored Payment Options

get {baseURL}/account/{accno}/storedPaymentOptions?partnerReference={partnerReference}&programCode={programCode}&accnoType={accnoType}&localDate={localDate}&localTime={localTime}

Returns the payment options stored for an account.

Request parameters

accno
String Length: 255 Required

Account number.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

transactionTypeCode
String Length: 10

Transaction type. See Transaction Type in the Lookups.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

GET {baseURL}/account/XXX-123456/storedPaymentOptions?partnerReference=1234567890&programCode=PROG&accnoType=00&localDate=2014-03-12&localTime=163835

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=


Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"programCode": "PROG",
"accno": "XXX-123456",
"paymentOptions": [
{
"name": "Mastercard",
"code": "MSTRCRD",
"carrierNumber": "123***789",
"reference": "318306776d144adc94639801499736d5",
"paymentGroup": "Cards",
"paymentGroupCode": "CARDS",
"paymentSubGroup": "Credit Cards",
"paymentSubGroupCode": "CRDTCRD",
"expiryMonth": 10,
"expiryYear": 2014,
"validUntilDate": "2014-10-31",
"validUntilTime": "235959",
"bankCode": "",
"isVerifiable": true,
"statusCode": "VERIFIED",
"isDefault": false,
"billingAddress":
{
"fullName": "John Doe",
"addr1": "Green Street",
"addr2": "",
"city": "City",
"state": "",
"countryName": "Germany",
"countryCode": "DE",
"postCode": "12345"
},
"iconUrl": "http://www.google.com"
},
{
"name": "VISA",
"code": "VISA",
"carrierNumber": "987***321",
"reference": "39f581425f264e94956224331f481b0c",
"paymentGroup": "Cards",
"paymentGroupCode": "CARDS",
"paymentSubGroup": "Credit Cards",
"paymentSubGroupCode": "CRDTCRD",
"expiryMonth": 10,
"expiryYear": 2014,
"validUntilDate": "2014-10-31",
"validUntilTime": "235959","bankCode": "",
"isVerifiable": true,
"statusCode": "VERIFIED",
"isDefault": false,
"billingAddress":
{
"fullName": "John Doe",
"addr1": "Green Street",
"addr2": "",
"city": "City",
"state": "",
"countryName": "Germany",
"countryCode": "DE",
"postCode": "12345"
},
"iconUrl": "http://www.google.com"
}
]
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 Payment

 1.38 Init Authorize

put {baseURL}/payment/initAuthorize

This interface method is used to initialize authorizing a payment to an e-wallet user or merchant account. A call to "Init Authorize" internally performs an "Init Load Account" call, if provided 'accno' is a user account.

Please note that there are two use cases where this method is used, as part of Guest Payment authorizations and Customer Initiated Transactions using an existing stored payment option. The fields which should be used differ and are reflected in the provided samples.

Request parameters

partnerReference
String Length: 64 Required

Partner service call identifier.

programAccno
String Length: 255 Required

Program account number.

accno
String Length: 255

User or merchant account number.

accnoType
String Length: 2

Account number type. See Account Number Type in the Lookups. Required only if 'accno' is specified.

storedPaymentOptionReference
String Length: 36

Stored payment option unique reference. This value can be supplied, if 'paymentOptionCode' is not provided.

paymentOptionCode
String Length: 10

Payment option code.

presentationAmount
Decimal Length: 18,2 Required

The amount which is authorized for payment to the account.

presentationCurrCode
String Length: 3 Required

The 3-letter currency code associated with the transaction.

presentationUsage
String Length: 127 Required

Information relevant to the payment.

useDifferentBillingAddress
Boolean Required

Defines whether the stored address or a custom billing address is used.

Please note that inline with requirements introduced by Strong Customer Authentication, Guest Payment integrations require that real customer address information (with the exception of "customerFullName") be provided i.e. "useDifferentBillingAddress" must be set to true, which makes the following address parameters mandatory:

    - customerFullName

    - emailAddress

    - addr1

    - houseNumber (if not included in addr1)

    - city

    - postCode

    - countryCode

Please contact customer support where providing accurate data may not be possible in production, as this may result in transactions being rejected.

If false, in the case of CIT the address of the account owner is used; the account owner is determined by the storedPaymentOptionReference.

customerFullName
String Length: 201

Customer full name consisting of the first name and last name.

emailAddress
String

Email address.

addr1
String Length: 60

Address line 1.

addr2
String Length: 60

Address line 2.

addr3
String Length: 60

Address line 3.

houseNumber
String Length: 10

House number.

city
String Length: 50

City name.

state
String Length: 50

State name.

countryCode
String Length: 3

Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

postCode
String Length: 10

Postal code.

phone
String Length: 30

Phone number.

custom1
String Length: 255

For external party usage.

custom2
String Length: 255

For external party usage.

custom3
String Length: 255

For external party usage.

externalChannelReference
String Length: 100

External payment provider channel.

mandateReference
String Length: 35

Mandate reference.

mandateSignedDate
YYYY-MM-DD Length: 10

Mandate signing date.

mandateSignedTime
HHMMSS Length: 6

mandateSignedTime

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample for CIT

Path:

PUT {baseURL}/payment/initAuthorize

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
"partnerReference": "1234567890",
"programAccno": "123456",
"accno": "XXX-123456",
"accnoType": "00",
"storedPaymentOptionReference": "8ac7a49f66aaa1f50166be603cf15385",
"paymentOptionCode": "MSTRCRD",
"presentationAmount": 100,
"presentationCurrCode": "EUR",
"presentationUsage": "Deposit: 100 EUR",
"useDifferentBillingAddress": false,
"custom1": "Custom information 1",
"criteria": [
    {
        "name": "affiliate",
        "value": "ExternalShopXY"
    },
    {
        "name": "age",
        "value": "30-40"
    }
],
"localDate": "2014-03-12",
"localTime": "163835"
}

Request sample for Guest Payment

Path:

PUT {Base URL}/payment/initAuthorize

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: H4sIAAAAAAA{partial omission for brevity}EAN2bJ/6l2XX+A5kJqdP+MwAA

{
"partnerReference": "1234567890",
"programAccno": "123456",
"accno": "XXX-123456",
"accnoType": "00",
"paymentOptionCode": "MSTRCRD",
"presentationAmount": 100,
"presentationCurrCode": "EUR",
"presentationUsage": "Deposit: 100 EUR",
"useDifferentBillingAddress": true,
"customerFullName": "Jacob Smith",
"emailAddress": "user@example.com",
"addr1": "Anystreet",
"houseNumber": "321",
"city": "Anycity",
"countryCode": "DE",
"postCode": "12345",
"custom1": "Custom information 1",
"criteria": [
    {
        "name": "affiliate",
        "value": "ExternalShopXY"
    },
    {
        "name": "age",
        "value": "30-40"
    }
],
"localDate": "2014-03-12",
"localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

storedPaymentOptionReference
String Length: 36

Stored payment option unique reference. This value can be supplied, if 'paymentOptionCode' is not provided.

uniqueReference
String Length: 36

This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.

authorizationToken
String Length: 8192

Unique authorization token assigned by an external payment provider.

paymentOptionCode
String Length: 10

Payment option code.

presentationAmount
Decimal Length: 18,2

The amount which is authorized for payment to the account.

presentationCurrCode
String Length: 3

The 3-letter currency code associated with the transaction.

presentationUsage
String Length: 255

Information relevant to the payment.

custom1
String Length: 255

For external party usage.

custom2
String Length: 255

For external party usage.

custom3
String Length: 255

For external party usage.

statusCode
String Length: 10

Status code of the account. See Account Status Codes in the Lookups.

statusReason
String Length: 255

Reason for a status code.

paymentProviderResponse
Object

Complete payment provider response.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample for CIT

Status Code:

201 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"programAccno": "123456",
"accno": "XXX-123456",
"storedPaymentOptionReference": "8ac7a49f66aaa1f50166be603cf15385",
"uniqueReference": "d633d423651c4cc4bb04b6be69a13ecd",
"loadAccountReference": "621b66dd7a10480487e09ddf290ae931",
"authorizationToken": "0C64A8CAD371F2A1177A9B1B2F505B13.sbg-vm-fe02",
"paymentOptionCode": "MSTRCRD",
"presentationAmount": 100,
"presentationCurrCode": "EUR",
"presentationUsage": "Deposit: 100 EUR",
"custom1": "Custom information 1",
"custom2": "",
"custom3": "",
"statusCode": "RECEIVED",
"statusReason": "",
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

Response sample for Guest Payment

Status Code:

201 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"programAccno": "123456",
"accno": "XXX-123456",
"uniqueReference": "d633d423651c4cc4bb04b6be69a13ecd",
"loadAccountReference": "621b66dd7a10480487e09ddf290ae931",
"authorizationToken": "0C64A8CAD371F2A1177A9B1B2F505B13.sbg-vm-fe02",
"paymentOptionCode": "MSTRCRD",
"presentationAmount": 100,
"presentationCurrCode": "EUR",
"presentationUsage": "Deposit: 100 EUR",
"custom1": "Custom information 1",
"custom2": "",
"custom3": "",
"statusCode": "RECEIVED",
"statusReason": "",
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.39 Complete Authorize

post {baseURL}/payment/{uniqueReference}/completeAuthorize

This interface method is used to complete a previously initiated authorization.

Request parameters

uniqueReference
String Length: 36 Required

This is the uniqueReference that was assigned to initializing of an external authorization. It is received as part of "Init Authorize" response from KontoCloud.

partnerReference
String Length: 64 Required

Partner service call identifier.

authorizationToken
String Length: 8192 Required

Unique authorization token assigned by an external payment provider.

externalChannelReference
String Length: 100

External payment provider channel.

useDifferentBillingAddress
Boolean

Defines whether the stored address or a custom billing address is used.
If true, the fields 'customerFullName', 'addr1', 'city', 'countryCode', 'postCode' are required.
If false, the account owner address is used.
If the field is not provided, false value is used.

customerFullName
String Length: 201

Customer full name consisting of the first name and last name.

addr1
String Length: 60

Address line 1.

addr2
String Length: 60

Address line 2.

addr3
String Length: 60

Address line 3.

houseNumber
String Length: 10

House number.

city
String Length: 50

City name.

countryCode
String Length: 3

Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

postCode
String Length: 10

Postal code.

phone
String Length: 30

Phone number.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

POST {baseURL}/payment/{uniqueReference}/completeAuthorize

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
   "partnerReference": "1234567890",
   "authorizationToken": "0C64A8CAD371F2A1177A9B1B2F505B13.sbg-vm-fe02",
   "localDate": "2014-03-12",
   "localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

initiatorAccno
String Length: 255

Initiator account number.

accno
String Length: 255

Account number.

uniqueReference
String Length: 36

This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.

storedPaymentOptionReference
String Length: 36

Stored payment option reference.

initiationCountryCode
String Length: 2

Payment Option issuer country ISO2 code.

initiationCountryCode3
String Length: 3

Payment Option issuer country ISO3 code.

processedAmount
Decimal Length: 18,2

The amount returned by the acquirer after processing.

processedCurrCode
String Length: 3

The 3-letter currency code associated with the processed amount.

statusCode
String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason
String Length: 255

Reason for a status code.

paymentProviderResponse
Object

Complete payment provider response:

- Array for "PayU" payment option;

- Object for all other payment options.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
   "partnerReference": "1234567890",
   "initiatorAccno": "98765",
   "accno": "XXX-123456",
   "uniqueReference": "d633d423651c4cc4bb04b6be69a13ecd",
   "storedPaymentOptionReference": "7dc5eb4673744da99859f65be192c04c",
   "initiationCountryCode": "ES",
   "initiationCountryCode3": "ESP",
   "processedAmount": 92,
   "processedCurrCode": "EUR",
   "statusCode": "AUTHORIZED",
   "statusReason": "Request Successfully Processed.",
   "localDate": "2014-03-12",
   "localTime": "163835",
   "sysDate": "2014-03-12",
   "sysTime": "153837",
   "responseCode": "0000",
   "responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.27 Authorize

put {baseURL}/payment/authorize

This interface method is used to authorize a payment to an e-wallet or merchant account.
A call to "Authorize" internally performs an "Init Load Account" call, if an 'accno' parameter is specified.

Request parameters

partnerReference
String Length: 64 Required

Partner service call identifier.

programAccno
String Length: 255 Required

Program account number.

accno
String Length: 255

User or merchant account number.

accnoType
String Length: 2

Account number type. See Account Number Type in the Lookups. Required only if 'accno' is specified.

storedPaymentOptionReference
String Length: 36 Required

Stored payment option reference.

invoiceReference
String Length: 255

Payment invoice reference.

channelProductReference
String Length: 255

Payment channel product reference.

presentationAmount
Decimal Length: 18,2 Required

The amount which is authorized for payment to the account.

presentationCurrCode
String Length: 3 Required

The 3-letter currency code associated with the transaction.

presentationUsage
String Length: 127 Required

Information relevant to the payment.

useDifferentBillingAddress
Boolean Required

Defines whether the stored address or a custom billing address is used.

If true, the fields 'customerFullName', 'addr1', 'city', 'countryCode', 'postCode', 'emailAddress' are required.

If false, the billing address of the stored payment option is used or if a stored payment option is not provided, the account owner address.

customerFullName
String Length: 201

Customer full name consisting of the first name and last name.

addr1
String Length: 60

Address line 1.

addr2
String Length: 60

Address line 2.

addr3
String Length: 60

Address line 3.

houseNumber
String Length: 10

House number.

city
String Length: 50

City name.

state
String Length: 50

State name.

countryCode
String Length: 3

Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

postCode
String Length: 10

Postal code.

phone
String Length: 30

Phone number.

emailAddress
String Length: 255

Email address.

custom1
String Length: 255

For external party usage.

custom2
String Length: 255

For external party usage.

custom3
String Length: 255

For external party usage.

oneTimePassword
Number Length: 8

One Time Password used for confirmation during Two Factor Authentication.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:

PUT {baseURL}/payment/authorize

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
"partnerReference": "1234567890",
"programAccno": "123456",
"accno": "XXX-123456",
"accnoType": "00",
"storedPaymentOptionReference": "8ac7a49f66aaa1f50166be603cf15385", 
"invoiceReference": "Invoice-20140410-1", 
"channelProductReference": "Product-1",
"presentationAmount": 100,
"presentationCurrCode": "EUR",
"presentationUsage": "Deposit: 100 EUR", 
"useDifferentBillingAddress": true, 
"customerFullName": "Firstname Lastname",
"emailAddress": "user@example.com",
"addr1": "Address 1",
"city": "City",
"countryCode": "DE",
"postCode": "12345",
"custom1": "Custom information 1",
"criteria": [
 {
   "name": "affiliate",
   "value": "ExternalShopXY"
 },
 {
   "name": "age",
   "value": "30-40"
 }
],
"localDate": "2014-03-12",
"localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programAccno
String Length: 255

Program account number.

accno
String Length: 255

Account number.

uniqueReference
String Length: 36

This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.

storedPaymentOptionReference
String Length: 36

Stored payment option reference.

invoiceReference
String Length: 255

Payment invoice reference.

channelProductReference
String Length: 255

Payment channel product reference.

presentationAmount
Decimal Length: 18,2

The amount which is authorized for payment to the account.

presentationCurrCode
String Length: 3

The 3-letter currency code associated with the transaction.

presentationUsage
String Length: 127

Information relevant to the payment.

processedAmount
Decimal Length: 18,2

The amount returned by the acquirer after processing.

processedCurrCode
String Length: 3

The 3-letter currency code associated with the processed amount.

custom1
String Length: 255

For external party usage.

custom2
String Length: 255

For external party usage.

custom3
String Length: 255

For external party usage.

statusCode
String Length: 10

Status code of the account. See Account Status Codes in the Lookups.

statusReason
String Length: 255

Reason for a status code.

paymentProviderResponse
Object

Complete payment provider response.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

201 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"programAccno": "123456",
"accno": "XXX-123456",
"uniqueReference": "d633d423651c4cc4bb04b6be69a13ecd",
"loadAccountReference": "621b66dd7a10480487e09ddf290ae931",
"storedPaymentOptionReference": "",
"invoiceReference": "Invoice-20140410-1",
"channelProductReference": "Product-1",
"presentationAmount": 100,
"presentationCurrCode": "EUR",
"presentationUsage": "Deposit: 100 EUR",
"processedAmount": 100,
"processedCurrCode": "EUR",
"custom1": "Custom information 1",
"custom2": "",
"custom3": "",
"statusCode": "AUTHORIZED",
"statusReason": "",
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.29 Capture

post {baseURL}/payment/{uniqueReference}/capture

This interface method is used to capture a payment to an e-wallet account previously authorized via a call to "Init Authorize"+"Complete Authorize" or "Authorize".
A call to "Capture" internally performs a "Load Account" call, if an 'accno' parameter is specified during authorization.

Request parameters

uniqueReference
String Length: 36 Required

This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.

partnerReference
String Length: 64 Required

Partner service call identifier.

modifiedUsage
String Length: 127

Information relevant to the payment.

custom1
String Length: 255

For external party usage.

custom2
String Length: 255

For external party usage.

custom3
String Length: 255

For external party usage.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

POST {baseURL}/payment/d633d423651c4cc4bb04b6be69a13ecd/capture

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
"partnerReference": "1234567890",
"modifiedAmount": 92,
"modifiedAmountCurrCode": "EUR",
"custom1": "Custom information 1",
"localDate": "2014-03-12",
"localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

initiatorAccno
String Length: 255

Initiator account number.

accno
String Length: 255

Account number.

uniqueReference
String Length: 36

Unique transaction reference assigned by KontoCloud upon authorization.

modifiedAmount
Decimal Length: 18,2

The amount which is captured for payment to the account.

modifiedAmountCurrCode
String Length: 3

The 3-letter currency code associated with the transaction.

processedAmount
Decimal Length: 18,2

The amount returned by the acquirer after processing.

processedCurrCode
String Length: 3

The 3-letter currency code associated with the processed amount.

custom1
String Length: 255

For external party usage.

custom2
String Length: 255

For external party usage.

custom3
String Length: 255

For external party usage.

statusCode
String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason
String Length: 255

Reason for a status code.

paymentProviderResponse
Object

Complete payment provider response:

- Array for "PayU" payment option;

- Object for all other payment options.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

201 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"initiatorAccno": "98765",
"accno": "XXX-123456",
"uniqueReference": "d633d423651c4cc4bb04b6be69a13ecd",
"modifiedAmount": 92,
"modifiedAmountCurrCode": "EUR",
"processedAmount": 92,
"processedCurrCode": "EUR",
"custom1": "Custom information 1",
"custom2": "",
"custom3": "",
"statusCode": "CAPTURED",
"statusReason": "",
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.75 Refund

post {baseURL}/payment/{uniqueReference}/refund

This interface method is used to refund a previously captured external authorization.

Request parameters

partnerReference
String Length: 64 Required

Partner service call identifier.

uniqueReference
String Length: 36 Required

This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.

refundAmount
Decimal Length: 18,2

Amount being refunded. It cannot exceed the amount of the refunded transaction. If the value is not provided the full refund is performed.

refundUsage
String Length: 255

Information relevant to the refund.

refundType
String Length: 1

The code defining what type of refund will be performed. Available types of refund listed in "Refund Type" lookup.

refundSourceAccno
String Length: 36

User's or merchant's Account from which the 'refundAmount' will be refunded in case of a partial chain refund. This account must be one of the target accountsofdependent"Payment"or "Load Account".

custom1
String Length: 255

For external party usage.

custom2
String Length: 255

For external party usage.

custom3
String Length: 255

For external party usage.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

POST {baseURL}/payment/d633d423651c4cc4bb04b6be69a13ecd/refund

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
"partnerReference": "1234567890", 
"refundAmount": 9,
"refundUsage": "Payment refund", 
"localDate": "2014-03-12", 
"localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

initiatorAccno
String Length: 255

Initiator account number.

accno
String Length: 255

Account number.

uniqueReference
String Length: 36

Unique transaction reference assigned by KontoCloud upon authorization.

refundAmount
Decimal Length: 18,2

Amount being refunded. It cannot exceed the amount of the refunded transaction. If the value is not provided the full refund is performed.

refundCurrCode
String Length: 3

Currency code of the amount to be refunded.

processedAmount
Decimal Length: 18,2

The amount returned by the acquirer after processing.

processedCurrCode
String Length: 3

The 3-letter currency code associated with the processed amount.

custom1
String Length: 255

For external party usage.

custom2
String Length: 255

For external party usage.

custom3
String Length: 255

For external party usage.

statusCode
String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason
String Length: 255

Reason for a status code.

paymentProviderResponse
Object

Complete payment provider response:

- Array for "PayU" payment option;

- Object for all other payment options.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

201 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"initiatorAccno": "98765",
"accno": ["XXX-123456", "XXX-123457"], 
"uniqueReference": "d633d423651c4cc4bb04b6be69a13ecd", 
"refundAmount": 9,
"refundCurrCode": "EUR",
"processedAmount": 9,
"processedCurrCode": "EUR",
"custom1": "Custom information 1",
"custom2": "",
"custom3": "",
"statusCode": "CAPTURED",
"statusReason": "",
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.30 Cancel

post {baseURL}/payment/{uniqueReference}/cancel

This interface method is used to cancel a previously authorized payment to an e-wallet account.

Request parameters

uniqueReference
String Length: 36 Required

This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.

partnerReference
String Length: 64 Required

Partner service call identifier.

custom1
String Length: 255

For external party usage.

custom2
String Length: 255

For external party usage.

custom3
String Length: 255

For external party usage.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

POST {baseURL}/payment/d633d423651c4cc4bb04b6be69a13ecd/cancel

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
   "partnerReference": "1234567890",
   "custom1": "Custom information 1",
   "localDate": "2014-03-12",
   "localTime": "163835"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

initiatorAccno
String Length: 255

Initiator account number.

accno
String Length: 255

Account number.

uniqueReference
String Length: 36

Unique transaction reference assigned by KontoCloud upon authorization.

custom1
String Length: 255

For external party usage.

custom2
String Length: 255

For external party usage.

custom3
String Length: 255

For external party usage.

statusCode
String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason
String Length: 255

Reason for a status code.

paymentProviderResponse
Object

Complete payment provider response:

- Array for "PayU" payment option;

- Object for all other payment options.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

201 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US

{
   "partnerReference": "1234567890",
   "initiatorAccno": "98765",
   "accno": "XXX-123456",
   "uniqueReference": "d633d423651c4cc4bb04b6be69a13ecd",
   "custom1": "Custom information 1",
   "custom2": "",
   "custom3": "",
   "statusCode": "CANCELLED",
   "statusReason": "",
   "localDate": "2014-03-12",
   "localTime": "163835",
   "sysDate": "2014-03-12",
   "sysTime": "153837",
   "responseCode": "0000",
   "responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.41 Get Payment Status

get {baseURL}/payment/{uniqueReference}/status?&partnerReference={partnerReference}&localDate={localDate}&localTime={localTime}

This interface method is used to get a status of a transaction.

Request parameters

uniqueReference
String Length: 36 Required

Unique transaction reference assigned by the KontoCloud.

partnerReference
String Length: 64 Required

Partner service call identifier.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

GET {baseURL}/payment/1234567890/status?partnerReference=1234567890&localDate=2014-03-12&localTime=163835

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=


Response parameters

uniqueReference
String Length: 36

Unique transaction reference assigned by the KontoCloud. Same as in request.

partnerReference
String Length: 64

Partner service call identifier.

initiatorAccno
String Length: 255

Initiator account number.

initiatorName
String Length: 201

Name of the instance which initiated the payment.

accno
String Length: 255

Account number.

presentationAmount
Decimal Length: 18,2

Amount with which the payment was initiated or captured.

presentationCurrCode
String Length: 3

The 3-letter currency code associated with the transaction.

presentationUsage
String Length: 127

Information relevant to the payment.

customerFullName
String Length: 201

Customer full name consisting of the first name and last name.

addr1
String Length: 60

Address line 1.

addr2
String Length: 60

Address line 2.

addr3
String Length: 60

Address line 3.

houseNumber
String Length: 10

House number.

city
String Length: 50

City name.

state
String Length: 50

State name.

country
String Length: 100

Country name.

countryCode
String Length: 2

Country ISO 3166-1 alpha-2 code.

countryCode3
String Length: 3

Country ISO 3166-1 alpha-3 code.

postCode
String Length: 10

Postal code.

statusCode
String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason
String Length: 255

Reason for a status code.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
   "uniqueReference": "1234567890",
   "partnerReference": "1234567890",
   "initiatorAccno": "123456",
   "initiatorName": "C4U-Malta Limited",
   "accno": "XXX-123456",
   "presentationAmount": 100.00,
   "presentationCurrCode": "EUR",
   "presentationUsage": "Buying a vodafone monthly subscription.",
   "custom1": "Custom information 1",
   "custom2": "",
   "custom3": "",
   "customerFullName": "Max Mustermann",
   "addr1": "Platz der Republik 1",
   "addr2": "",
   "addr3": "",
   "houseNumber": "",
   "city": "Berlin",
   "state": "",
   "stateCode": null,
   "country": "Germany",
   "postCode": "11011",
   "statusCode": "CAPTURED",
   "statusReason": "",
   "localDate": "2014-03-12",
   "localTime": "163835",
   "sysDate": "2014-03-12",
   "sysTime": "153837",
   "responseCode": "0000",
   "responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 TPP

 Card Based Payment Instruments

 1.17 Find User Account

get {baseURL}/account/find?partnerReference={partnerReference}&programCode={programCode}&userId={userId}&localDate={localDate}&localTime={localTime}

A request to find an account number based on the user identifier.

Request parameters

accno
String Length: 255 Required

E-wallet user account number.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

userId
String Length: 255 Required

User identifier: email, login, secondary email address, or uuid.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:

GET {baseURL}/account/find?partnerReference=50F45B51E07D4CE1ABB1676E3DF5BB44&programCode=COMPANY123&userId=user@example.com&localDate=2016-01-31&localTime=131415

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=


Response parameters

partnerReference
String Length: 64

partnerReference same as in the Request.

programCode
String Length: 10

Program code

accno
String Length: 255

Account number.

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
 "accno": "1000104149",
 "partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
 "programCode": "COMPANY123",
 "localDate": "2016-01-31",
 "localTime": "131415",
 "sysDate": "2016-01-31",
 "sysTime": "121420",
 "responseCode": "0000",
 "responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.146 Check Available Payment Amount

get {baseURL}/account/{accno}/checkAvailablePaymentAmount?partnerReference={partnerReference}&programCode={programCode}&accnoType={accnoType}&amount={amount}&currCode={currCode}&localDate={localDate}&localTime={localTime}

A request to check the availability of the amount for the payment from the specified E-Wallet account.

Request parameters

accno
String Length: 255 Required

E-wallet user account number.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

amount
Decimal Length: 18.2 Required

The amount to be checked for availability to payment from the account.

currCode
String Length: 3 Required

The 3-letter currency code of the checked amount.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:

GET {baseURL}/account/XXX-123456/checkAvailablePaymentAmount?partnerReference=50F45B51E07D4CE1ABB1676E3DF5BB44&programCode=COMPANY123&accnoType=00&amount=100&currCode=EUR&localDate=2019-12-02&localTime=131415

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=


Response parameters

The response contains the following possible text values without quotes:

  • "yes" –  if the amount is available;
  • "no" – if the amount is not available.

Response Sample (Successful)

Status Code:

200 (OK)

Header:

Content-Type: text/plain
Accept-Language: en-US

yes

Response Sample (Fail Case)

Status Code:

400 (Bad Request)

Header:

Content-Type: application/json
Accept-Language: en-US

{
  "partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
  "sysDate": "2000-12-31",
  "sysTime": "235959",
  "responseCode": "0008",
  "responseDescription": "Invalid account number supplied: 1234567890.",
  "additionalInformation": {
    "requestId": "aff2728481a181dc36daedc14055b516"
  }
}

 Account Information

 1.7 Account Enquiry

get {baseURL}/account/{accno}/enquiry?partnerReference={partnerReference}&programCode={programCode}&accnoType={accnoType}&startDate={startDate}&endDate={endDate}&top={top}&skip={skip}&localDate={localDate}&localTime={localTime}

Returns the transactions performed by the account holder with an option additionally to receive pending transactions in the result.

Request parameters

accno
String Length: 255 Required

E-wallet user account number.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

startDate
YYYY-MM-DD Length: 10

Start date for the enquiry. Only account entries on this day and beyond will be returned. If not specified, the search will return results from the first account entry.

startTime
HHMMSS Length: 6

Start time for the enquiry. If 'startTime' is provided, 'startDate' becomes required. If not specified "000000" is used as start time.

endDate
YYYY-MM-DD Length: 10

End date for the enquiry. Only account entries on this day and before will be returned. If not specified, the search will return results up to the last account entry.

endTime
HHMMSS Length: 6

End time for the enquiry. If 'endTime' is provided, 'endDate' becomes required. If not specified "235959" is used as end time.

top
Number Length: 4

Number of account entries to return. Used for requesting a specific number of the most recent account entries.

skip
Number Length: 4

Number of account entries to skip in the result set. Used for skipping a specific number of the most recent account entries.

includeNeutral
Boolean

Defines if the Neutral Account Entries should be used. 'False' – if not specified. if 'True' – both Account Entries and Neutral Account Entries should be returned.

sortDirection
String Length: 4

Defines the direction of sorting by booking date. See Sort Direction in the Lookups. If not specified, "ASC" is used.

includePendingTransactions
Boolean

A flag defining whether pending transactions should be included in the response. "False" is used if it is not provided.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:

GET {baseURL}/account/XXX-123456/enquiry?partnerReference=1234567890&programCode=PROG &accnoType=00&startDate=2014-01-01&endDate=2014-01-31&top=100& includePendingTransactions=false&skip=100 &localDate=2014-03-12&localTime=163835

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=


Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programAccno
String Length: 255

Program account number.

accno
String Length: 255

E-wallet user account number or merchant account number.

count
Number Length: 6

Total pending transactions count using the 'startDate' and 'endDate' filters.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
    "partnerReference": "1234567890",
    "programCode": "PROG",
    "accno": "XXX-123456",
    "count": 2,
    "entries": [
        {
            "isPending": false,
            "bookingDate": "2014-01-15",
            "bookingTime": "221133",
            "valueDate": "2014-01-16",
            "valueTime": "102030",
            "sourceAmount": 5.00,
            "sourceCurrCode": "EUR",
            "amount": 5.00,
            "currCode": "EUR",
            "exchangeRate": 1.00,
            "balance": 45.00,
            "entryIndicator": "DBIT",
            "description": "XXXXXXXXXXXXXXXXXX",
            "name": "John Doe",
            "entryType": "Payment",
            "reference": "3150a55a754c443d86398dfab1be7afa",
            "statusCode": "SETTLED",
            "paymentOptionCode": "MSTRCRD"
        },
        {
            "isPending": false,
            "bookingDate": "2014-01-15",
            "bookingTime": "221133",
            "valueDate": "2014-01-16",
            "valueTime": "102030",
            "sourceAmount": 5.00,
            "sourceCurrCode": "EUR",
            "amount": 5.00,
            "currCode": "EUR",
            "exchangeRate": 1.00,
            "balance": 40.00,
            "entryIndicator": "DBIT",
            "description": "XXXXXXXXXXXXXXXXXX",
            "name": "John Doe",
            "entryType": "Payment",
            "reference": "f7e4fb07f0364d1288d535274bc02da6",
            "statusCode": "SETTLED",
            "paymentOptionCode": "MSTRCRD"
        }
    ],
    "localDate": "2014-03-12",
    "localTime": "163835",
    "sysDate": "2014-03-12",
    "sysTime": "153837",
    "responseCode": "0000",
    "responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.8 Balance Enquiry

get {baseURL}/account/{accno}/balance?partnerReference={partnerReference}&programCode={programCode}&accnoType={accnoType}&localDate={localDate}&localTime={localTime}

A request for a balance enquiry returns the current available balance on the account.

Request parameters

accno
String Length: 255 Required

E-wallet user account number.

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:

GET {baseURL}/account/1000104149/balance?partnerReference=50F45B51E07D4CE1ABB1676E3DF5BB44&programCode=COMPANY123&accnoType=01&localDate=2016-01-31&localTime=131415

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=


Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programAccno
String Length: 255

Program account number.

accno
String Length: 255

E-wallet user account number or merchant account number.

psBal
Decimal Length: 18

Previous day closing balance.

avlBal
Decimal Length: 18

Current available balance (booked balance – blocked Amount).

bkBal
Decimal Length: 18

Booked balance: Booked balance is the total deposit on a particular day plus previous closing balance.

blkAmt
Decimal Length: 18

Total Blocked amount: Blocked amount is the authorized amount until it is captured or cancelled.

pooledAmt
Decimal Length: 18,2

Total Pooled amount: Pooled amount is authorized only on the wallet account, but not on the external payment option.

currCode
String Length: 3

Currency code of the balance returned.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
 "accno": "1000104149",
 "psBal": 0,
 "avlBal": 12.34,
 "bkBal": 12.34,
 "blkAmt": 0,
 "pooledAmt": 0,
 "currCode": "EUR",
 "partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
 "programCode": "COMPANY123",
 "localDate": "2016-01-31",
 "localTime": "000000",
 "sysDate": "2016-06-15",
 "sysTime": "131950",
 "responseCode": "0000",
 "responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 Payment Initiation

 1.42 KC-Authorize

put {baseURL}/payment/kc-authorize

This interface method is used to authorize a payment from an e-wallet account to a merchant.

Request parameters

partnerReference
String Length: 64 Required

Partner service call identifier.

depositReference
String Length: 36

uniqueReference of a transaction that was assigned to a capture external authorization request.

accno
String Length: 255 Required

E-wallet user account number.

merchantAccno
String Length: 255

Merchant account number.

programCode
String Length: 10 Required

Program code

programAccno
String Length: 255 Required

Program account number.

merchantProgramCode
String Length: 10

Destination program code. Mandatory if merchantAccno is specified as External Account Reference.

accnoType
String Length: 2 Required

Account number type. See Account Number Type in the Lookups.

paymentAmount
Decimal Length: 18,2 Required

The amount of payment .

paymentCurrCode
String Length: 3 Required

The 3-letter currency code associated with the transaction.

paymentUsage
String Length: 255 Required

Description of a performed payment.

useDifferentBillingAddress
Boolean Required

Defines whether the stored address or a custom billing address is used. If true, the fields 'customerFullName', 'addr1', 'city', 'countryCode', 'postCode' are required. If false, the account owner address is used.

customerFullName
String Length: 201

Customer full name consisting of the first name and last name.

countryCode
String Length: 3 Required

Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

addr1
String Length: 60

Customer's address line 1.

addr2
String Length: 60

Customer's address line 2.

addr3
String Length: 60

Customer's address line 3.

houseNumber
String Length: 10

Customer's house number.

city
String Length: 50

Customer's city name.

state
String Length: 50

State name.

postCode
String Length: 10

Customer's postal code.

phone
String Length: 30

Phone number.

emailAddress
String

Email address.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:

PUT {baseURL}/payment/kc-authorize

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
 "partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
 "depositReference": "da530d6055b14364991e79aec1a36a74",
 "accno": "123000045",
 "merchantAccno": "000000005",
 "programAccno": "000000001",
 "accnoType": "01",
 "paymentAmount": 100.00,
 "paymentCurrCode": "EUR",
 "paymentUsage": "One off top up.",
 "useDifferentBillingAddress": false,
 "localDate": "2014-03-12",
 "localTime": "131415"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

uniqueReference
String Length: 36

Unique reference assigned by KontoCloud to the credit transaction.

accno
String Length: 255

E-wallet user account number or merchant account number.

merchantAccno
String Length: 255

Seller merchant account number.

programAccno
String Length: 255

Program account number.

paymentAmount
Decimal Length: 18,2

The amount of payment .

paymentCurrCode
String Length: 3

The 3-letter currency code associated with the transaction.

paymentUsage
String Length: 255

Description of a performed payment.

fxRate
Decimal Length: 18,2

Currency conversion rate between payment currency and merchant account currency used in the transaction.

statusCode
String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason
String Length: 255

Reason for a status code.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "1234567890",
"uniqueReference": "d633d423651c4cc4bb04b6be69a13ecd",
"accno": "123000045",
"merchantAccno": "000000005",
"programAccno": "000000001",
"paymentAmount": 100.00,
"paymentCurrCode": "EUR",
"paymentUsage": "One off top up.",
"fxRate": 1.00,
"statusCode": "AUTHORIZED",
"statusReason": "",
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.121 KC-Debit Account

put {baseURL}/payment/kc-debitAccount

This interface method is used to initiate a payment from an e-wallet account to a merchant account.

Request parameters

partnerReference
String Length: 64 Required

Partner service call identifier.

depositReference
String Length: 36

uniqueReference of a transaction that was assigned to a capture external authorization request.

accno
String Length: 255 Required

E-wallet user account number or merchant account number.

programAccno
String Length: 255 Required

Initiating program account number.

merchantAccno
String Length: 255 Required

Destination merchant account number.

merchantProgramCode
String Length: 10

Destination program code. Mandatory if merchantAccno is specified as External Account Reference.

accnoType
String Length: 2 Required

Account number and merchant account number type. Refer to Account Number Type in the Lookups.

paymentAmount
Decimal Length: 18,2 Required

The amount of payment from eWallet account to merchant account.

paymentCurrCode
String Length: 3 Required

The 3-letter currency code associated with the transaction.

paymentUsage
String Length: 255 Required

Description of a performed payment.

useDifferentBillingAddress
Boolean Required

Defines whether the stored address or a custom billing address is used. If true, the fields 'customerFullName', 'addr1', 'city', 'countryCode', 'postCode' are required. If false, the account owner address is used.

customerFullName
String Length: 201

Customer full name consisting of the first name and last name.

countryCode
String Length: 3 Required

Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

addr1
String Length: 60

Customer's address line 1.

addr2
String Length: 60

Customer's address line 2.

addr3
String Length: 60

Customer's address line 3.

houseNumber
String Length: 10

Customer's house number.

city
String Length: 50

Customer's city name.

state
String Length: 50

State name.

postCode
String Length: 10

Customer's postal code.

emailAddress
String

Email address.

oneTimePassword
String Length: 8

One Time Password used for confirmation during Two Factor Authentication.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:

PUT {baseURL}/payment/kc-debitAccount

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
 "partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
 "depositReference": "da530d6055b14364991e79aec1a36a74",
 "accno": "123000045",
 "programAccno": "000000001",
 "merchantAccno": "000000005",
 "merchantProgramCode": "COMPANY123",
 "accnoType": "01",
 "paymentAmount": 100.00,
 "paymentCurrCode": "EUR",
 "paymentUsage": "One off top up.",
 "useDifferentBillingAddress": false,
 "localDate": "2014-03-12",
 "localTime": "131415"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

uniqueReference
String Length: 36

Unique reference assigned by KontoCloud to the credit transaction.

accno
String Length: 255

E-wallet user account number or merchant account number.

programAccno
String Length: 255

Program account number.

merchantAccno
String Length: 255

Seller merchant account number.

merchantProgramCode
String Length: 10

Destination program code.

paymentAmount
Decimal Length: 18,2

The amount of payment .

paymentCurrCode
String Length: 3

The 3-letter currency code associated with the transaction.

paymentUsage
String Length: 255

Description of a performed payment.

fxRate
Decimal Length: 18

Currency conversion rate used.

statusCode
String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason
String Length: 255

Reason for a status code.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"uniqueReference": "653d5e9f63e24be495f3aecdcc4e9825",
"partnerReference": "1234567890",
"accno": "123000045",
"programAccno": "000000001",
"merchantAccno": "000000005",
"merchantProgramCode": "COMPANY123",
"paymentAmount": 100.00,
"paymentCurrCode": "EUR",
"paymentUsage": "One off top up.",
"fxRate": 1.00,
"statusCode": "CAPTURED",
"statusReason": "",
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 1.14 KC-Capture

post {baseURL}/payment/{uniqueReference}/kc-capture

This interface method is used to capture a previously authorized payment from an e-wallet account to a merchant.

Request parameters

uniqueReference
String Length: 36 Required

This is the uniqueReference that was assigned to an authorization. It is received as part of "KC-Authorize" response from KontoCloud.

partnerReference
String Length: 64 Required

Partner service call identifier.

modifiedAmount
Decimal Length: 18,2 Required

The amount of payment from the e-Wallet account to the merchant account.

modifiedAmountCurrCode
String Length: 3 Required

The 3-letter currency code associated with the transaction.

modifiedUsage
String Length: 127

Information relevant to the payment.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:

POST {baseURL}/payment/1234567890/kc-capture

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
  "partnerReference": "1234567890",
  "modifiedAmount": 100.00,
  "modifiedAmountCurrCode": "EUR",
  "localDate": "2014-03-12",
  "localTime": "163835"
}

Response parameters

uniqueReference
String Length: 36

A unique reference assigned to the authorization by KontoCloud. Same as in the request.

partnerReference
String Length: 64

Partner service call identifier.

merchantAccno
String Length: 255

Merchant account number.

accno
String Length: 255

Account number.

modifiedAmount
Decimal Length: 18,2

The amount of payment from the e-Wallet account to the merchant account.

modifiedAmountCurrCode
String Length: 3

The 3-letter currency code associated with the transaction.

processedAmount
Decimal Length: 18

The amount the member is paying from their e-Wallet account to the merchant account in the merchant account currency.

fxRate
Decimal Length: 18,2

Currency conversion rate between payment currency and merchant account currency used in the transaction.

statusCode
String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason
String Length: 255

Reason for a status code.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
  "uniqueReference": "1234567890",
  "partnerReference": "1234567890",
  "merchantAccno": "123456",
  "accno": "XXX-123456",
  "modifiedAmount": 90.00,
  "modifiedAmountCurrCode": "EUR",
  "processedAmount": 90.00,
  "processedCurrCode": "EUR",
  "fxRate": 1.00,
  "statusCode": "CAPTURED",
  "statusReason": "",
  "localDate": "2014-03-12",
  "localTime": "163835",
  "sysDate": "2014-03-12",
  "sysTime": "153837",
  "responseCode": "0000",
  "responseDescription": "Successful execution.",
  "additionalInformation": {
    "requestId": "aff2728481a181dc36daedc14055b516"
  }
}

 1.15 KC-Cancel

post {baseURL}/payment/{uniqueReference}/kc-cancel

This interface method is used to cancel a previously authorized payment before it is captured.

Request parameters

uniqueReference
String Length: 36 Required

This is the uniqueReference that was assigned to an authorization. It is received as part of "KC-Authorize" response from KontoCloud.

partnerReference
String Length: 64 Required

Partner service call identifier.

modifiedUsage
String Length: 127

Information relevant to the payment.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:

POST {baseURL}/payment/1234567890/kc-cancel

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
  "partnerReference": "1234567890",
  "modifiedUsage": "Cancelled by the client.",
  "localDate": "2014-03-12",
  "localTime": "163835"
}

Response parameters

uniqueReference
String Length: 36

A unique reference assigned to the authorization by KontoCloud. Same as in the request.

partnerReference
String Length: 64

Partner service call identifier.

merchantAccno
String Length: 255

Merchant account number.

accno
String Length: 255

Account number.

statusCode
String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason
String Length: 255

Reason for a status code.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
  "uniqueReference": "1234567890",
  "partnerReference": "1234567890",
  "merchantAccno": "123456",
  "accno": "XXX-123456",
  "statusCode": "CANCELLED",
  "statusReason": "",
  "localDate": "2014-03-12",
  "localTime": "163835",
  "sysDate": "2014-03-12",
  "sysTime": "153837",
  "responseCode": "0000",
  "responseDescription": "Successful execution.",
  "additionalInformation": {
    "requestId": "aff2728481a181dc36daedc14055b516"
  }
}

 1.16 KC-Refund

post {baseURL}/payment/{uniqueReference}/kc-refund

This interface method is used to refund a previously captured payment.

Request parameters

uniqueReference
String Length: 36 Required

This is the uniqueReference that was assigned to an authorization. It is received as part of "KC-Authorize" response from KontoCloud.

partnerReference
String Length: 64 Required

Partner service call identifier.

refundAmount
Decimal Length: 18,2

Amount being refunded. It cannot exceed the amount of the refunded transaction. If the value is not provided the full refund is performed.

refundUsage
String Length: 255

Information relevant to the refund.

refundType
String Length: 1

The code defining what type of refund will be performed. Available types of refund listed in "Refund Type" lookup.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:

POST {baseURL}/payment/1234567890/kc-refund

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
  "partnerReference": "1234567890",
  "refundType": "0",
  "localDate": "2014-03-12",
  "localTime": "163835"
}

Response parameters

uniqueReference
String Length: 36

A unique reference assigned to the authorization by KontoCloud. Same as in the request.

partnerReference
String Length: 64

Partner service call identifier.

refundSourceAccno
String Length: 255

Refund source account number.

accno
String Length: 255

Account number.

statusCode
String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason
String Length: 255

Reason for a status code.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
  "uniqueReference": "1234567890",
  "partnerReference": "1234567890",
  "refundSourceAccno": "123456",
  "accno": "XXX-123456",
  "statusCode": "CAPTURED",
  "statusReason": "",
  "localDate": "2014-03-12",
  "localTime": "163835",
  "sysDate": "2014-03-12",
  "sysTime": "153837",
  "responseCode": "0000",
  "responseDescription": "Successful execution.",
  "additionalInformation": {
    "requestId": "aff2728481a181dc36daedc14055b516"
  }
}

 Ancillary Services

 Address Validation

 1.105 Perform Address Check

post {baseURL}/compliance/addressCheck

A request to check the validity of an address.

Request parameters

partnerReference
String Length: 64 Required

Partner service call identifier.

programCode
String Length: 10 Required

Program code

street
String Length: 68 Required

Street.

house
String Length: 10

House.

postalCode
String Length: 10

Postal code.

city
String Length: 50

City name.

countryCode
String Length: 3

Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.

localDate
YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime
HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:

POST {baseURL}/compliance/addressCheck

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

{
  "partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
  "programCode": "COMPANY123",
  "street": "Rathausstraße.",
  "house": "8",
  "postalCode": "24960",
  "city": "Glücksburg",
  "line2": null,
  "line3": null,
  "countryCode": "DE",
  "localDate": "2016-01-31",
  "localTime": "131415"
}

Response parameters

partnerReference
String Length: 64

Partner service call identifier.

programCode
String Length: 10

Program code

localDate
YYYY-MM-DD Length: 10

The current date of the caller.

localTime
HHMMSS Length: 6

The current time of the caller.

sysDate
YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime
HHMMSS Length: 6

The current time of the KontoCloud server

responseCode
String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription
String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
"partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
"programCode": "COMPANY123",
"addressCheckData":
{
"archiveId": "4742000025020093",
"decision": "HOUSE_CONFIRMED",
"postalCodeCorrect": true,
"normalizedAddress":
{
"street": "Rathausstr.",
"house": "8",
"houseExtension": "",
"postalCode": "24960",
"city": "Glücksburg (Ostsee)",
"countryCode": "DE"
},
"foundAddress":
{
"street": "Rathausstr.",
"house": "8",
"houseExtension": "",
"postalCode": "24960",
"city": "Glücksburg (Ostsee)",
"countryCode": "DE"
}
},
"localDate": "2014-03-12",
"localTime": "163835",
"sysDate": "2014-03-12",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

 Compliance Check

 1.101 Perform Person Compliance Check

post {baseURL}/compliance/personCheck

A request to check a person's compliance via the compliance system.

Request parameters

partnerReference
String Length: 64 Required

Partner service call identifier.

merchantReference
String Length: 36

Merchant reference to identify the merchant for which the check is being performed.

programCode
String Length: 10 Required

Program code

division
String Length: 100

Division.

customerId
String Length: 255 Required

Customer identifier.

firstName
String Length: 100 Required

First name.

lastName
String Length: 100 Required

Last name.

street
String Length: 68 Required

Street.

house
String Length: 10

House.

postalCode
String Length: 10 Required

Postal code.

city
String Length: 50 Required

City name.

countryCode
Stri