Introduction

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

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

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

We recommend setting a minimum timeout of 90 seconds, even though API requests are expected to return a response much faster

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

API Authentication

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

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

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

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

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.

1.45 Issue Token

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

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

Request parameters

userId

String Length: 255 Required

Caller user identifier in the KontoCloud system.

password

String Length: 128 Required

Caller password in the KontoCloud system.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:: POST {baseURL}/user/user@example.com/issue
Header:: Content-Type: application/json
Accept-Language: en-US

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

Response parameters

token

String Length: 32768

Security token.

validUntil

YYYY-MM-DD Length: 24

Token validity period in UTC.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

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

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

Error Handling

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

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

Communication of errors to end users

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

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

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

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

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

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

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

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

Capture Error Handling

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

Logical Errors

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

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

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

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

Response sample

Status Code:: 400 (Bad Request)
Header:: Content-Type: application/json
Accept-Language: en-US

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

Unexpected Errors

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

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

Response sample

Status Code:: 500 (Internal Server Error)
Header:: Content-Type: application/json
Accept-Language: en-US

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

Account Management

1.1 Create Account

put {baseURL}/account

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

Request parameters

externalAccountReference

String Length: 255

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

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accountApplicationFlowCode

String Length: 10

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

currCode

String Length: 3 Required

Currency code of the account to be opened.

validFrom

YYYY-MM-DD Length: 10

Start date of the account.

validUntil

YYYY-MM-DD Length: 10

Expiry date of the account.

Deprecated and ignored field.

loginID

String Length: 255

title

String Length: 2

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

lastName

String Length: 100 Required

Customer's last name.

firstName

String Length: 100 Required

Customer's first name.

culture

String Length: 14

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

addr1

String Length: 60 Required

Address line 1.

addr2

String Length: 60

Address line 2.

addr3

String Length: 60

Address line 3.

houseNumber

String Length: 10

House number.

city

String Length: 50 Required

City name.

state

String Length: 50

State name.

countryCode

String Length: 3 Required

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

postCode

String Length: 10 Required

Postal code.

dob

YYYY-MM-DD Length: 10 Required

Date of birth.

placeOfBirth

String Length: 100

Place of birth.

landlinePhone

String Length: 30

Landline phone number.

mobilePhone

String Length: 30

Mobile phone number.

emailAddress

String Length: 255 Required

Email address for any notification.

useDifferentCorrespondenceAddress

Boolean Required

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

correspondenceAddr1

String Length: 60

Correspondence address line 1.

correspondenceAddr2

String Length: 60

Correspondence address line 2.

correspondenceAddr3

String Length: 60

Correspondence address line 3.

correspondenceHouseNumber

String Length: 10

Correspondence house number.

correspondenceCity

String Length: 50

Correspondence city name.

correspondenceState

String Length: 50

Correspondence state name.

correspondenceCountryCode

String Length: 3

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

correspondencePostCode

String Length: 10

Correspondence postal code.

occupation

String Length: 50

A job or profession.

nationality

String Length: 3 Required

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

taxId

String Length: 50

Tax identification number.

identificationDocumentType

String Length: 50

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

identityNumber

String Length: 20

Identification document number.

documentIssuingCountryCode

String Length: 3

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

dateOfExpiry

YYYY-MM-DD Length: 10

Expiry date of the identification document.

sourceOfWealth

String Length: 50

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

sourceOfFunds

String Length: 50

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

isPep

Boolean

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

isBusinessUser

Boolean

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

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

If false, the fields listed above are optional.

businessCompanyName

String Length: 201

Company legal name.

businessCompanyType

String Length: 100

Company legal type.

businessCompanyRegistrationNumber

String Length: 50

Company registration number.

businessCompanyRegistrationCountryCode

String Length: 3

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

businessAddr1

String Length: 60

Company address line 1.

businessAddr2

String Length: 60

Company address line 2.

businessAddr3

String Length: 60

Company address line 3.

businessHouseNumber

String Length: 10

Company house number.

businessCity

String Length: 50

Company city name.

businessPostCode

String Length: 10

Company post code.

businessState

String Length: 50

Company state name.

businessCountryCode

String Length: 3

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

businessUrl

String Length: 255

Company website URL.

debtorData

Object

Debtor Data parameters.

additionalData

Array

Collection of additional data.

name

String

Name.

value

String

Value.

classification

Object

classification.

salesOutlet

String

Shop id.

contactOther

String

Legal E-mail address (required for Italy)

gender

String

Customer's gender

language

String

Language.

registration

Object

Tax number information.

registrationID

String

Registration ID.

registrationType

String

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

String

Risk status.

salutation

String

Customer's salutation.

userAgreementReference

String Length: 36

Reference to the user agreement text.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

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

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

productCode

String Length: 10

Account product of the new account.

accTypeCode

String Length: 10

Account type code of the account.

custCode

String Length: 10

Customer identifier generated by KontoCloud.

externalAccountReference

String Length: 255

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

accno

String Length: 255

Account number.

statusCode

String Length: 10

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

twoFAStatusCode

String Length: 10

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

accFlowStatusCode

String Length: 10

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

validFrom

YYYY-MM-DD Length: 10

Start date of the account.

validUntil

YYYY-MM-DD Length: 10

Expiry date of the account.

Deprecated and ignored field.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

debtorManagementProviderResponse

Object

Complete response of debtor management provider.

httpStatusCode

String Length: 3

HTTP status code.

providerResponse

String

Response description.

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.4 Update Account Information

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

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

Request parameters

accno

String Length: 255 Required

Account number.

externalAccountReference

String Length: 255

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

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

accTypeCode

String Length: 10

Account type code of the account.

title

String Length: 2

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

lastName

String Length: 100 Required

Customer's last name.

firstName

String Length: 100 Required

Customer's first name.

addr1

String Length: 60 Required

Address line 1.

addr2

String Length: 60

Address line 2.

addr3

String Length: 60

Address line 3.

houseNumber

String Length: 10

House number.

city

String Length: 50 Required

City name.

postCode

String Length: 10 Required

Postal code.

state

String Length: 50

State name.

countryCode

String Length: 3 Required

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

dob

YYYY-MM-DD Length: 10 Required

Date of birth.

landlinePhone

String Length: 30

Landline phone number.

mobilePhone

String Length: 30

Mobile phone number.

emailAddress

String Length: 255 Required

Email address for any notification.

nationality

String Length: 3 Required

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

culture

String Length: 14

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

timeZone

String Length: 50

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

useDifferentCorrespondenceAddress

Boolean Required

correspondenceAddr1

String Length: 60

Correspondence address line 1.

correspondenceAddr2

String Length: 60

Correspondence address line 2.

correspondenceAddr3

String Length: 60

Correspondence address line 3.

correspondenceHouseNumber

String Length: 10

Correspondence house number.

correspondenceCity

String Length: 50

Correspondence city name.

correspondenceState

String Length: 50

Correspondence state name.

correspondenceCountryCode

String Length: 3

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

correspondencePostCode

String Length: 10

Correspondence postal code.

taxId

String Length: 50

Tax identification number.

identificationDocumentType

String Length: 50

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

identityNumber

String Length: 20

Identification document number.

documentIssuingCountryCode

String Length: 3

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

dateOfExpiry

YYYY-MM-DD Length: 10

Expiry date of the identification document.

notifyUser

Boolean

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

businessCompanyName

String Length: 201

Company legal name.

businessCompanyType

String Length: 100

Company legal type.

businessCompanyRegistrationNumber

String Length: 50

Company registration number.

businessCompanyRegistrationCountryCode

String Length: 3

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

businessAddr1

String Length: 60

Company address line 1.

businessAddr2

String Length: 60

Company address line 2.

businessAddr3

String Length: 60

Company address line 3.

businessHouseNumber

String Length: 10

Company house number.

businessCity

String Length: 50

Company city name.

businessState

String Length: 50

Company state name.

businessPostCode

String Length: 10

Company post code.

businessCountryCode

String Length: 3

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

businessUrl

String Length: 255

Company website URL.

debtorData

Object

Debtor Data parameters.

additionalData

Array

Collection of additional data.

name

String

Name.

value

String

Value.

classification

Object

classification.

salesOutlet

String

Shop id.

contactOther

String

Legal E-mail address (required for Italy)

gender

String

Customer's gender

language

String

Language.

registration

Object

Tax number information.

registrationID

String

Registration ID.

registrationType

String

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

String

Risk status.

salutation

String

Customer's salutation.

userAgreementReference

String Length: 36

Reference to the user agreement text.

oneTimePassword

Number Length: 8

One Time Password used for confirmation during Two Factor Authentication.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

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

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

providerResponse

Object

External provider data.

complianceData

Array

Compliance data.

archiveId

String Length: 50

Archived check result identifier.

details

Array

List of compliance check details. Each array item contains a list of "name"->"value" pairs.

hitType

String Length: 10

The following options are possible:

• "SL" – sanctions list,

• "BL" – black list,

• "PEP" – publicly exposed person.

manualReview

Boolean

Whether a manual review is required or not.

trafficLight

String Length: 10

The following options are possible:

• "RED" – hit,

• "YELLOW" – unsure hit,

• "GREEN" – no hit.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

debtorManagementProviderResponse

Object

Complete response of debtor management provider.

httpStatusCode

String Length: 3

HTTP status code.

providerResponse

String

Response description.

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.5 Get Account Information

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

Returns the account holder information.

Request parameters

accno

String Length: 255 Required

Account number.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:: GET {baseURL}/account/XXX-123456?partnerReference=50F45B51E07D4CE1ABB1676E3DF5BB44&programCode=COMPANY123&accnoType=01&localDate=2016-01-31&localTime=131415
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

externalAccountReference

String Length: 255

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

merchantName

String Length: 201

Merchant name.

title

Number Length: 1

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

lastName

String Length: 100

Customer's last name.

firstName

String Length: 100

Customer's first name.

addr1

String Length: 60

Address line 1.

addr2

String Length: 60

Address line 2.

addr3

String Length: 60

Address line 3.

houseNumber

String Length: 10

House number.

city

String Length: 50

City name.

state

String Length: 50

State name.

countryName

String Length: 100

Country name.

countryCode

String Length: 3

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

postCode

String Length: 10

Postal code.

dob

YYYY-MM-DD Length: 10

Date of birth.

landlinePhone

String Length: 30

Landline phone number.

mobilePhone

String Length: 30

Mobile phone number.

emailAddress

String Length: 255

Email address for any notification.

loginID

String Length: 255

culture

String Length: 14

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

timeZone

String Length: 50

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

useDifferentCorrespondenceAddress

Boolean

Defines whether a different correspondence address is used.

correspondenceAddr1

String Length: 60

Correspondence address line 1.

correspondenceAddr2

String Length: 60

Correspondence address line 2.

correspondenceAddr3

String Length: 60

Correspondence address line 3.

correspondenceHouseNumber

String Length: 10

Correspondence house number.

correspondenceCity

String Length: 50

Correspondence city name.

correspondenceState

String Length: 50

Correspondence state name.

correspondenceCountryName

String Length: 100

Correspondence country name.

correspondenceCountryCode

String Length: 2

Correspondence country ISO 3166-1 alpha-2 code.

correspondenceCountryCode3

String Length: 3

Correspondence country ISO 3166-1 alpha-3 code.

correspondencePostCode

String Length: 10

Correspondence postal code.

nationality

String Length: 2

The user national country ISO2 code.

nationality3

String Length: 3

The user national country ISO3 code.

taxId

String Length: 50

Tax identification number.

currCode

String Length: 3

Currency code of the account.

accTypeName

String Length: 100

Account type of the account.

accTypeCode

String Length: 10

Account type code of the account.

maximumAllowedBalance

Decimal Length: 18

Account's maximum allowed balance.

minimumAllowedBalance

Decimal Length: 18

Account's minimum allowed balance.

statusCode

String Length: 10

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

twoFAStatusCode

String Length: 10

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

accFlowStatusCode

String Length: 10

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

isEmailVerified

Boolean

Defines whether the user's email is verified.

isMobilePhoneVerified

Boolean

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

isUserActive

Boolean

Defines whether the user is active.

isUserLocked

Boolean

Defines whether the user is locked.

lastLoginDate

YYYY-MM-DD Length: 10

Last user login date into the Kontocloud system.

lastLoginTime

HHMMSS Length: 6

Last user login time into the Kontocloud system.

isMtanEnabled

Boolean

Defines whether MTAN support is enabled.

isBusinessUser

Boolean

Defines whether business information is provided for a user.

businessCompanyName

String Length: 201

Company legal name.

businessCompanyType

String Length: 100

Company legal type.

businessCompanyRegistrationNumber

String Length: 50

Company registration number.

businessCompanyRegistrationCountryCode

String Length: 2

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

businessCompanyRegistrationCountryCode3

String Length: 3

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

businessAddr1

String Length: 60

Company address line 1.

businessAddr2

String Length: 60

Company address line 2.

businessAddr3

String Length: 60

Company address line 3.

businessHouseNumber

String Length: 10

Company house number.

businessCity

String Length: 50

Company city name.

businessPostCode

String Length: 10

Company post code.

businessCountryCode

String Length: 2

Company country ISO 3166-1 alpha-2 code.

businessCountryCode3

String Length: 3

Company country ISO 3166-1 alpha-3 code.

businessUrl

String Length: 255

Company website URL.

userAgreementReference

String Length: 36

Reference to the user agreement text.

isUserAgreementUpToDate

Boolean

Identifies the User Agreement actuality.

accountValidUntil

YYYY-MM-DD Length: 10

The latest account validity date.

accountCreationDate

YYYY-MM-DD Length: 10

The account creation date.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

{
"accno": "1000104149",
"title": 1,
"externalAccountReference": "CUSTID1234567890",
"lastName": "Lastname",
"firstName": "Firstname",
"addr1": "123 Anystreet",
"addr2": "Building 1a",
"addr3": null,
"houseNumber": null,
"city": "Anycity",
"state": "Anystate",
"countryCode": "DE",
"countryName": "Germany",
"postCode": "POSTCOD123",
"dob": "1990-01-31",
"landlinePhone": "+49 1234 567 890",
"mobilePhone": "+49 1234 567 890",
"emailAddress": "user@example.com",
"currCode": "EUR",
"accTypeName": "Starter Business",
"accTypeCode": "STARTBIZ",
"maximumAllowedBalance": "1000.00",
"minimumAllowedBalance": "0.00",
"statusCode": "ACTIVE",
"twoFAStatusCode": "2FADIS"
"accFlowStatusCode": "APPROVEDSV",
"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": "2016-03-01",
"accountCreationDate": "2016-01-31",
"localDate": "2016-01-31",
"localTime": "000000",
"sysDate": "2016-06-15",
"sysTime": "114249",
"responseCode": "0000",
"responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

1.73 Close Account

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

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

Request parameters

accno

String Length: 255 Required

Account number.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

isDataDeleted

Boolean

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

externalRequestReference

String Length: 100

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

closingReason

String Length: 1024 Required

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

storedPaymentOptionReference

String Length: 36

Stored payment option reference to payout the account balance.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

statusCode

String Length: 10

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

dateClosed

YYYY-MM-DD Length: 10

Calendar date when the account was closed.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

Payment Option Management

1.53 Init Add Stored Payment Option

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

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

Request parameters

accno

String Length: 255 Required

Account number.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

paymentOptionCode

String Length: 10

Payment option code.

externalChannelReference

String Length: 100

External payment provider channel.

mandateReference

String Length: 35

Mandate reference.

mandateSignedDate

YYYY-MM-DD Length: 10

Mandate signing date.

mandateSignedTime

HHMMSS Length: 6

mandateSignedTime

useDifferentBillingAddress

Boolean Required

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

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

If false, the account owner address is used.

customerFullName

String Length: 201

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

emailAddress

String Length: 255

Email address.

addr1

String Length: 60

Address line 1.

addr2

String Length: 60

Address line 2.

addr3

String Length: 60

Address line 3.

houseNumber

String Length: 10

House number.

city

String Length: 50

City name.

state

String Length: 50

State name.

countryCode

String Length: 3

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

postCode

String Length: 10

Postal code.

phone

String Length: 30

Phone number.

criteria

Array

Collection of additional request parameters passed to the payment provider.

name

String Length: 50 Required

Parameter name.

value

String Length: 100 Required

Parameter value.

currCode

String Length: 3

Currency code of the payment option to be stored.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

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

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

authorizationToken

String Length: 8192

Unique authorization token assigned by an external payment provider.

paymentOptionCode

String Length: 10

Payment option code.

paymentProviderResponse

Object

Complete payment provider response.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.54 Complete Add Stored Payment Option

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

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

Request parameters

accno

String Length: 255 Required

User or merchant account number.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

paymentOptionCode

String Length: 10

Payment option code.

authorizationToken

String Length: 8192 Required

Unique authorization token assigned by an external payment provider.

useDifferentBillingAddress

Boolean Required

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

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

If false, the account owner address is used.

customerFullName

String Length: 201

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

emailAddress

String Length: 255

Email address.

addr1

String Length: 60

Address line 1.

addr2

String Length: 60

Address line 2.

addr3

String Length: 60

Address line 3.

houseNumber

String Length: 10

House number.

city

String Length: 50

City name.

state

String Length: 50

State name.

countryCode

String Length: 3

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

postCode

String Length: 10

Postal code.

phone

String Length: 30

Phone number.

externalChannelReference

String Length: 100

External payment provider channel.

criteria

Array

Collection of additional request parameters passed to the payment provider.

name

String Length: 50 Required

Parameter name.

value

String Length: 100 Required

Parameter value.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

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

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

paymentOptionCode

String Length: 10

Payment option code.

storedPaymentOptionReference

String Length: 36

Stored payment option reference.

initiationCountryCode

String Length: 2

Stored Payment Option issuer country ISO2 code.

initiationCountryCode3

String Length: 3

Stored Payment Option issuer country ISO3 code.

paymentProviderResponse

Object

Complete payment provider response.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.56 Init Verify Stored Payment Option

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

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

Request parameters

accno

String Length: 255 Required

User or merchant account number.

storedPaymentOptionReference

String Length: 36 Required

Stored payment option reference.

partnerReference

String Length: 64 Required

Partner service call identifier.

programAccno

String Length: 255 Required

Program account number.

accnoType

String Length: 2 Required

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

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:: POST {baseURL}/account/XXX-123456/storedPaymentOptions/5e71b97bd8aa446ba35161ec5c7af3f2/initVerify
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

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

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

1.57 Complete Verify Stored Payment Option

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

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

Request parameters

accno

String Length: 255 Required

User or merchant account number.

storedPaymentOptionReference

String Length: 36 Required

Stored payment option reference.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

verificationCode

Number Length: 6 Required

Payment option verification code.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:: POST {baseURL}/account/XXX-123456/storedPaymentOptions/5e71b97bd8aa446ba35161ec5c7af3f2/completeVerify
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.55 Delete Stored Payment Option

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

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

Request parameters

accno

String Length: 255 Required

User or merchant account number.

storedPaymentOptionReference

String Length: 36 Required

Stored payment option reference.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:: DELETE {baseURL}/account/XXX-123456/storedPaymentOptions/5e71b97bd8aa446ba35161ec5c7af3f2
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.79 Set Default Stored Payment Option

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

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

Request parameters

accno

String Length: 255 Required

User or merchant account number.

storedPaymentOptionReference

String Length: 36 Required

Stored payment option reference.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.21 Get Payment Options

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

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

Request parameters

accno

String Length: 255 Required

Account number.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

transactionTypeCode

String Length: 10 Required

Transaction type. See Transaction Type in the Lookups.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:: GET {baseURL}/account/XXX-123456/paymentOptions?partnerReference=1234567890&programCode=PROG&accnoType=00&transactionTypeCode=AUTH&localDate=2014-03- 12&localTime=163835
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

transactionTypeCode

String Length: 10

Transaction type. See Transaction Type in the Lookups.

paymentOptions

Array

Collection of payment option data.

code

String Length: 10

Payment option code.

iconUrl

String Length: 255

The URL of the payment option icon.

isStorable

Boolean

Defines whether the payment option can be stored.

name

String Length: 100

Payment option name.

paymentGroup

String Length: 100

Payment group name.

paymentGroupCode

String Length: 10

Payment group code. See Payment Group in the Lookups.

paymentSubGroup

String Length: 100

Payment subgroup name.

paymentSubGroupCode

String Length: 10

Payment subgroup code. See Payment Subgroup in the Lookups.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.26 Get Stored Payment Options

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

Returns the payment options stored for an account.

Request parameters

accno

String Length: 255 Required

Account number.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

transactionTypeCode

String Length: 10

Transaction type. See Transaction Type in the Lookups.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:: GET {baseURL}/account/XXX-123456/storedPaymentOptions?partnerReference=1234567890&programCode=PROG&accnoType=00&localDate=2014-03-12&localTime=163835
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

paymentOptions

Array

Collection of payment option data.

bankName

String Length: 255

Payment carrier bank name.

billingAddress

Object

Associated billing address.

addr1

String Length: 60

Address Line 1.

addr2

String Length: 60

Address Line 2.

addr3

String Length: 60

Address Line 3.

countryCode

String Length: 2

Country ISO 3166-1 alpha-2 code.

countryCode3

String Length: 3

Country ISO 3166-1 alpha-3 code.

countryName

String Length: 100

Country name.

fullName

String Length: 201

Customer's full name.

postCode

String Length: 10

Postal code.

state

String Length: 50

State name.

code

String Length: 10

Payment option code.

expiryMonth

Number Length: 2

Payment carrier expiry month.

expiryYear

Number Length: 4

Payment carrier expiry year.

iconUrl

String Length: 255

The URL of the payment option icon.

isDefault

Boolean

Defines whether the payment option is default for the specified account.

isStorable

Boolean

Defines whether the payment option can be stored.

isVerifiable

Boolean

Defines whether the payment option can be verified.

mandate

Object

Mandate data. Available for "Bank Account SEPA" payment option.

financialInstitutionAddr1

String Length: 60

Financial institution address Line 1.

financialInstitutionAddr2

String Length: 60

Financial institution address Line 2.

financialInstitutionCity

String Length: 50

Financial institution city name.

financialInstitutionCountryCode

String Length: 2

Financial institution country ISO 3166-1 alpha-2 code.

financialInstitutionCountryCode3

String Length: 3

Financial institution country ISO 3166-1 alpha-3 code.

financialInstitutionCountryName

String Length: 100

Financial institution country name.

financialInstitutionCreditorIdentifier

String Length: 35

Financial institution creditor identifier.

financialInstitutionName

String Length: 100

Financial institution name.

financialInstitutionPostCode

String Length: 10

Financial institution postal code.

financialInstitutionState

String Length: 50

Financial institution state name.

mandateReference

String Length: 35

Mandate reference.

mandateSignedDate

YYYY-MM-DD Length: 10

Mandate signing date.

mandateSignedTime

HHMMSS Length: 6

Mandate signing time.

name

String Length: 100

Payment option name.

paymentGroup

String Length: 100

Payment group name.

paymentGroupCode

String Length: 10

Payment group code. See Payment Group in the Lookups.

paymentSubGroup

String Length: 100

Payment subgroup name.

paymentSubGroupCode

String Length: 10

Payment subgroup code. See Payment Subgroup in the Lookups.

reference

String Length: 36

Stored payment option unique reference code.

statusCode

String Length: 10

Stored payment option status code. See Payment Option Status in the Lookups.

validUntilDate

YYYY-MM-DD Length: 10

Payment option's validity date.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

Payment

1.38 Init Authorize

put {baseURL}/payment/initAuthorize

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

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

Request parameters

partnerReference

String Length: 64 Required

Partner service call identifier.

programAccno

String Length: 255 Required

Program account number.

accno

String Length: 255

User or merchant account number.

accnoType

String Length: 2

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

storedPaymentOptionReference

String Length: 36

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

paymentOptionCode

String Length: 10

Payment option code.

presentationAmount

Decimal Length: 18,2 Required

The amount which is authorized for payment to the account.

presentationCurrCode

String Length: 3 Required

The 3-letter currency code associated with the transaction.

presentationUsage

String Length: 127 Required

Information relevant to the payment.

useDifferentBillingAddress

Boolean Required

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

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

- customerFullName

- emailAddress

- addr1

- houseNumber (if not included in addr1)

- city

- postCode

- countryCode

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

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

customerFullName

String Length: 201

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

emailAddress

String

Email address.

addr1

String Length: 60

Address line 1.

addr2

String Length: 60

Address line 2.

addr3

String Length: 60

Address line 3.

houseNumber

String Length: 10

House number.

city

String Length: 50

City name.

state

String Length: 50

State name.

countryCode

String Length: 3

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

postCode

String Length: 10

Postal code.

phone

String Length: 30

Phone number.

custom1

String Length: 255

For external party usage.

custom2

String Length: 255

For external party usage.

custom3

String Length: 255

For external party usage.

externalChannelReference

String Length: 100

External payment provider channel.

mandateReference

String Length: 35

Mandate reference.

mandateSignedDate

YYYY-MM-DD Length: 10

Mandate signing date.

mandateSignedTime

HHMMSS Length: 6

mandateSignedTime

criteria

Array

Collection of additional request parameters passed to the payment provider.

name

String Length: 50 Required

Parameter name.

value

String Length: 100 Required

Parameter value.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample for CIT

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

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

storedPaymentOptionReference

String Length: 36

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

uniqueReference

String Length: 36

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

authorizationToken

String Length: 8192

Unique authorization token assigned by an external payment provider.

paymentOptionCode

String Length: 10

Payment option code.

presentationAmount

Decimal Length: 18,2

The amount which is authorized for payment to the account.

presentationCurrCode

String Length: 3

The 3-letter currency code associated with the transaction.

presentationUsage

String Length: 255

Information relevant to the payment.

custom1

String Length: 255

For external party usage.

custom2

String Length: 255

For external party usage.

custom3

String Length: 255

For external party usage.

statusCode

String Length: 10

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

statusReason

String Length: 255

Reason for a status code.

paymentProviderResponse

Object

Complete payment provider response.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample for CIT

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

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

1.39 Complete Authorize

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

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

Request parameters

uniqueReference

String Length: 36 Required

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

partnerReference

String Length: 64 Required

Partner service call identifier.

authorizationToken

String Length: 8192 Required

Unique authorization token assigned by an external payment provider.

externalChannelReference

String Length: 100

External payment provider channel.

useDifferentBillingAddress

Boolean

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

customerFullName

String Length: 201

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

addr1

String Length: 60

Address line 1.

addr2

String Length: 60

Address line 2.

addr3

String Length: 60

Address line 3.

houseNumber

String Length: 10

House number.

city

String Length: 50

City name.

countryCode

String Length: 3

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

postCode

String Length: 10

Postal code.

phone

String Length: 30

Phone number.

criteria

Array

Collection of additional request parameters passed to the payment provider.

name

String Length: 50 Required

Parameter name.

value

String Length: 100 Required

Parameter value.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:: POST {baseURL}/payment/{uniqueReference}/completeAuthorize
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

initiatorAccno

String Length: 255

Initiator account number.

accno

String Length: 255

Account number.

uniqueReference

String Length: 36

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

storedPaymentOptionReference

String Length: 36

Stored payment option reference.

initiationCountryCode

String Length: 2

Payment Option issuer country ISO2 code.

initiationCountryCode3

String Length: 3

Payment Option issuer country ISO3 code.

processedAmount

Decimal Length: 18,2

The amount returned by the acquirer after processing.

processedCurrCode

String Length: 3

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

statusCode

String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason

String Length: 255

Reason for a status code.

paymentProviderResponse

Object

Complete payment provider response:

- Array for "PayU" payment option;

- Object for all other payment options.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.27 Authorize

put {baseURL}/payment/authorize

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

Request parameters

partnerReference

String Length: 64 Required

Partner service call identifier.

programAccno

String Length: 255 Required

Program account number.

accno

String Length: 255

User or merchant account number.

accnoType

String Length: 2

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

storedPaymentOptionReference

String Length: 36 Required

Stored payment option reference.

invoiceReference

String Length: 255

Payment invoice reference.

channelProductReference

String Length: 255

Payment channel product reference.

presentationAmount

Decimal Length: 18,2 Required

The amount which is authorized for payment to the account.

presentationCurrCode

String Length: 3 Required

The 3-letter currency code associated with the transaction.

presentationUsage

String Length: 127 Required

Information relevant to the payment.

useDifferentBillingAddress

Boolean Required

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

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

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

customerFullName

String Length: 201

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

addr1

String Length: 60

Address line 1.

addr2

String Length: 60

Address line 2.

addr3

String Length: 60

Address line 3.

houseNumber

String Length: 10

House number.

city

String Length: 50

City name.

state

String Length: 50

State name.

countryCode

String Length: 3

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

postCode

String Length: 10

Postal code.

phone

String Length: 30

Phone number.

emailAddress

String Length: 255

Email address.

custom1

String Length: 255

For external party usage.

custom2

String Length: 255

For external party usage.

custom3

String Length: 255

For external party usage.

criteria

Array

Collection of additional request parameters passed to the payment provider.

name

String Length: 50 Required

Parameter name.

value

String Length: 100 Required

Parameter value.

oneTimePassword

Number Length: 8

One Time Password used for confirmation during Two Factor Authentication.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

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

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programAccno

String Length: 255

Program account number.

accno

String Length: 255

Account number.

uniqueReference

String Length: 36

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

storedPaymentOptionReference

String Length: 36

Stored payment option reference.

invoiceReference

String Length: 255

Payment invoice reference.

channelProductReference

String Length: 255

Payment channel product reference.

presentationAmount

Decimal Length: 18,2

The amount which is authorized for payment to the account.

presentationCurrCode

String Length: 3

The 3-letter currency code associated with the transaction.

presentationUsage

String Length: 127

Information relevant to the payment.

processedAmount

Decimal Length: 18,2

The amount returned by the acquirer after processing.

processedCurrCode

String Length: 3

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

custom1

String Length: 255

For external party usage.

custom2

String Length: 255

For external party usage.

custom3

String Length: 255

For external party usage.

statusCode

String Length: 10

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

statusReason

String Length: 255

Reason for a status code.

paymentProviderResponse

Object

Complete payment provider response.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.29 Capture

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

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

Request parameters

uniqueReference

String Length: 36 Required

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

partnerReference

String Length: 64 Required

Partner service call identifier.

modifiedUsage

String Length: 127

Information relevant to the payment.

custom1

String Length: 255

For external party usage.

custom2

String Length: 255

For external party usage.

custom3

String Length: 255

For external party usage.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:: POST {baseURL}/payment/d633d423651c4cc4bb04b6be69a13ecd/capture
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

initiatorAccno

String Length: 255

Initiator account number.

accno

String Length: 255

Account number.

uniqueReference

String Length: 36

Unique transaction reference assigned by KontoCloud upon authorization.

modifiedAmount

Decimal Length: 18,2

The amount which is captured for payment to the account.

modifiedAmountCurrCode

String Length: 3

The 3-letter currency code associated with the transaction.

processedAmount

Decimal Length: 18,2

The amount returned by the acquirer after processing.

processedCurrCode

String Length: 3

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

custom1

String Length: 255

For external party usage.

custom2

String Length: 255

For external party usage.

custom3

String Length: 255

For external party usage.

statusCode

String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason

String Length: 255

Reason for a status code.

paymentProviderResponse

Object

Complete payment provider response:

- Array for "PayU" payment option;

- Object for all other payment options.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.75 Refund

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

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

Request parameters

partnerReference

String Length: 64 Required

Partner service call identifier.

uniqueReference

String Length: 36 Required

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

refundAmount

Decimal Length: 18,2

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

refundUsage

String Length: 255

Information relevant to the refund.

refundType

String Length: 1

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

refundSourceAccno

String Length: 36

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

custom1

String Length: 255

For external party usage.

custom2

String Length: 255

For external party usage.

custom3

String Length: 255

For external party usage.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:: POST {baseURL}/payment/d633d423651c4cc4bb04b6be69a13ecd/refund
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

initiatorAccno

String Length: 255

Initiator account number.

accno

String Length: 255

Account number.

uniqueReference

String Length: 36

Unique transaction reference assigned by KontoCloud upon authorization.

refundAmount

Decimal Length: 18,2

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

refundCurrCode

String Length: 3

Currency code of the amount to be refunded.

processedAmount

Decimal Length: 18,2

The amount returned by the acquirer after processing.

processedCurrCode

String Length: 3

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

custom1

String Length: 255

For external party usage.

custom2

String Length: 255

For external party usage.

custom3

String Length: 255

For external party usage.

statusCode

String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason

String Length: 255

Reason for a status code.

paymentProviderResponse

Object

Complete payment provider response:

- Array for "PayU" payment option;

- Object for all other payment options.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.30 Cancel

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

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

Request parameters

uniqueReference

String Length: 36 Required

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

partnerReference

String Length: 64 Required

Partner service call identifier.

custom1

String Length: 255

For external party usage.

custom2

String Length: 255

For external party usage.

custom3

String Length: 255

For external party usage.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:: POST {baseURL}/payment/d633d423651c4cc4bb04b6be69a13ecd/cancel
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

initiatorAccno

String Length: 255

Initiator account number.

accno

String Length: 255

Account number.

uniqueReference

String Length: 36

Unique transaction reference assigned by KontoCloud upon authorization.

custom1

String Length: 255

For external party usage.

custom2

String Length: 255

For external party usage.

custom3

String Length: 255

For external party usage.

statusCode

String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason

String Length: 255

Reason for a status code.

paymentProviderResponse

Object

Complete payment provider response:

- Array for "PayU" payment option;

- Object for all other payment options.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.41 Get Payment Status

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

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

Request parameters

uniqueReference

String Length: 36 Required

Unique transaction reference assigned by the KontoCloud.

partnerReference

String Length: 64 Required

Partner service call identifier.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

Path:: GET {baseURL}/payment/1234567890/status?partnerReference=1234567890&localDate=2014-03-12&localTime=163835
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

Response parameters

uniqueReference

String Length: 36

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

partnerReference

String Length: 64

Partner service call identifier.

initiatorAccno

String Length: 255

Initiator account number.

initiatorName

String Length: 201

Name of the instance which initiated the payment.

accno

String Length: 255

Account number.

presentationAmount

Decimal Length: 18,2

Amount with which the payment was initiated or captured.

presentationCurrCode

String Length: 3

The 3-letter currency code associated with the transaction.

presentationUsage

String Length: 127

Information relevant to the payment.

customerFullName

String Length: 201

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

addr1

String Length: 60

Address line 1.

addr2

String Length: 60

Address line 2.

addr3

String Length: 60

Address line 3.

houseNumber

String Length: 10

House number.

city

String Length: 50

City name.

state

String Length: 50

State name.

country

String Length: 100

Country name.

countryCode

String Length: 2

Country ISO 3166-1 alpha-2 code.

countryCode3

String Length: 3

Country ISO 3166-1 alpha-3 code.

postCode

String Length: 10

Postal code.

statusCode

String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason

String Length: 255

Reason for a status code.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

TPP

Card Based Payment Instruments

1.17 Find User Account

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

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

Request parameters

accno

String Length: 255 Required

E-wallet user account number.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

userId

String Length: 255 Required

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

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:: GET {baseURL}/account/find?partnerReference=50F45B51E07D4CE1ABB1676E3DF5BB44&programCode=COMPANY123&userId=user@example.com&localDate=2016-01-31&localTime=131415
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

Response parameters

partnerReference

String Length: 64

partnerReference same as in the Request.

programCode

String Length: 10

Program code

accno

String Length: 255

Account number.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

1.146 Check Available Payment Amount

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

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

Request parameters

accno

String Length: 255 Required

E-wallet user account number.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

amount

Decimal Length: 18.2 Required

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

currCode

String Length: 3 Required

The 3-letter currency code of the checked amount.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:: GET {baseURL}/account/XXX-123456/checkAvailablePaymentAmount?partnerReference=50F45B51E07D4CE1ABB1676E3DF5BB44&programCode=COMPANY123&accnoType=00&amount=100&currCode=EUR&localDate=2019-12-02&localTime=131415
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

Response parameters

The response contains the following possible text values without quotes:

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

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.

Response Sample (Successful)

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

yes

Response Sample (Fail Case)

Status Code:: 400 (Bad Request)
Header:: Content-Type: application/json
Accept-Language: en-US

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

Account Information

1.7 Account Enquiry

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

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

Request parameters

accno

String Length: 255 Required

E-wallet user account number.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

startDate

YYYY-MM-DD Length: 10

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

startTime

HHMMSS Length: 6

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

endDate

YYYY-MM-DD Length: 10

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

endTime

HHMMSS Length: 6

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

top

Number Length: 4

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

skip

Number Length: 4

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

includeNeutral

Boolean

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

sortDirection

String Length: 4

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

includePendingTransactions

Boolean

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

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:: GET {baseURL}/account/XXX-123456/enquiry?partnerReference=1234567890&programCode=PROG &accnoType=00&startDate=2014-01-01&endDate=2014-01-31&top=100& includePendingTransactions=false&skip=100 &localDate=2014-03-12&localTime=163835
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programAccno

String Length: 255

Program account number.

accno

String Length: 255

E-wallet user account number or merchant account number.

count

Number Length: 6

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

entries

Array

Collection of account entries data.

amount

Decimal Length: 18

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

Decimal Length: 18

For account entry: account closed balance.

For transaction entry: empty.

bookingDate

YYYY-MM-DD Length: 10

For account entry: entry booking date.

For transaction entry: empty.

bookingTime

HHMMSS Length: 6

For account entry: entry booking time.

For transaction entry: empty.

currCode

String Length: 3

For account entry: account currency code.

For transaction entry: transaction's account currency code.

description

String Length: 512

For account entry: entry description.

For transaction entry: transaction presentation usage.

entryIndicator

String Length: 4

Entry indicator:

- "DBIT",

- "CRDT".

entryType

String Length: 100

Entry type.

exchangeRate

Decimal Length: 18

Currency conversion rate used.

isPending

Boolean

For account entry: False.

For transaction entry: True.

name

String Length: 201

Entry name.

reference

String Length: 36

For account entry: account entry unique reference. For account entry: account entry unique reference.

For transaction entry: transaction's TransactionReference.

sourceAmount

Decimal Length: 18

For account entry: originaloriginal entry amount.

For transaction entry: the transaction's PresentationAmount.

sourceCurrCode

String Length: 3

For account entry: original entry currency code.

For transaction entry: transaction's presentationCurrCode.

statusCode

String Length: 10

For account entry: "SETTLED". For transaction entry: Transaction status code. See Transaction Status in the Lookups.

valueTime

HHMMSS Length: 6

For account entry: entry value time. For account entry: entry value time.

For transaction entry: transaction's creation time.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

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

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

1.8 Balance Enquiry

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

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

Request parameters

accno

String Length: 255 Required

E-wallet user account number.

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

accnoType

String Length: 2 Required

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

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:: GET {baseURL}/account/1000104149/balance?partnerReference=50F45B51E07D4CE1ABB1676E3DF5BB44&programCode=COMPANY123&accnoType=01&localDate=2016-01-31&localTime=131415
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programAccno

String Length: 255

Program account number.

accno

String Length: 255

E-wallet user account number or merchant account number.

psBal

Decimal Length: 18

Previous day closing balance.

avlBal

Decimal Length: 18

Current available balance (booked balance – blocked Amount).

bkBal

Decimal Length: 18

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

blkAmt

Decimal Length: 18

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

pooledAmt

Decimal Length: 18,2

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

currCode

String Length: 3

Currency code of the balance returned.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

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

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

Payment Initiation

1.42 KC-Authorize

put {baseURL}/payment/kc-authorize

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

Request parameters

partnerReference

String Length: 64 Required

Partner service call identifier.

depositReference

String Length: 36

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

accno

String Length: 255 Required

E-wallet user account number.

merchantAccno

String Length: 255

Merchant account number.

programCode

String Length: 10 Required

Program code

programAccno

String Length: 255 Required

Program account number.

merchantProgramCode

String Length: 10

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

accnoType

String Length: 2 Required

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

paymentAmount

Decimal Length: 18,2 Required

The amount of payment .

paymentCurrCode

String Length: 3 Required

The 3-letter currency code associated with the transaction.

paymentUsage

String Length: 255 Required

Description of a performed payment.

useDifferentBillingAddress

Boolean Required

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

customerFullName

String Length: 201

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

countryCode

String Length: 3 Required

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

addr1

String Length: 60

Customer's address line 1.

addr2

String Length: 60

Customer's address line 2.

addr3

String Length: 60

Customer's address line 3.

houseNumber

String Length: 10

Customer's house number.

city

String Length: 50

Customer's city name.

state

String Length: 50

State name.

postCode

String Length: 10

Customer's postal code.

phone

String Length: 30

Phone number.

emailAddress

String

Email address.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:: PUT {baseURL}/payment/kc-authorize
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

uniqueReference

String Length: 36

Unique reference assigned by KontoCloud to the credit transaction.

accno

String Length: 255

E-wallet user account number or merchant account number.

merchantAccno

String Length: 255

Seller merchant account number.

programAccno

String Length: 255

Program account number.

paymentAmount

Decimal Length: 18,2

The amount of payment .

paymentCurrCode

String Length: 3

The 3-letter currency code associated with the transaction.

paymentUsage

String Length: 255

Description of a performed payment.

fxRate

Decimal Length: 18,2

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

statusCode

String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason

String Length: 255

Reason for a status code.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

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

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

1.121 KC-Debit Account

put {baseURL}/payment/kc-debitAccount

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

Request parameters

partnerReference

String Length: 64 Required

Partner service call identifier.

depositReference

String Length: 36

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

accno

String Length: 255 Required

E-wallet user account number or merchant account number.

programAccno

String Length: 255 Required

Initiating program account number.

merchantAccno

String Length: 255 Required

Destination merchant account number.

merchantProgramCode

String Length: 10

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

accnoType

String Length: 2 Required

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

paymentAmount

Decimal Length: 18,2 Required

The amount of payment from eWallet account to merchant account.

paymentCurrCode

String Length: 3 Required

The 3-letter currency code associated with the transaction.

paymentUsage

String Length: 255 Required

Description of a performed payment.

useDifferentBillingAddress

Boolean Required

customerFullName

String Length: 201

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

countryCode

String Length: 3 Required

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

addr1

String Length: 60

Customer's address line 1.

addr2

String Length: 60

Customer's address line 2.

addr3

String Length: 60

Customer's address line 3.

houseNumber

String Length: 10

Customer's house number.

city

String Length: 50

Customer's city name.

state

String Length: 50

State name.

postCode

String Length: 10

Customer's postal code.

emailAddress

String

Email address.

oneTimePassword

String Length: 8

One Time Password used for confirmation during Two Factor Authentication.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:: PUT {baseURL}/payment/kc-debitAccount
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

uniqueReference

String Length: 36

Unique reference assigned by KontoCloud to the credit transaction.

accno

String Length: 255

E-wallet user account number or merchant account number.

programAccno

String Length: 255

Program account number.

merchantAccno

String Length: 255

Seller merchant account number.

merchantProgramCode

String Length: 10

Destination program code.

paymentAmount

Decimal Length: 18,2

The amount of payment .

paymentCurrCode

String Length: 3

The 3-letter currency code associated with the transaction.

paymentUsage

String Length: 255

Description of a performed payment.

fxRate

Decimal Length: 18

Currency conversion rate used.

statusCode

String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason

String Length: 255

Reason for a status code.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

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

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

1.14 KC-Capture

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

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

Request parameters

uniqueReference

String Length: 36 Required

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

partnerReference

String Length: 64 Required

Partner service call identifier.

modifiedFeeAmount

Decimal Length: 18,2

Fee charged for capturing the amount.

modifiedAmountCurrCode

String Length: 3 Required

The 3-letter currency code associated with the transaction.

modifiedUsage

String Length: 127

Information relevant to the payment.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:: POST {baseURL}/payment/1234567890/kc-capture
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

uniqueReference

String Length: 36

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

partnerReference

String Length: 64

Partner service call identifier.

merchantAccno

String Length: 255

Merchant account number.

accno

String Length: 255

Account number.

modifiedAmount

Decimal Length: 18,2

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

modifiedAmountCurrCode

String Length: 3

The 3-letter currency code associated with the transaction.

processedAmount

Decimal Length: 18

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

fxRate

Decimal Length: 18,2

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

statusCode

String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason

String Length: 255

Reason for a status code.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

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

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

1.15 KC-Cancel

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

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

Request parameters

uniqueReference

String Length: 36 Required

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

partnerReference

String Length: 64 Required

Partner service call identifier.

modifiedUsage

String Length: 127

Information relevant to the payment.

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:: POST {baseURL}/payment/1234567890/kc-cancel
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

uniqueReference

String Length: 36

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

partnerReference

String Length: 64

Partner service call identifier.

merchantAccno

String Length: 255

Merchant account number.

accno

String Length: 255

Account number.

statusCode

String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason

String Length: 255

Reason for a status code.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

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

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

1.16 KC-Refund

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

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

Request parameters

uniqueReference

String Length: 36 Required

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

partnerReference

String Length: 64 Required

Partner service call identifier.

refundAmount

Decimal Length: 18,2

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

refundUsage

String Length: 255

Information relevant to the refund.

refundType

String Length: 1

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

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request Sample

Path:: POST {baseURL}/payment/1234567890/kc-refund
Header:: Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=

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

Response parameters

uniqueReference

String Length: 36

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

partnerReference

String Length: 64

Partner service call identifier.

refundSourceAccno

String Length: 255

Refund source account number.

accno

String Length: 255

Account number.

statusCode

String Length: 10

Transaction status code. See Transaction Status in the Lookups.

statusReason

String Length: 255

Reason for a status code.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response Sample

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

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

Ancillary Services

Address Validation

1.105 Perform Address Check

post {baseURL}/compliance/addressCheck

A request to check the validity of an address.

Request parameters

partnerReference

String Length: 64 Required

Partner service call identifier.

programCode

String Length: 10 Required

Program code

street

String Length: 68 Required

Street.

house

String Length: 10

House.

postalCode

String Length: 10

Postal code.

city

String Length: 50

City name.

countryCode

String Length: 3

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

localDate

YYYY-MM-DD Length: 10 Required

The current date of the caller.

localTime

HHMMSS Length: 6 Required

The current time of the caller.

Request sample

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

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

Response parameters

partnerReference

String Length: 64

Partner service call identifier.

programCode

String Length: 10

Program code

addressCheckData

Object

Address check data.

archiveId

String Length: 50

Archived check result identifier.

decision

String Length: 50

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

Object

Found address data.

city

String Length: 50

City.

countryCode

String Length: 2

Country ISO 3166-1 alpha-2 code.

house

String Length: 10

House.

houseExtension

String Length: 50

House extension.

postalCode

String Length: 10

Postal code.

street

String Length: 68

Street.

normalizedAddress

Object

Normalized address data. Only for Germany.

city

String Length: 50

City.

countryCode

String Length: 2

Country ISO 3166-1 alpha-2 code.

house

String Length: 10

House.

houseExtension

String Length: 50

House extension.

postalCode

String Length: 10

Postal code.

street

String Length: 68

Street.

postalCodeCorrect

Boolean

Defines whether the postal code is correct.

localDate

YYYY-MM-DD Length: 10

The current date of the caller.

localTime

HHMMSS Length: 6

The current time of the caller.

sysDate

YYYY-MM-DD Length: 10

The current date of the KontoCloud server

sysTime

HHMMSS Length: 6

The current time of the KontoCloud server

responseCode

String Length: 4

The response code. See Response Codes in the Lookups.

responseDescription

String Length: 512

The response description. See Response Codes in the Lookups.

Response sample

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

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

Compliance Check

1.101 Perform Person Compliance Check

post {baseURL}/compliance/personCheck

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

Request parameters

partnerReference

String Length: 64 Required

Partner service call identifier.

merchantReference

String Length: 36

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

programCode

String Length: 10 Required

Program code

division

String Length: 100

Division.

customerId

String Length: 255 Required

Customer identifier.

firstName

String Length: 100 Required

First name.

lastName

String Length: 100 Required

Last name.

street

String Length: 68 Required

Street.

house

String Length: 10

House.

postalCode

String Length: 10 Required

Postal code.

city

String Length: 50 Required

City name.

countryCode

String Length: 3 Required