We recommend setting a minimum timeout of 90 seconds, even though API requests are expected to return a response much faster
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.
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.
Although caching of the authentication token can improve performance it is important to check for potential caching related rejections of requests. This may result from expired tokens being served from your cache for requests, particularly during initial sprints focused on integration.
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
Caller user identifier in the KontoCloud system.
password
Caller password in the KontoCloud system.
localDate
The current date of the caller.
localTime
The current time of the caller.
Response parameters
token
Security token.
validUntil
Token validity period in UTC.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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"
}
}
put {baseURL}/account
This method is used to create an e-wallet account.
Request parameters
externalAccountReference
Account reference to identify the account in the future by the partners in their system.
partnerReference
Partner service call identifier.
programCode
Program code
accountApplicationFlowCode
Code of the account application flow. A program default flow of Type "E-Wallet User" is used if a value is not provided.
currCode
Currency code of the account to be opened.
validFrom
Start date of the account.
validUntil
Expiry date of the account.
Deprecated and ignored field.
loginID
Login ID of the customer using the service.
lastName
Customer's last name.
firstName
Customer's first name.
culture
User culture, based on RFC 4646. For example, "de-DE".
addr1
Address line 1.
addr2
Address line 2.
addr3
Address line 3.
houseNumber
House number.
city
City name.
state
State name.
countryCode
Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
postCode
Postal code.
dob
Date of birth.
placeOfBirth
Place of birth.
landlinePhone
Landline phone number.
mobilePhone
Mobile phone number.
emailAddress
Email address for any notification.
useDifferentCorrespondenceAddress
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
Correspondence address line 1.
correspondenceAddr2
Correspondence address line 2.
correspondenceAddr3
Correspondence address line 3.
correspondenceHouseNumber
Correspondence house number.
correspondenceCity
Correspondence city name.
correspondenceState
Correspondence state name.
correspondenceCountryCode
Correspondence country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
correspondencePostCode
Correspondence postal code.
occupation
A job or profession.
nationality
The ISO2 or ISO3 code of a country a new user is a national of.
taxId
Tax identification number.
identificationDocumentType
Type of the new user's identification document e.g. passport.
identityNumber
Identification document number.
documentIssuingCountryCode
The ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of a country that issued the identification document.
dateOfExpiry
Expiry date of the identification document.
sourceOfWealth
The activity which generated the new user's total net worth.
sourceOfFunds
The main activity which generates the new user's funds for this ewallet.
isPep
Is the new user or his/her family member a politically exposed person.
isBusinessUser
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
Company legal name.
businessCompanyType
Company legal type.
businessCompanyRegistrationNumber
Company registration number.
businessCompanyRegistrationCountryCode
Company registration country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
businessAddr1
Company address line 1.
businessAddr2
Company address line 2.
businessAddr3
Company address line 3.
businessHouseNumber
Company house number.
businessCity
Company city name.
businessPostCode
Company post code.
businessState
Company state name.
businessCountryCode
Company country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
businessUrl
Company website URL.
debtorData
Debtor Data parameters.
additionalData
Collection of additional data.
name
Name.
value
Value.
classification
classification.
salesOutlet
Shop id.
contactOther
Legal E-mail address (required for Italy)
gender
Customer's gender
language
Language.
registration
Tax number information.
registrationID
Registration ID.
registrationType
Registration type.
PIT-3 - possible values:
- "EU_VAT_NUMBER" for European companies;
- "NO_PERSON_ID" for private perosns (in some contries);
- "VAT_NUMBER" for European Economic Area companies.
riskStatus
Risk status.
salutation
Customer's salutation.
userAgreementReference
Reference to the user agreement text.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programCode
Program code
productCode
Account product of the new account.
accTypeCode
Account type code of the account.
custCode
Customer identifier generated by KontoCloud.
externalAccountReference
Account reference to identify the account in the future by the partners in their system.
accno
Account number.
twoFAStatusCode
Two Factor Authentication Status Code. Refer to Two Factor Authentication Status Codes in the Lookups.
accFlowStatusCode
Status code of the account flow. See Account Flow Status Codes in the Lookups.
validFrom
Start date of the account.
validUntil
Expiry date of the account.
Deprecated and ignored field.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
debtorManagementProviderResponse
Complete response of debtor management provider.
httpStatusCode
HTTP status code.
providerResponse
Response description.
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"
}
}
post {baseURL}/account/{accno}/updateInfo
Provides the ability to update an account holder's information.
Request parameters
accno
Account number.
externalAccountReference
Account reference to identify the account in the future by the partners in their system.
partnerReference
Partner service call identifier.
programCode
Program code
accTypeCode
Account type code of the account.
lastName
Customer's last name.
firstName
Customer's first name.
addr1
Address line 1.
addr2
Address line 2.
addr3
Address line 3.
houseNumber
House number.
city
City name.
postCode
Postal code.
state
State name.
countryCode
Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
dob
Date of birth.
landlinePhone
Landline phone number.
mobilePhone
Mobile phone number.
emailAddress
Email address for any notification.
nationality
The ISO2 or ISO3 code of a country a new user is a national of.
culture
User culture, based on RFC 4646. For example, "de-DE".
timeZone
User time zone id. For example, "Central European Standard Time". See Time Zone in the Lookups.
useDifferentCorrespondenceAddress
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
Correspondence address line 1.
correspondenceAddr2
Correspondence address line 2.
correspondenceAddr3
Correspondence address line 3.
correspondenceHouseNumber
Correspondence house number.
correspondenceCity
Correspondence city name.
correspondenceState
Correspondence state name.
correspondenceCountryCode
Correspondence country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
correspondencePostCode
Correspondence postal code.
taxId
Tax identification number.
identificationDocumentType
Type of the new user's identification document e.g. passport.
identityNumber
Identification document number.
documentIssuingCountryCode
The ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of a country that issued the identification document.
dateOfExpiry
Expiry date of the identification document.
notifyUser
Defines whether the account owner is notified of the account information change. Default value is false.
businessCompanyName
Company legal name.
businessCompanyType
Company legal type.
businessCompanyRegistrationNumber
Company registration number.
businessCompanyRegistrationCountryCode
Company registration country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
businessAddr1
Company address line 1.
businessAddr2
Company address line 2.
businessAddr3
Company address line 3.
businessHouseNumber
Company house number.
businessCity
Company city name.
businessState
Company state name.
businessPostCode
Company post code.
businessCountryCode
Company country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
businessUrl
Company website URL.
debtorData
Debtor Data parameters.
additionalData
Collection of additional data.
name
Name.
value
Value.
classification
classification.
salesOutlet
Shop id.
contactOther
Legal E-mail address (required for Italy)
gender
Customer's gender
language
Language.
registration
Tax number information.
registrationID
Registration ID.
registrationType
Registration type.
PIT-3 - possible values:
- "EU_VAT_NUMBER" for European companies;
- "NO_PERSON_ID" for private perosns (in some contries);
- "VAT_NUMBER" for European Economic Area companies.
riskStatus
Risk status.
salutation
Customer's salutation.
userAgreementReference
Reference to the user agreement text.
oneTimePassword
One Time Password used for confirmation during Two Factor Authentication.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programCode
Program code
accno
Account number.
providerResponse
External provider data.
complianceData
Compliance data.
archiveId
Archived check result identifier.
details
List of compliance check details. Each array item contains a list of "name"->"value" pairs.
hitType
The following options are possible:
• "SL" – sanctions list,
• "BL" – black list,
• "PEP" – publicly exposed person.
manualReview
Whether a manual review is required or not.
trafficLight
The following options are possible:
• "RED" – hit,
• "YELLOW" – unsure hit,
• "GREEN" – no hit.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
debtorManagementProviderResponse
Complete response of debtor management provider.
httpStatusCode
HTTP status code.
providerResponse
Response description.
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"
}
}
get {baseURL}/account/{accno}?partnerReference={partnerReference}&programCode={programCode}&accnoType={accnoType}&localDate={localDate}&localTime={localTime}
Returns the account holder information.
Request parameters
accno
Account number.
partnerReference
Partner service call identifier.
programCode
Program code
localDate
The current date of the caller.
localTime
The current time of the caller.
Response parameters
partnerReference
Partner service call identifier.
programCode
Program code
accno
Account number.
externalAccountReference
Account reference to identify the account in the future by the partners in their system.
merchantName
Merchant name.
lastName
Customer's last name.
firstName
Customer's first name.
addr1
Address line 1.
addr2
Address line 2.
addr3
Address line 3.
houseNumber
House number.
city
City name.
state
State name.
countryName
Country name.
countryCode
Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
postCode
Postal code.
dob
Date of birth.
landlinePhone
Landline phone number.
mobilePhone
Mobile phone number.
emailAddress
Email address for any notification.
loginID
Login ID of the customer using the service.
culture
User culture, based on RFC 4646. For example, "de-DE".
timeZone
User time zone id. For example, "Central European Standard Time". See Time Zone in the Lookups.
useDifferentCorrespondenceAddress
Defines whether a different correspondence address is used.
correspondenceAddr1
Correspondence address line 1.
correspondenceAddr2
Correspondence address line 2.
correspondenceAddr3
Correspondence address line 3.
correspondenceHouseNumber
Correspondence house number.
correspondenceCity
Correspondence city name.
correspondenceState
Correspondence state name.
correspondenceCountryName
Correspondence country name.
correspondenceCountryCode
Correspondence country ISO 3166-1 alpha-2 code.
correspondenceCountryCode3
Correspondence country ISO 3166-1 alpha-3 code.
correspondencePostCode
Correspondence postal code.
nationality
The user national country ISO2 code.
nationality3
The user national country ISO3 code.
taxId
Tax identification number.
currCode
Currency code of the account.
accTypeName
Account type of the account.
accTypeCode
Account type code of the account.
maximumAllowedBalance
Account's maximum allowed balance.
minimumAllowedBalance
Account's minimum allowed balance.
twoFAStatusCode
Two Factor Authentication Status Code. Refer to Two Factor Authentication Status Codes in the Lookups.
accFlowStatusCode
Status code of the account flow. See Account Flow Status Codes in the Lookups.
isEmailVerified
Defines whether the user's email is verified.
isMobilePhoneVerified
Defines whether the user's mobile phone number is verified.
isUserActive
Defines whether the user is active.
isUserLocked
Defines whether the user is locked.
lastLoginDate
Last user login date into the Kontocloud system.
lastLoginTime
Last user login time into the Kontocloud system.
isMtanEnabled
Defines whether MTAN support is enabled.
isBusinessUser
Defines whether business information is provided for a user.
businessCompanyName
Company legal name.
businessCompanyType
Company legal type.
businessCompanyRegistrationNumber
Company registration number.
businessCompanyRegistrationCountryCode
Company registration country ISO 3166-1 alpha-2 code.
businessCompanyRegistrationCountryCode3
Company registration country ISO 3166-1 alpha-3 code.
businessAddr1
Company address line 1.
businessAddr2
Company address line 2.
businessAddr3
Company address line 3.
businessHouseNumber
Company house number.
businessCity
Company city name.
businessPostCode
Company post code.
businessCountryCode
Company country ISO 3166-1 alpha-2 code.
businessCountryCode3
Company country ISO 3166-1 alpha-3 code.
businessUrl
Company website URL.
userAgreementReference
Reference to the user agreement text.
isUserAgreementUpToDate
Identifies the User Agreement actuality.
accountValidUntil
The latest account validity date.
accountCreationDate
The account creation date.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
Account number.
partnerReference
Partner service call identifier.
programCode
Program code
isDataDeleted
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
A reference assigned to the Data Deletion Request in the external system.
closingReason
Reason for closing the accountand data deletion (if it is needed).
storedPaymentOptionReference
Stored payment option reference to payout the account balance.
localDate
The current date of the caller.
localTime
The current time of the caller.
Response parameters
partnerReference
Partner service call identifier.
programCode
Program code
accno
Account number.
dateClosed
Calendar date when the account was closed.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
Account number.
partnerReference
Partner service call identifier.
programCode
Program code
paymentOptionCode
Payment option code.
externalChannelReference
External payment provider channel.
mandateReference
Mandate reference.
mandateSignedDate
Mandate signing date.
mandateSignedTime
mandateSignedTime
useDifferentBillingAddress
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
Customer full name consisting of the first name and last name.
emailAddress
Email address.
addr1
Address line 1.
addr2
Address line 2.
addr3
Address line 3.
houseNumber
House number.
city
City name.
state
State name.
countryCode
Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
postCode
Postal code.
phone
Phone number.
criteria
Collection of additional request parameters passed to the payment provider.
name
Parameter name.
value
Parameter value.
currCode
Currency code of the payment option to be stored.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programCode
Program code
accno
Account number.
authorizationToken
Unique authorization token assigned by an external payment provider.
paymentOptionCode
Payment option code.
paymentProviderResponse
Complete payment provider response.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
User or merchant account number.
partnerReference
Partner service call identifier.
programCode
Program code
paymentOptionCode
Payment option code.
authorizationToken
Unique authorization token assigned by an external payment provider.
useDifferentBillingAddress
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
Customer full name consisting of the first name and last name.
emailAddress
Email address.
addr1
Address line 1.
addr2
Address line 2.
addr3
Address line 3.
houseNumber
House number.
city
City name.
state
State name.
countryCode
Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
postCode
Postal code.
phone
Phone number.
externalChannelReference
External payment provider channel.
criteria
Collection of additional request parameters passed to the payment provider.
name
Parameter name.
value
Parameter value.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programCode
Program code
accno
Account number.
paymentOptionCode
Payment option code.
storedPaymentOptionReference
Stored payment option reference.
initiationCountryCode
Stored Payment Option issuer country ISO2 code.
initiationCountryCode3
Stored Payment Option issuer country ISO3 code.
paymentProviderResponse
Complete payment provider response.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
post {baseURL}/account/{accno}/storedPaymentOptions/{storedPaymentOptionReference}/initVerify
Initiates verification of an e-wallet user or merchant account preferred payment option.
Request parameters
accno
User or merchant account number.
storedPaymentOptionReference
Stored payment option reference.
partnerReference
Partner service call identifier.
programAccno
Program account number.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programCode
Program code
accno
Account number.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
post {baseURL}/account/{accno}/storedPaymentOptions/{storedPaymentOptionReference}/completeVerify
Completes verification of an e-wallet user or merchant account preferred payment option.
Request parameters
accno
User or merchant account number.
storedPaymentOptionReference
Stored payment option reference.
partnerReference
Partner service call identifier.
programCode
Program code
verificationCode
Payment option verification code.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programCode
Program code
accno
Account number.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
del {baseURL}/account/{accno}/storedPaymentOptions/{storedPaymentOptionReference}
Deletes a preferred payment option from an e-wallet user or merchant account.
Request parameters
accno
User or merchant account number.
storedPaymentOptionReference
Stored payment option reference.
partnerReference
Partner service call identifier.
programCode
Program code
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programCode
Program code
accno
Account number.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
post {baseURL}/account/{accno}/storedPaymentOptions/{storedPaymentOptionReference}/setDefault
Sets a default stored payment option for an e-wallet user or merchant account.
Request parameters
accno
User or merchant account number.
storedPaymentOptionReference
Stored payment option reference.
partnerReference
Partner service call identifier.
programCode
Program code
localDate
The current date of the caller.
localTime
The current time of the caller.
Response parameters
partnerReference
Partner service call identifier.
programCode
Program code
accno
Account number.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
Account number.
partnerReference
Partner service call identifier.
programCode
Program code
transactionTypeCode
Transaction type. See Transaction Type in the Lookups.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programCode
Program code
accno
Account number.
paymentOptions
Collection of payment option data.
code
Payment option code.
iconUrl
The URL of the payment option icon.
isStorable
Defines whether the payment option can be stored.
name
Payment option name.
paymentGroup
Payment group name.
paymentSubGroup
Payment subgroup name.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
Account number.
partnerReference
Partner service call identifier.
programCode
Program code
localDate
The current date of the caller.
localTime
The current time of the caller.
Response parameters
partnerReference
Partner service call identifier.
programCode
Program code
accno
Account number.
paymentOptions
Collection of payment option data.
bankName
Payment carrier bank name.
billingAddress
Associated billing address.
addr1
Address Line 1.
addr2
Address Line 2.
addr3
Address Line 3.
countryCode
Country ISO 3166-1 alpha-2 code.
countryCode3
Country ISO 3166-1 alpha-3 code.
countryName
Country name.
fullName
Customer's full name.
postCode
Postal code.
state
State name.
code
Payment option code.
expiryMonth
Payment carrier expiry month.
expiryYear
Payment carrier expiry year.
iconUrl
The URL of the payment option icon.
isDefault
Defines whether the payment option is default for the specified account.
isStorable
Defines whether the payment option can be stored.
isVerifiable
Defines whether the payment option can be verified.
mandate
Mandate data. Available for "Bank Account SEPA" payment option.
financialInstitutionAddr1
Financial institution address Line 1.
financialInstitutionAddr2
Financial institution address Line 2.
financialInstitutionCity
Financial institution city name.
financialInstitutionCountryCode
Financial institution country ISO 3166-1 alpha-2 code.
financialInstitutionCountryCode3
Financial institution country ISO 3166-1 alpha-3 code.
financialInstitutionCountryName
Financial institution country name.
financialInstitutionCreditorIdentifier
Financial institution creditor identifier.
financialInstitutionName
Financial institution name.
financialInstitutionPostCode
Financial institution postal code.
financialInstitutionState
Financial institution state name.
mandateReference
Mandate reference.
mandateSignedDate
Mandate signing date.
mandateSignedTime
Mandate signing time.
name
Payment option name.
paymentGroup
Payment group name.
paymentSubGroup
Payment subgroup name.
reference
Stored payment option unique reference code.
statusCode
Stored payment option status code. See Payment Option Status in the Lookups.
validUntilDate
Payment option's validity date.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
Partner service call identifier.
programAccno
Program account number.
accno
User or merchant account number.
accnoType
Account number type. See Account Number Type in the Lookups. Required only if 'accno' is specified.
storedPaymentOptionReference
Stored payment option unique reference. This value can be supplied, if 'paymentOptionCode' is not provided.
paymentOptionCode
Payment option code.
presentationAmount
The amount which is authorized for payment to the account.
presentationCurrCode
The 3-letter currency code associated with the transaction.
presentationUsage
Information relevant to the payment.
useDifferentBillingAddress
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
Customer full name consisting of the first name and last name.
emailAddress
Email address.
addr1
Address line 1.
addr2
Address line 2.
addr3
Address line 3.
houseNumber
House number.
city
City name.
state
State name.
countryCode
Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
postCode
Postal code.
phone
Phone number.
custom1
For external party usage.
custom2
For external party usage.
custom3
For external party usage.
externalChannelReference
External payment provider channel.
mandateReference
Mandate reference.
mandateSignedDate
Mandate signing date.
mandateSignedTime
mandateSignedTime
criteria
Collection of additional request parameters passed to the payment provider.
name
Parameter name.
value
Parameter value.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programCode
Program code
accno
Account number.
storedPaymentOptionReference
Stored payment option unique reference. This value can be supplied, if 'paymentOptionCode' is not provided.
uniqueReference
This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.
authorizationToken
Unique authorization token assigned by an external payment provider.
paymentOptionCode
Payment option code.
presentationAmount
The amount which is authorized for payment to the account.
presentationCurrCode
The 3-letter currency code associated with the transaction.
presentationUsage
Information relevant to the payment.
custom1
For external party usage.
custom2
For external party usage.
custom3
For external party usage.
statusReason
Reason for a status code.
paymentProviderResponse
Complete payment provider response.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
post {baseURL}/payment/{uniqueReference}/completeAuthorize
This interface method is used to complete a previously initiated authorization.
Request parameters
uniqueReference
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
Partner service call identifier.
authorizationToken
Unique authorization token assigned by an external payment provider.
externalChannelReference
External payment provider channel.
useDifferentBillingAddress
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
Customer full name consisting of the first name and last name.
addr1
Address line 1.
addr2
Address line 2.
addr3
Address line 3.
houseNumber
House number.
city
City name.
countryCode
Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
postCode
Postal code.
phone
Phone number.
criteria
Collection of additional request parameters passed to the payment provider.
name
Parameter name.
value
Parameter value.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
initiatorAccno
Initiator account number.
accno
Account number.
uniqueReference
This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.
storedPaymentOptionReference
Stored payment option reference.
initiationCountryCode
Payment Option issuer country ISO2 code.
initiationCountryCode3
Payment Option issuer country ISO3 code.
processedAmount
The amount returned by the acquirer after processing.
processedCurrCode
The 3-letter currency code associated with the processed amount.
statusReason
Reason for a status code.
paymentProviderResponse
Complete payment provider response:
- Array for "PayU" payment option;
- Object for all other payment options.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
Partner service call identifier.
programAccno
Program account number.
accno
User or merchant account number.
accnoType
Account number type. See Account Number Type in the Lookups. Required only if 'accno' is specified.
storedPaymentOptionReference
Stored payment option reference.
invoiceReference
Payment invoice reference.
channelProductReference
Payment channel product reference.
presentationAmount
The amount which is authorized for payment to the account.
presentationCurrCode
The 3-letter currency code associated with the transaction.
presentationUsage
Information relevant to the payment.
useDifferentBillingAddress
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
Customer full name consisting of the first name and last name.
addr1
Address line 1.
addr2
Address line 2.
addr3
Address line 3.
houseNumber
House number.
city
City name.
state
State name.
countryCode
Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
postCode
Postal code.
phone
Phone number.
emailAddress
Email address.
custom1
For external party usage.
custom2
For external party usage.
custom3
For external party usage.
criteria
Collection of additional request parameters passed to the payment provider.
name
Parameter name.
value
Parameter value.
oneTimePassword
One Time Password used for confirmation during Two Factor Authentication.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programAccno
Program account number.
accno
Account number.
uniqueReference
This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.
storedPaymentOptionReference
Stored payment option reference.
invoiceReference
Payment invoice reference.
channelProductReference
Payment channel product reference.
presentationAmount
The amount which is authorized for payment to the account.
presentationCurrCode
The 3-letter currency code associated with the transaction.
presentationUsage
Information relevant to the payment.
processedAmount
The amount returned by the acquirer after processing.
processedCurrCode
The 3-letter currency code associated with the processed amount.
custom1
For external party usage.
custom2
For external party usage.
custom3
For external party usage.
statusReason
Reason for a status code.
paymentProviderResponse
Complete payment provider response.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.
partnerReference
Partner service call identifier.
modifiedUsage
Information relevant to the payment.
custom1
For external party usage.
custom2
For external party usage.
custom3
For external party usage.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
initiatorAccno
Initiator account number.
accno
Account number.
uniqueReference
Unique transaction reference assigned by KontoCloud upon authorization.
modifiedAmount
The amount which is captured for payment to the account.
modifiedAmountCurrCode
The 3-letter currency code associated with the transaction.
processedAmount
The amount returned by the acquirer after processing.
processedCurrCode
The 3-letter currency code associated with the processed amount.
custom1
For external party usage.
custom2
For external party usage.
custom3
For external party usage.
statusReason
Reason for a status code.
paymentProviderResponse
Complete payment provider response:
- Array for "PayU" payment option;
- Object for all other payment options.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
post {baseURL}/payment/{uniqueReference}/refund
This interface method is used to refund a previously captured external authorization.
Request parameters
partnerReference
Partner service call identifier.
uniqueReference
This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.
refundAmount
Amount being refunded. It cannot exceed the amount of the refunded transaction. If the value is not provided the full refund is performed.
refundUsage
Information relevant to the refund.
refundType
The code defining what type of refund will be performed. Available types of refund listed in "Refund Type" lookup.
refundSourceAccno
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
For external party usage.
custom2
For external party usage.
custom3
For external party usage.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
initiatorAccno
Initiator account number.
accno
Account number.
uniqueReference
Unique transaction reference assigned by KontoCloud upon authorization.
refundAmount
Amount being refunded. It cannot exceed the amount of the refunded transaction. If the value is not provided the full refund is performed.
refundCurrCode
Currency code of the amount to be refunded.
processedAmount
The amount returned by the acquirer after processing.
processedCurrCode
The 3-letter currency code associated with the processed amount.
custom1
For external party usage.
custom2
For external party usage.
custom3
For external party usage.
statusReason
Reason for a status code.
paymentProviderResponse
Complete payment provider response:
- Array for "PayU" payment option;
- Object for all other payment options.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
post {baseURL}/payment/{uniqueReference}/cancel
This interface method is used to cancel a previously authorized payment to an e-wallet account.
Request parameters
uniqueReference
This is the uniqueReference that was assigned to the external authorization. It is received as part of authorization response from KontoCloud.
partnerReference
Partner service call identifier.
custom1
For external party usage.
custom2
For external party usage.
custom3
For external party usage.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
initiatorAccno
Initiator account number.
accno
Account number.
uniqueReference
Unique transaction reference assigned by KontoCloud upon authorization.
custom1
For external party usage.
custom2
For external party usage.
custom3
For external party usage.
statusReason
Reason for a status code.
paymentProviderResponse
Complete payment provider response:
- Array for "PayU" payment option;
- Object for all other payment options.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
Unique transaction reference assigned by the KontoCloud.
partnerReference
Partner service call identifier.
localDate
The current date of the caller.
localTime
The current time of the caller.
Response parameters
uniqueReference
Unique transaction reference assigned by the KontoCloud. Same as in request.
partnerReference
Partner service call identifier.
initiatorAccno
Initiator account number.
initiatorName
Name of the instance which initiated the payment.
accno
Account number.
presentationAmount
Amount with which the payment was initiated or captured.
presentationCurrCode
The 3-letter currency code associated with the transaction.
presentationUsage
Information relevant to the payment.
customerFullName
Customer full name consisting of the first name and last name.
addr1
Address line 1.
addr2
Address line 2.
addr3
Address line 3.
houseNumber
House number.
city
City name.
state
State name.
country
Country name.
countryCode
Country ISO 3166-1 alpha-2 code.
countryCode3
Country ISO 3166-1 alpha-3 code.
postCode
Postal code.
statusReason
Reason for a status code.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
E-wallet user account number.
partnerReference
Partner service call identifier.
programCode
Program code
userId
User identifier: email, login, secondary email address, or uuid.
localDate
The current date of the caller.
localTime
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
partnerReference same as in the Request.
programCode
Program code
accno
Account number.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
E-wallet user account number.
partnerReference
Partner service call identifier.
programCode
Program code
amount
The amount to be checked for availability to payment from the account.
currCode
The 3-letter currency code of the checked amount.
localDate
The current date of the caller.
localTime
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.
When this API Endpoint returns a Successful Response - the "Content-Type" Header will be "text/plain" and the Body will contain either "yes" or "no", as demonstrated.
However, if it returns an Error Response (ex. HTTP 400) - the "Content-Type" Header will be "application/json" and the Body will contain a JSON Error Data Object.
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"
}
}
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
E-wallet user account number.
partnerReference
Partner service call identifier.
programCode
Program code
startDate
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
Start time for the enquiry. If 'startTime' is provided, 'startDate' becomes required. If not specified "000000" is used as start time.
endDate
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
End time for the enquiry. If 'endTime' is provided, 'endDate' becomes required. If not specified "235959" is used as end time.
top
Number of account entries to return. Used for requesting a specific number of the most recent account entries.
skip
Number of account entries to skip in the result set. Used for skipping a specific number of the most recent account entries.
includeNeutral
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
Defines the direction of sorting by booking date. See Sort Direction in the Lookups. If not specified, "ASC" is used.
includePendingTransactions
A flag defining whether pending transactions should be included in the response. "False" is used if it is not provided.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programAccno
Program account number.
accno
E-wallet user account number or merchant account number.
count
Total pending transactions count using the 'startDate' and 'endDate' filters.
entries
Collection of account entries data.
amount
For account entry: converted entry amount according to the account currency. For account entry: converted entry amount according to the account currency.
For transaction entry: transaction's AccountAmount.
balance
For account entry: account closed balance.
For account entry: account closed balance.
For transaction entry: empty.
bookingDate
For account entry: entry booking date.
For account entry: entry booking date.
For transaction entry: empty.
bookingTime
For account entry: entry booking time.
For account entry: entry booking time.
For transaction entry: empty.
currCode
For account entry: account currency code.
For account entry: account currency code.
For transaction entry: transaction's account currency code.
description
For account entry: entry description.
For account entry: entry description.
For transaction entry: transaction presentation usage.
entryIndicator
Entry indicator:
- "DBIT",
- "CRDT".
entryType
Entry type.
exchangeRate
Currency conversion rate used.
isPending
For account entry: False.
For transaction entry: True.
name
Entry name.
reference
For account entry: account entry unique reference. For account entry: account entry unique reference.
For transaction entry: transaction's TransactionReference.
sourceAmount
For account entry: originaloriginal entry amount.
For transaction entry: the transaction's PresentationAmount.
sourceCurrCode
For account entry: original entry currency code.
For account entry: original entry currency code.
For transaction entry: transaction's presentationCurrCode.
statusCode
For account entry: "SETTLED". For transaction entry: Transaction status code. See Transaction Status in the Lookups.
valueTime
For account entry: entry value time. For account entry: entry value time.
For transaction entry: transaction's creation time.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
E-wallet user account number.
partnerReference
Partner service call identifier.
programCode
Program code
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programAccno
Program account number.
accno
E-wallet user account number or merchant account number.
psBal
Previous day closing balance.
avlBal
Current available balance (booked balance – blocked Amount).
bkBal
Booked balance: Booked balance is the total deposit on a particular day plus previous closing balance.
blkAmt
Total Blocked amount: Blocked amount is the authorized amount until it is captured or cancelled.
pooledAmt
Total Pooled amount: Pooled amount is authorized only on the wallet account, but not on the external payment option.
currCode
Currency code of the balance returned.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
Partner service call identifier.
depositReference
uniqueReference of a transaction that was assigned to a capture external authorization request.
accno
E-wallet user account number.
merchantAccno
Merchant account number.
programCode
Program code
programAccno
Program account number.
merchantProgramCode
Destination program code. Mandatory if merchantAccno is specified as External Account Reference.
paymentAmount
The amount of payment .
paymentCurrCode
The 3-letter currency code associated with the transaction.
paymentUsage
Description of a performed payment.
useDifferentBillingAddress
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
Customer full name consisting of the first name and last name.
countryCode
Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
addr1
Customer's address line 1.
addr2
Customer's address line 2.
addr3
Customer's address line 3.
houseNumber
Customer's house number.
city
Customer's city name.
state
State name.
postCode
Customer's postal code.
phone
Phone number.
emailAddress
Email address.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
uniqueReference
Unique reference assigned by KontoCloud to the credit transaction.
accno
E-wallet user account number or merchant account number.
merchantAccno
Seller merchant account number.
programAccno
Program account number.
paymentAmount
The amount of payment .
paymentCurrCode
The 3-letter currency code associated with the transaction.
paymentUsage
Description of a performed payment.
fxRate
Currency conversion rate between payment currency and merchant account currency used in the transaction.
statusReason
Reason for a status code.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
Partner service call identifier.
depositReference
uniqueReference of a transaction that was assigned to a capture external authorization request.
accno
E-wallet user account number or merchant account number.
programAccno
Initiating program account number.
merchantAccno
Destination merchant account number.
merchantProgramCode
Destination program code. Mandatory if merchantAccno is specified as External Account Reference.
accnoType
Account number and merchant account number type. Refer to Account Number Type in the Lookups.
paymentAmount
The amount of payment from eWallet account to merchant account.
paymentCurrCode
The 3-letter currency code associated with the transaction.
paymentUsage
Description of a performed payment.
useDifferentBillingAddress
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
Customer full name consisting of the first name and last name.
countryCode
Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
addr1
Customer's address line 1.
addr2
Customer's address line 2.
addr3
Customer's address line 3.
houseNumber
Customer's house number.
city
Customer's city name.
state
State name.
postCode
Customer's postal code.
emailAddress
Email address.
oneTimePassword
One Time Password used for confirmation during Two Factor Authentication.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
uniqueReference
Unique reference assigned by KontoCloud to the credit transaction.
accno
E-wallet user account number or merchant account number.
programAccno
Program account number.
merchantAccno
Seller merchant account number.
merchantProgramCode
Destination program code.
paymentAmount
The amount of payment .
paymentCurrCode
The 3-letter currency code associated with the transaction.
paymentUsage
Description of a performed payment.
fxRate
Currency conversion rate used.
statusReason
Reason for a status code.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
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
This is the uniqueReference that was assigned to an authorization. It is received as part of "KC-Authorize" response from KontoCloud.
partnerReference
Partner service call identifier.
modifiedAmount
The amount of payment from the e-Wallet account to the merchant account.
modifiedAmountCurrCode
The 3-letter currency code associated with the transaction.
modifiedUsage
Information relevant to the payment.
localDate
The current date of the caller.
localTime
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
A unique reference assigned to the authorization by KontoCloud. Same as in the request.
partnerReference
Partner service call identifier.
merchantAccno
Merchant account number.
accno
Account number.
modifiedAmount
The amount of payment from the e-Wallet account to the merchant account.
modifiedAmountCurrCode
The 3-letter currency code associated with the transaction.
processedAmount
The amount the member is paying from their e-Wallet account to the merchant account in the merchant account currency.
fxRate
Currency conversion rate between payment currency and merchant account currency used in the transaction.
statusReason
Reason for a status code.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
post {baseURL}/payment/{uniqueReference}/kc-cancel
This interface method is used to cancel a previously authorized payment before it is captured.
Request parameters
uniqueReference
This is the uniqueReference that was assigned to an authorization. It is received as part of "KC-Authorize" response from KontoCloud.
partnerReference
Partner service call identifier.
modifiedUsage
Information relevant to the payment.
localDate
The current date of the caller.
localTime
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
A unique reference assigned to the authorization by KontoCloud. Same as in the request.
partnerReference
Partner service call identifier.
merchantAccno
Merchant account number.
accno
Account number.
statusReason
Reason for a status code.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
post {baseURL}/payment/{uniqueReference}/kc-refund
This interface method is used to refund a previously captured payment.
Request parameters
uniqueReference
This is the uniqueReference that was assigned to an authorization. It is received as part of "KC-Authorize" response from KontoCloud.
partnerReference
Partner service call identifier.
refundAmount
Amount being refunded. It cannot exceed the amount of the refunded transaction. If the value is not provided the full refund is performed.
refundUsage
Information relevant to the refund.
refundType
The code defining what type of refund will be performed. Available types of refund listed in "Refund Type" lookup.
localDate
The current date of the caller.
localTime
The current time of the caller.
Response parameters
uniqueReference
A unique reference assigned to the authorization by KontoCloud. Same as in the request.
partnerReference
Partner service call identifier.
refundSourceAccno
Refund source account number.
accno
Account number.
statusReason
Reason for a status code.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
post {baseURL}/compliance/addressCheck
A request to check the validity of an address.
Request parameters
partnerReference
Partner service call identifier.
programCode
Program code
street
Street.
house
House.
postalCode
Postal code.
city
City name.
countryCode
Country ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code.
localDate
The current date of the caller.
localTime
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
Partner service call identifier.
programCode
Program code
addressCheckData
Address check data.
archiveId
Archived check result identifier.
decision
The following options are possible:
• "HOUSE_CONFIRMED": address confirmed;
• "STREET_CONFIRMED_HOUSE_NOT_I DENTIFIED": street confirmed / House unknown;
• "STREET_CONFIRMED_HOUSE_NOT_P ROVIDED": street confirmed / House not provided in request;
• "CITY_CONFIRMED_STREET_NOT_IDE NTIFIED": city confirmed / Street unknown;
• "NOT_CONFIRMED": location not confirmed (unknown).
foundAddress
Found address data.
city
City.
countryCode
Country ISO 3166-1 alpha-2 code.
house
House.
houseExtension
House extension.
postalCode
Postal code.
street
Street.
normalizedAddress
Normalized address data. Only for Germany.
city
City.
countryCode
Country ISO 3166-1 alpha-2 code.
house
House.
houseExtension
House extension.
postalCode
Postal code.
street
Street.
postalCodeCorrect
Defines whether the postal code is correct.
localDate
The current date of the caller.
localTime
The current time of the caller.
sysDate
The current date of the KontoCloud server
sysTime
The current time of the KontoCloud server
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"
}
}
post {baseURL}/compliance/personCheck
A request to check a person's compliance via the compliance system.
Request parameters
partnerReference
Partner service call identifier.
merchantReference
Merchant reference to identify the merchant for which the check is being performed.
programCode
Program code
division
Division.
customerId
Customer identifier.
firstName
First name.
lastName
Last name.
street
Street.
house
House.
postalCode
Postal code.
city
City name.
countryCode