Credit/Debit Card
- Initiate Storing of New Payment Option
- Collect Payment Option Details via SDK
- Complete Storing of New Payment Option
1. Initiate Storing of New Payment Option
Pay.ON
The storing of a new payment option is initialized by calling the API method 1.53 Init Add Stored Payment Option.
In the example below, we initiate the storing of a VISA payment option for the account number KDNR0001.
Initiate Storing of New Payment Option Request
Path:
POST {baseURL}/account/{accno}/storedPaymentOptions/initAdd
POST {baseURL}/account/KDNR0001/storedPaymentOptions/initAdd
Header:
Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=
{
"partnerReference": "DEV-SVR001-DE_CUSTID-QKG4JMVBQY_CARTID-F8Y8V3W9JT_7P6F92RY4P",
"programCode": "COMPANYDE",
"accnoType": "00",
"paymentOptionCode": "VISA",
"useDifferentBillingAddress":true,
"customerFullName": "Jacob Smith",
"emailAddress": "user@example.com",
"addr1":"Anystreet",
"houseNumber":"321",
"city":"Anycity",
"countryCode":"DE",
"postCode": "12345",
"localDate": "2018-11-11",
"localTime": "025727"
}
In the case of a credit card payments, it is possible to omit the payment option code. The SDK will auto detect the credit card provider on the basis of the entered credit card number.
Initiate Storing of New Payment Option Response
Status Code:
201 (Created)
Header:
Content-Type: application/json
Accept-Language: en-US
{
"accno": "KDNR0001",
"authorizationToken": "BFADEC6590EFAF8B5368C2D8DC5DC83A.uat01-vm-tx04",
"paymentOptionCode": "VISA",
"paymentProviderResponse": {
"result": {
"code": "000.200.100",
"description": "successfully created checkout"
},
"buildNumber": "a8c8de953a4fb1b1bcf1daf162a485c02ad4f9f2@2018-11-07 11:53:45 +0000",
"timestamp": "2018-11-11 01:57:28+0000",
"ndc": "BFADEC6590EFAF8B5368C2D8DC5DC83A.uat01-vm-tx04",
"id": "BFADEC6590EFAF8B5368C2D8DC5DC83A.uat01-vm-tx04"
},
"programCode": "COMPANYDE",
"partnerReference": "DEV-SVR001-DE_CUSTID-QKG4JMVBQY_CARTID-F8Y8V3W9JT_7P6F92RY4P",
"localDate": "2018-11-11",
"localTime": "025727",
"sysDate": "2018-11-11",
"sysTime": "015728",
"responseCode": "0000",
"responseDescription": "Successful execution",
"additionalInformation": {
"requestId": "aff2728481a181dc36daedc14055b516"
}
}
The response includes the desired authorization token under the return parameter "authorizationToken" which is needed to complete the storing of the payment option in further steps.
2. Collect Payment Option Details via SDK
Pay.ON
The SDK renders a customizable payment form and sends the entered payment details directly from the customer's browser to us. This prevents, that you must fulfill the comprehensive requirements of the PCI DSS. 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 for storing a credit card payment option. A complete and detailed description of the KC Web SDK can be found here.
The KC Web SDK is used to securely collect the payment option details. The authorization token returned by the API method 1.53 Init Add Stored Payment Option which initiated the storing is used to associate the payment option details collected via the KC Web SDK with the storing process.
Collect Payment Option Details via KC Web SDK
cw.PaymentForm(container,
{
authorizationToken: "BFADEC6590EFAF8B5368C2D8DC5DC83A.uat01-vm-tx04",
callbackUrl: "https://www.example.com/StoredPaymentOptions/CompleteAdd",
paymentOptionCodes: ["VISA"],
locale: "en-US",
paymentProviderMode: "test",
submitButtonTitle: "Continue",
onError: function(message)
{
console.log(message);
}
}
);
In the case of an omitted Payment Option Code in step 1. Initiate Storing of New Payment Option, specify all allowed credit card providers in the SDK (e.g., paymentOptionCodes: ["VISA","MSTRCRD","AMEX"]). Hence, the credit card provider will be auto detected on the basis of the entered credit card number.
The "callbackURL" should be replaced with the URL identifying the server side method which will call the next API method to complete the authorization (see 3. Complete Storing of New Payment Option).
After the shopper submits the payment form by clicking the button labeled with the value of "submitButtonTitle" (see example above), he is redirected to the specified "callbackURL.
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 Storing of New Payment Option
Pay.ON
Since the SDK sends the payment option details directly to us, you have no knowledge about the current status of the storing process and if it got authorized. Therefore, call the API method 1.54 Complete Add Stored Payment Option from your server side method behind the "callbackURL", which you specified in the SDK.
Note, that authorization token is attached to the "callbackUrl" (as query string parameter "id"). This approach avoids having to persist this variable on the server side and is thus recommended practice.
Complete Storing of New Payment Option Request
Path:
PUT {baseURL}/account/KDNR0001/storedPaymentOptions/completeAdd
Header:
Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=
{
"partnerReference": "DEV-SVR001-DE_CUSTID-YT99V39D2H_CARTID-RQ4WHY8DYC_P96KTG7VYC",
"programCode": "COMPANYDE",
"accnoType": "00",
"paymentOptionCode": "VISA",
"authorizationToken": "BFADEC6590EFAF8B5368C2D8DC5DC83A.uat01-vm-tx04",
"useDifferentBillingAddress": false,
"localDate": "2018-11-11",
"localTime": "030047"
}
In some cases (ex. where the user's device loses internet connectivity) the redirect to the specified "callbackUrl" does not take place. To prevent the storing from expiring despite it being successful, the API method 1.54 Complete Add Stored Payment Option should be called automatically from your backend 28 minutes after 1.53 Init Add Stored Payment Option has been called.
Complete Storing of New Payment Option Response
Status Code:
200 (OK)
Header:
Content-Type: application/json
Accept-Language: en-US
{
"accno": "KDNR0001",
"paymentOptionCode": "VISA",
"storedPaymentOptionReference": "8ac7a49f66f2d5ae0167007fa0b17970",
"initiationCountryCode": "DE",
"initiationCountryCode3": "DEU",
"paymentProviderResponse": {
"id": "8ac7a4a166f2d5ae0167007fa529140e",
"registrationId": "8ac7a49f66f2d5ae0167007fa0b17970",
"paymentType": "PA",
"paymentBrand": "VISA",
"amount": "0.01",
"currency": "EUR",
"descriptor": "",
"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": "4b3856c6b0213210b7e027d11924ee70bcca7791db29dae62af987dff467840f",
"CTPE_DESCRIPTOR_TEMPLATE": "${TRANSACTION_ID}"
},
"risk": {
"score": "0"
},
"buildNumber": "a8c8de953a4fb1b1bcf1daf162a485c02ad4f9f2@2018-11-07 11:53:45 +0000",
"timestamp": "2018-11-11 02:00:25+0000",
"ndc": "BFADEC6590EFAF8B5368C2D8DC5DC83A.uat01-vm-tx04"
},
"programCode": "COMPANYDE",
"partnerReference": "DEV-SVR001-DE_CUSTID-YT99V39D2H_CARTID-RQ4WHY8DYC_P96KTG7VYC",
"localDate": "2018-11-11",
"localTime": "030047",
"sysDate": "2018-11-11",
"sysTime": "020048",
"responseCode": "0000",
"responseDescription": "Successful execution",
"additionalInformation": {
"requestId": "aff2728481a181dc36daedc14055b516"
}
}
The "responseCode": "0000" and the responseDescription indicate that the new payment option has been successfully stored.
The storedPaymentOptionReference parameter is used to identify the tokenized payment option as part of other API methods (see section Payment Process). You can either store it on your server or retrieve it via an API call (see section Get Stored Payment Options).