PISP

1. Find User Account

Most API methods require to specify the customer account number (parameter "accno") and the program code (parameter "programCode"), which acts as an identifier for the marketplace.

To obtain these parameters, call the API Method

1.17 Find User Account

and specify the customer email address in the parameter "userId".

Find User Account Request

Path:

GET {baseURL}/account/find?partnerReference=50F45B51E07D4CE1ABB1676E3DF5BB44&programCode=COMPANY&userId=user@example.com&localDate=2019-09-17&localTime=131415

Header:

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

Find User Account Response

Status Code:

200 (OK)

Header:

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

{
"accno": "1000104149",
"partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
"programCode": "COMPANY",
"localDate": "2019-09-17",
"localTime": "131415",
"sysDate": "2019-09-17",
"sysTime": "121420",
"responseCode": "0000",
"responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

2. Check Available Payment Amount

To check if an accounts balance exceeds a specific payment amount, call the API method

1.146 Check Available Payment Amount

as shown in the sample below.

If the customer's available balance is sufficient the API returns "yes", otherwise "no". Please note, that the reponse body is formatted as plain text.

Check Available Payment Amout Request

Path:

GET {baseURL}/account/1000104149/checkAvailablePaymentAmount?partnerReference=50F45B51E07D4CE1ABB1676E3DF5BB44&programCode=COMPANY&accnoType=00&amount=100&currCode=EUR&localDate=2019-09-17&localTime=131415

Header:

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

Check Available Payment Amount Response

Status Code:

200 (OK)

Header:

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

yes

3. Initiate Payment

To initiate a payment, you can either use the API method 1.42 KC-Authorize or 1.121 KC-Debit. While KC-Authorize only authorizes the transaction without capturing the amount, KC-Debit performs an automatic capture as soon as the transaction has been successfully authorized.

KC-Authorize Request

Path:

PUT {baseURL}/payment/kc-authorize

Header:

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

{
 "partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
 "accno": "1000104149",
 "merchantAccno": "9999999",
 "programAccno": "1111111",
 "accnoType": "01",
 "paymentAmount": 100.00,
 "paymentCurrCode": "EUR",
 "paymentUsage": "Purchase of item1.",
 "useDifferentBillingAddress": false,
 "localDate": "2019-09-17",
 "localTime": "131415" 
}

KC-Authorize Response

Status Code:

201 (Created)

Header:

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

{ 
 "partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
 "accno": "1000104149",
 "merchantAccno": "9999999",
 "programAccno": "1111111",
 "paymentAmount": 100.00,
 "paymentCurrCode": "EUR",
 "paymentUsage": "Purchase of item1.",
 "twoFAConfirmationURI": "https://www.example.com",
 "localDate": "2019-09-17",
 "localTime": "163835",
 "sysDate": "2019-09-17",
 "sysTime": "153837",
 "responseCode": "0000",
 "responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

4. Retrieve One-Time Password

Generate a QR-code from the received "twoFAConfirmationURI" and display it on your webpage. The KontoCloud Authenticator app allows the customer to scan the QR-code and displays the corresponding one-time password. Finally, collect the one-time password from the customer via an input field on your webpage.

5. Complete Payment

KC-Authorize Request

Path:

PUT {baseURL}/payment/kc-authorize

Header:

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

{
 "partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
 "accno": "1000104149",
 "merchantAccno": "9999999",
 "programAccno": "1111111",
 "accnoType": "01",
 "paymentAmount": 100.00,
 "paymentCurrCode": "EUR",
 "paymentUsage": "Purchase of item1.",
 "oneTimePassword": "134567890",
 "useDifferentBillingAddress": false,
 "localDate": "2019-09-17",
 "localTime": "131415" 
}

KC-Authorize Response

Status Code:

201 (Created)

Header:

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

{ 
 "partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
 "uniqueReference": "d633d423651c4cc4bb04b6be69a13ecd",
 "accno": "1000104149",
 "merchantAccno": "9999999",
 "programAccno": "1111111",
 "paymentAmount": 100.00,
 "paymentCurrCode": "EUR",
 "paymentUsage": "Purchase of item1.",
 "fxRate": 1.00,
 "statusCode": "AUTHORIZED",
 "statusReason": "",
 "localDate": "2019-09-17",
 "localTime": "163835",
 "sysDate": "2019-09-17",
 "sysTime": "153837",
 "responseCode": "0000",
 "responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}

Call 1.15 KC-Cancel with the uniqueReference from the KC-Authorize response in the URL to capture the previously authorized payment amount.

KC-Capture Request

Path:

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

Header:

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

{
"partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
"modifiedAmount": 100.00,
"modifiedAmountCurrCode": "EUR",
"localDate": "2019-09-17",
"localTime": "163835"
}

KC-Capture Response

Status Code:

200 (OK)

Header:

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

{ 
"uniqueReference": "d633d423651c4cc4bb04b6be69a13ecd",
"partnerReference": "50F45B51E07D4CE1ABB1676E3DF5BB44",
"merchantAccno": "9999999",
"accno": "1000104149",
"modifiedAmount": 100.00,
"modifiedAmountCurrCode": "EUR",
"processedAmount": 100.00,
"processedCurrCode": "EUR",
"fxRate": 1.00,
"statusCode": "CAPTURED",
"statusReason": "",
"localDate": "2019-09-17",
"localTime": "163835",
"sysDate": "2019-09-17",
"sysTime": "153837",
"responseCode": "0000",
"responseDescription": "Successful execution.",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}