Customer Initiated Transactions (CIT)
Please note, that the following described SCA payment process only applies to Customer Initiated Recurring Payments (CIT). Here, the customer selects the stored credit card (one-click payment) and proceeds with the 3DS flow.
1. Initiate Authorization
The authorization of a payment is initialized by calling the API method 1.38 Init Authorize.
In the example below, we authorize 3.99 EUR for the payment option associated with the "storedPaymentOptionReference" (see Get Stored Payment Options) as part of the purchase of two premium widgets from Widgets GmbH.
Please note the Payment Provider may NOT permit processing for Non-Decimal Currencies if the "presentationAmount" does NOT contain a whole number.
Initiate Authorization Request
Path:
PUT {baseURL}/payment/initAuthorize
Header:
Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=
{
"partnerReference": "DEV-SVR001-DE_CUSTID-KD97TH2FP6_CARTID-PYQRTGMCMQ_VGT284FYXV",
"programAccno": "1679541175",
"accno": "MERCHANT-DE4321",
"accnoType": "00",
"storedPaymentOptionReference": "8ac7a4a266aab3ce0166c0602bf26dae",
"paymentOptionCode": "VISA",
"presentationAmount": 3.99,
"presentationCurrCode": "EUR",
"presentationUsage": "Purchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95.",
"useDifferentBillingAddress": false,
"localDate": "2018-10-15",
"localTime": "155107",
"custom1": "WVWZZZ3BZWE689725"
}
More information on the Mandatory and Optional parameters can be found in the 3D-Secure v2.x Requirements section.
Initiate Authorization Response
Status Code:
201 (Created)
Header:
Content-Type: application/json
Accept-Language: en-US
{
"programAccno": "1679541175",
"accno": "MERCHANT-DE4321",
"uniqueReference": "BNkk4BRkQEufPSvgf9lDwA",
"loadAccountReference": "NvPoE85cZE6FguOfrC7Fmw",
"authorizationToken": "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01",
"storedPaymentOptionReference": "8ac7a4a266aab3ce0166c0602bf26dae",
"paymentOptionCode": "VISA",
"presentationAmount": 3.99,
"presentationCurrCode": "EUR",
"presentationUsage": "Purchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95.",
"custom1": "WVWZZZ3BZWE689725",
"statusCode": "RECEIVED",
"paymentProviderResponse": {
"result": {
"code": "000.200.100",
"description": "successfully created checkout"
},
"buildNumber": "b5487567b639c21ffd60a5f42c484f3276ff93b3@2018-10-11 13:50:52 +0000",
"timestamp": "2018-10-15 13:55:51+0000",
"ndc": "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01",
"id": "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01"
},
"partnerReference": "DEV-SVR001-DE_CUSTID-KD97TH2FP6_CARTID-PYQRTGMCMQ_VGT284FYXV",
"localDate": "2018-10-15",
"localTime": "155550",
"sysDate": "2018-10-15",
"sysTime": "135551",
"responseCode": "0000",
"responseDescription": "Successful execution",
"additionalInformation": {
"requestId": "aff2728481a181dc36daedc14055b516"
}
}
The response includes the desired authorization token under the return parameter "authorizationToken" which is used to collect payment option details via the SDK and alongside the "uniqueReference" is required to complete the authorization of the initiated transaction. The transaction reference under the return parameter "uniqueReference" is furthermore required for the following API calls. Beyond this use, it should be persisted if possible, as it enables the identification of the transaction should the need arise at a later stage.
2. Payment Form Rendering via SDK
The SDK renders a form with the stored payment option and initiates the SCA (Secure Customer Authentication) flow. We offer SDKs for the integration into websites as well as mobile applications (Android and iOS).
The example below shows only the relevant part of the KC Web SDK implementation with credit card. A complete and detailed description of the KC Web SDK can be found here.
The authorization token returned by the API method 1.38 Init Authorize which initiated the transaction is used to associate the payment form rendered by the KC Web SDK with the transaction.
cw.PaymentForm(container, {
authorizationToken: "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01",
callbackUrl: "https://www.example.com/Checkout/CompleteOrder",
paymentOptionCodes: ["VISA"],
locale: "en-US",
paymentProviderMode: "test",
submitButtonTitle: "Continue",
onError: function(message) {
console.log(message);
}
}
This is followed by a redirect to the respective SCA procedure (e.g., 3-D Secure for credit card). Test transactions simulate the 3D-Secure authentication which allows you to select an expected return code (e.g., "Successful").
When configuring Content Security Policy consider 3-D Secure Verification will redirect to the Customer's Issuing Bank in order to Authorize the Transaction.
3. Complete Authorization
Since the SDK sends the payment details directly to the acquirer, where the payment is subsequently processed, you have no knowledge about the current status of the payment and if it got authorized. Therefore, call the API method 1.39 Complete Authorize from your server-side method behind the "callbackURL", which you specified in the SDK.
Complete Authorization Request
Path:
POST {baseURL}/payment/{uniqueReference}/completeAuthorize
POST {BaseURL}/payment/BNkk4BrkQEufPSvgf9lDwA/completeAuthorize
Header:
Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: H4sIAAAAAAA{partial omission for brevity}EAN2bJ/6l2XX+A5kJqdP+MwAA
{
"partnerReference": "DEV-SVR001-DE_CUSTID-KD97TH2FP6_CARTID-PYQRTGMCMQ_JUU3N9212BS",
"authorizationToken": "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01",
"localDate": "2018-10-15",
"localTime": "155550"
}
The transaction authorization is identified by the "uniqueReference" and "authorizationToken" returned initially by the API method 1.38 Init Authorize. Instead of saving these variables on your server-side, pass them via the query string parameters in the "callbackURL".
In some cases e.g., where the user's device loses internet connectivity, the redirect to the specified "callbackURL" does not take place. To prevent the transaction expiring despite it being successful, the API method 1.39 Complete Authorize should automatically be called from your backend 28 minutes after 1.38 Init Authorize has been called, and the payment process completed.
Complete Authorization Response
Status Code:
200 (OK)
Header:
Content-Type: application/json
Accept-Language: en-US
{
"initiatorAccno": "1679541175",
"accno": "1679797975",
"uniqueReference": "BNkk4BRkQEufPSvgf9lDwA",
"initiationCountryCode": "DE",
"initiationCountryCode3": "DEU",
"storedPaymentOptionReference": "8ac7a4a266aab3ce0166c0602bf26dae",
"processedAmount": 3.99,
"processedCurrCode": "EUR",
"statusCode": "AUTHORIZED",
"statusReason": "Request successfully processed in 'Merchant in Integrator Test Mode'",
"paymentProviderResponse": {
"id": "8ac7a4a26668b22f0166780ef9b571d1",
"paymentType": "PA",
"paymentBrand": "VISA",
"amount": "3.99",
"currency": "EUR",
"descriptor": "BNkk4BRkQEufPSvgf9lDwA",
"merchantTransactionId": "BNkk4BRkQEufPSvgf9lDwA",
"result": {
"code": "000.100.110",
"description": "Request successfully processed in 'Merchant in Integrator Test Mode'"
},
"card": {
"bin": "402400",
"last4Digits": "9550",
"holder": "Jacob Smith",
"expiryMonth": "04",
"expiryYear": "2022"
},
"customer": {
"ip": "123.123.123.123"
},
"threeDSecure": {
"eci": "06"
},
"customParameters": {
"SHOPPER_EndToEndIdentity": "a3eb5306fcaee2ffb589204ffdc9819ec5f29bd5853923e38adef0aa106e1680",
"CTPE_DESCRIPTOR_TEMPLATE": "${TRANSACTION_ID}"
},
"risk": {
"score": "0"
},
"buildNumber": "b5487567b639c21ffd60a5f42c484f3276ff93b3@2018-10-11 13:50:52 +0000",
"timestamp": "2018-10-15 14:08:59+0000",
"ndc": "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01"
},
"partnerReference": "DEV-SVR001-DE_CUSTID-KD97TH2FP6_CARTID-PYQRTGMCMQ_JUU3N9212BS",
"localDate": "2018-10-15",
"localTime": "160910",
"sysDate": "2018-10-15",
"sysTime": "140910",
"responseCode": "0000",
"responseDescription": "Successful execution",
"additionalInformation": {
"requestId": "aff2728481a181dc36daedc14055b516"
}
}
Note, that the 1.39 Complete Authorize response includes the internal representation of the Account Number indicated by the parameter Account Number Type.
The response includes the Transaction Status under the return parameter "statusCode", which at this point should be set to "AUTHORIZED" and indicates that the payment was authorized.
Please note if "responseCode": "0035" is returned this indicates the transaction is already "Authorized" and it should be treated as a Successful Response. This can occur if 1.39 Complete Authorize is called twice, or if the authorization was automatically completed 28 minutes after 1.38 Init Authorize. In such a case it is safe to continue with 1.29 Capture.