Skip to main content

Credit/Debit Card

Authorization Credit Debit Card

  1. Initiate Authorization
  2. Collect Payment Option Details via SDK
  3. Issuing Bank Authorizes Payment
  4. Complete Authorization

1. Initiate Authorization​

Pay.ON​

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 a VISA credit card as part of the purchase of two premium widgets from Widgets GmbH. The shopper's full name is provided alongside their address.

note

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",
    "paymentOptionCode": "VISA",
    "presentationAmount": 3.99,
    "presentationCurrCode": "EUR",
    "presentationUsage": "Purchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95.",
    "useDifferentBillingAddress": true,
    "customerFullName": "Jacob Smith",
    "emailAddress": "user@example.com",
    "addr1":"Anystreet",
    "houseNumber":"321",
    "city":"Anycity",
    "countryCode":"DE",
    "postCode":"12345",
    "localDate": "2018-10-15",
    "localTime": "155107",
    "custom1": "WVWZZZ3BZWE689725"
}

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.

note

In line with Strong Customer Authentication (SCA), it is now required that real customer information be accurately provided - i.e., "useDifferentBillingAddress" must be set to true, making the below parameters mandatory:

  • customerFullName
  • addr1
  • houseNumber (if not included in "addr1")
  • city
  • postCode
  • countryCode

It is advised that "emailAddress" also be provided, with accurate customer data.

Please discuss with you business contacts when providing accurate data may not be possible in production, as it may result in transactions being rejected.

More information on Mandatory and Optional parameters can be found in the 3D-Secure v2.x Requirements section.

note

If the value of "countryCode" is "US" (United States of America) or "CA" (Canada) the "state" parameter is required. The value of "state" must be a valid State Code. (ex. "countryCode": "US", "state": "NY",)

note

The maximum character length of the presentation usage (see variable presentationUsage in the example above) varies between payment options. It may be that with certain payment options the specified presentation usage may be less than 127 and consequently be truncated. It would thus be strongly recommended that the most pertinent information be placed at the beginning of the presentation usage. To be compatible with most payment options we suggest that the presentation usage already be truncated at the 22nd character.

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",
    "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. 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 the Acquirer. 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).

info

The example below shows only the relevant part of the KC Web SDK implementation for Guest Payments with credit card. A complete and detailed description of the 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 option details collected via the Web SDK with the transaction.

Collect Payment Option Details via KC Web SDK​

cw.PaymentForm(container,
{
  authorizationToken: "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01",
  callbackUrl: "https://www.example.com/Checkout/CompleteOrder",
  confirmationUrl: "https://www.example.com/ConfirmOrder",
  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 Authorization, specify all allowed credit card providers in the SDK (e.g., paymentOptionCodes: ["VISA","MSTRCRD","AMEX"]). Hence, the credit card scheme will be auto detected on the basis of the entered credit card number.

The "confirmationURL" can be replaced with the desired URL which will display the payment confirmation page. Note, that in most cases the display of a payment confirmation page is not mandatory (see 3. Payment Confirmation Page for further information). Do not specify a "confirmationURL" to skip this step.

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 5. Complete Authorization).

note

Note, that authorization token is attached to the "callbackUrl" (as query string parameter "id") and the "confirmationUrl" (as query parameter "authorizationToken"). This approach avoids having to persist this variable on the server side and is thus recommended practice.

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 "confirmationURL" or "callbackURL", respectively.

Payment Confirmation Page​

The Payment Confirmation Page enables the collection of payment details prior to the payment i.e., allowing the shopper to review their purchase details prior to finally committing to the payment.

info

Depending on your location, the display of a payment confirmation page may be mandatory. Please seek assistance by contacting legal counsel should you be unsure of the legal requirements in your country. Do not specify a "confirmationURL" to skip the confirmation page.

You can integrate the payment confirmation button in a few lines of client-side code.

Payment Confirmation Page Example​

<form id="confirmation">
    <button type="submit">Pay now</button> <!-- confirmation button -->
<form>
  
<script src="cwPaymentForm-5.3.1.js"></script> <!-- add cwPaymentForm script -->
  
<script type="text/javascript">
    var form = document.getElementById("confirmation"); // Find a confirmation form  
    try {
    // Configure the confirmation form
        cw.PaymentConfirmation(form, {
            paymentProviderMode: "test" // use "live" for a release version
        });
    } catch (e) {
        document.write(e);
        console.log(e);
    }
</script>

The embedded form in the body of your HTML site will create a confirmation button. The forwarded authorization token in the "confirmationUrl" (as query parameter "authorizationToken") associates the payment confirmation page with the payment option details previously collected via the KC Web SDK.

info

If 3-D Secure is supported, the shopper will be redirected to complete the 3-D Secure Authentication process as soon as they click the button labelled "PAY NOW" on the Payment Confirmation Page.

info

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. Issuing Bank Authorizes Payment​

The acquiring bank transmits the data to the issuing bank via the card scheme. Based on the validity of the card, the transaction, as well as the cardholder's available funds, the credit card issuer can approve or decline the transaction. If the transaction is authorized, the respective amount is blocked on the credit card and is no longer available for other charges. Afterwards, the acquirer receives an authorization response.

With the payment option details collected and the payment authorized, the shopper is redirected to the previously specified "callbackURL".

4. 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: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=
{
    "partnerReference": "DEV-SVR001-DE_CUSTID-KD97TH2FP6_CARTID-PYQRTGMCMQ_JYFGRFTQXM",
    "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".

note

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",
    "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_JYFGRFTQXM",
    "localDate": "2018-10-15",
    "localTime": "160910",
    "sysDate": "2018-10-15",
    "sysTime": "140910",
    "responseCode": "0000",
    "responseDescription": "Successful execution",
    "additionalInformation": {
        "requestId": "aff2728481a181dc36daedc14055b516"
    }
}
note

Note, that the 1.39 Complete Authorize response includes the internal representation of the Account Number indicated by the parameter Account Number Type. Additionally, the response includes the transaction status under the status code parameter, which, at this stage, should be set to AUTHORIZED, indicating that the payment has been successfully authorized.

Please also see transaction status handling for non-successful response codes.

 Imprint
|
Data protection and privacy
© 2025 J.P. Morgan Mobility Payments Systems GmbH. All rights reserved.