Skip to main content

Apple Pay

  1. Initiate Authorization
  2. Collect Payment Option Details via KC UPCF Web SDK
  3. Apple Pay Checkout
  4. Complete Authorization

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 100 EUR for a Apple Pay payment as part of the purchase of two premium widgets from Widgets GmbH.

Initiate Authorization Request​

Path:

PUT {baseURL}/payment/initAuthorize

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJjb25uZW***AwMjZ2PTQifQ==
User-Agent: ***
{
  "partnerReference": "52a90ad0-b21e-4f39-bdb3-31465d221d02",
  "programAccno": "7228894817",
  "accno": "7228905548",
  "accnoType": "01",
  "presentationAmount": 100,
  "presentationCurrCode": "EUR",
  "presentationUsage": "V Purchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95.",
  "useDifferentBillingAddress": false,
  "criteria": [
    {
      "name": "appleMerchantDomain",
      "value": "your-shop.com"
    },
    {
      "name": "appleButtonType",
      "value": "check-out"
    },
    {
      "name": "appleButtonStyle",
      "value": "white"
    }
  ],
  "paymentOptionCode": "APPLPAY",
  "localDate": "2025-01-28",
  "localTime": "124746"
}
info

The parameter useDifferentBillingAddress determines whether customer account data is loaded from the technical account. If set to false, the system will automatically obtain billing address data from the technical account. If set to true, the data must be explicitly provided in the request at the root level. Below is an example demonstrating how these parameters should be structured:

  "useDifferentBillingAddress": true,
  "customerFullName": "Jacob Smith",
  "emailAddress": "user@example.com",
  "addr1": "Gotzkowskystraße 2332",
  "city": "Delbrück",
  "countryCode": "DE",
  "postCode": "33129",
  "phone": "12345678910"

Customizable Apple Pay Button​

To customize the Apple Pay button within the request, include the appleButtonType and appleButtonStyle parameters in criteria (see example above). The "type" parameter defines the text displayed on the button, such as a standard payment label or a subscription-related prompt, while "style" controls the button's visual theme to match different background and branding requirements. These parameters determine how the Apple Pay button is generated on the page, ensuring flexibility in its presentation. By specifying these attributes, merchants can align the button's appearance with their checkout flow while maintaining compliance with Apple's UI guidelines.

For more details, please refer to the Button Customization documentation.

Multiple Domains Support​

To support multiple merchant domains for Apple Pay, the request can include the appleMerchantDomain parameter within the criteria object (also listed in the example above). This parameter enables merchants to specify additional domain where the Apple Pay button can be displayed, provided they have been whitelisted with Apple. Please refer to the Apple Pay page for more details.

Initiate Authorization Response​

Status Code:

200 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US
{
  "programAccno": "7228894817",
  "accno": "7228905548",
  "uniqueReference": "VWeOY7GRMbsv9THdqnenL",
  "loadAccountReference": "6VG2OK9Cf65qGrbbsiXCu",
  "authorizationToken": "eyJjb25uZW***AwMjZ2PTQifQ==",
  "paymentOptionCode": "APPLPAY",
  "presentationAmount": 100,
  "presentationCurrCode": "EUR",
  "presentationUsage": "V Purchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95.",
  "statusCode": "RECEIVED",
  "statusReason": "Successful transaction request.",
  "paymentProviderResponse": {
    "result": {
      "kcAuthorizationToken": "eyJjb25uZW***AwMjZ2PTQifQ==",
      "providerRequestDetails": {
        "processedData": {
          "authorizationToken": "e804b***d7c4",
          "connectorParentWebSDKUrl": "{baseURL}/static/apc_aps_main_v1.js?merchant=bWVyY2hhb...XY=&v=4",
          "transactionData": {
            "reference": "VWeOY7GRMbsv9THdqnenL",
            "providerReference": "",
            "amount": 100,
            "currency": "EUR",
            "country": "",
            "status": "RECEIVED",
            "statusReason": "Successful transaction request."
          }
        },
        "providerResponse": [],
        "responseCode": "0000",
        "responseDescription": "Operation succeeded.",
        "localTime": "2025-01-28T12:47:47+01:00"
      }
    },
    "responseCode": "0000",
    "responseDescription": "Operation succeeded.",
    "localDateTime": "2025-01-28T12:47:48+01:00",
    "additionalData": [
      {
        "name": "externalCalls",
        "value": [
          {
            "url": "{baseURL}/api/v1/payment/initAuthorize",
            "httpMethod": "POST",
            "httpStatusCode": 200
          }
        ]
      }
    ]
  },
  "partnerReference": "52a90ad0-b21e-4f39-bdb3-31465d221d02",
  "localDate": "2025-01-28",
  "localTime": "124746",
  "sysDate": "2025-01-28",
  "sysTime": "114748",
  "responseCode": "0000",
  "responseDescription": "Successful execution.",
  "additionalInformation": {
    "requestId": "a2e7726abe7a45b4b1529b8bc2c649dd"
  }
}

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.

important

Please use the "authorizationToken" from the root level of the response, as other instances within nested structures are for internal purposes and should not be used for further API calls.

2. Collect Payment Option Details via KC UPCF Web SDK​

The KC UPCF Web SDK renders the customizable Apple Pay button, which can be customized in the previous step, and transmits all necessary payment details to start the Apple Pay Checkout flow. We offer SDKs for integration into websites as well as mobile applications (iOS).

info

The example below shows only the relevant part of the KC UPCF Web SDK implementation for Guest Payments with Apple Pay. A complete and detailed description of the KC UPCF Web SDK can be found here.

Example code to handle KC UPCF Web SDK for Apple Pay button:

window.kc.webSdk.PaymentForm(container, {
  authorizationToken,
  callbackUrl: `${window.location.origin}${completedOrder}`,
  paymentOptionCodes: ['APPLPAY'],
  locale: "en-US",
  paymentProviderMode: "test",
  submitButtonTitle: "buy",
  onError: function (message) {
    // handle errors
  },
  onComplete: function () {
    // handle apple authorization
  }
})

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 KC UPCF Web SDK with the transaction.

3. Apple Pay Checkout​

In the Checkout, Apple Pay displays a pop-up that shows all the credit card options that are available in Apple Pay.

Following this, the user sees the confirmation screen, the chosen payment option and the amount to be authorized. Clicking the cart symbol displays the payment details (see parameter "presentationUsage" in the Initiate Authorization Request).

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.

After confirming the payment with the Apple Pay button, the KC UPCF Web SDK triggers the onComplete function. This function is called upon successful payment processing, and merchants are responsible for defining what happens next. This can include displaying a confirmation message or redirecting the shopper to a success page. Please note that the KC UPCF Web SDK does not handle redirection automatically; any navigation must be implemented within the "onComplete" function.

important

Merchants should implement appropriate handling in the onComplete and onError callbacks to manage the user experience, such as retrying the process for errors or confirming the success of the transaction.

info

Only VISA and Mastercard payment options are supported.

Apple Pay Button

important

The payment can be done only on Apple devices.

info

The payment can be confirmed using the passcode or fingerprint.

4. Complete Authorization​

Since the KC UPCF Web SDK sends the payment details directly to Apple Pay, where the payment is subsequently processed, you have no direct visibility into the payment’s real-time authorization status. "onComplete" within the SDK indicates that the frontend component has successfully finished; however, this does not mark the final success of the payment.

important

Please note that KC UPCF Web SDK does not handle any redirection; it must be implemented in your custom logic.

After the onComplete callback confirms successful payment processing, you should call the API method 1.39 Complete Authorize from your server-side application to finalize the transaction. A the payment is only considered fully successful once it has been successfully authorized, meaning the 1.39 Complete Authorize API response returns "responseCode": "0000" or the status is Authorized or Captured. Please also see transaction status handling for non-successful response codes.

Merchants are responsible for defining the actions within the "onComplete" function, such as showing a confirmation page or initiating additional server-side processes.

Complete Authorization Request​

Path:

POST {baseURL}/payment/{uniqueReference}/completeAuthorize
POST {baseURL}/payment/VWeOY7GRMbsv9THdqnenL/completeAuthorize

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJjb25uZW***AwMjZ2PTQifQ==
User-Agent: ***
{
  "partnerReference": "52a90ad0-b21e-4f39-bdb3-31465d221d02",
  "authorizationToken": "eyJjb25uZW***AwMjZ2PTQifQ==",
  "localDate": "2025-01-28",
  "localTime": "125112"
}
note

The transaction authorization is identified by the "uniqueReference" and "authorizationToken" returned initially by the API method 1.38 Init Authorize.

Complete Authorization Response​

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US
{
  "initiatorAccno": "7228894817",
  "accno": "7228905548",
  "uniqueReference": "VWeOY7GRMbsv9THdqnenL",
  "processedAmount": 100.00,
  "processedCurrCode": "EUR",
  "statusCode": "AUTHORIZED",
  "statusReason": "Authorization request has been approved by Acquirer/Payment provider and transaction can be requested for Capture.",
  "paymentProviderResponse": {
    "result": {
      "providerRequestDetails": {
        "processedData": {
          "paymentOptionBrand": "APPLPAY",
          "carrierNumber": "481852****3553",
          "bic": "",
          "cardExpiryMonth": "01",
          "cardExpiryYear": "2030",
          "eci": "07",
          "transactionData": {
            "reference": "VWeOY7GRMbsv9THdqnenL",
            "providerReference": "8ac7a49f94a9c5c40194acc0524f057c",
            "amount": 100.00,
            "currency": "EUR",
            "country": "",
            "status": "AUTHORIZED",
            "statusReason": "Authorization request has been approved by Acquirer/Payment provider and transaction can be requested for Capture."
          },
          "customerName": {
            "fullName": "Demo Admin",
            "firstName": "Demo",
            "lastName": "Admin"
          }
        },
        "providerResponse": [
          {
            "method": "POST",
            "url": "{baseURL}/v1/payments",
            "request": "amount=100&currency=EUR&card.number=48185288****3553&card.expiryMonth=01&card.expiryYear=2030&threeDSecure.verificationId=AwAAAAAAPtAYkWQAAAAAgBxgEwA%3D&threeDSecure.eci=07&applePay.source=web&paymentBrand=APPLEPAY&entityId=8ac7a4c981ea24bf0181ee7dd2fc1e73&merchantTransactionId=VWeOY7GRMbsv9THdqnenL&paymentType=PA",
            "response": "{\"id\":\"8ac7a49f94a9c5c40194acc0524f057c\",\"paymentType\":\"PA\",\"paymentBrand\":\"VISA\",\"amount\":\"100\",\"currency\":\"EUR\",\"descriptor\":\"VWeOY7GRMbsv9THdqnenL\",\"merchantTransactionId\":\"VWeOY7GRMbsv9THdqnenL\",\"result\":{\"code\":\"000.100.110\",\"description\":\"Request successfully processed in 'Merchant in Integrator Test Mode'\"},\"card\":{\"bin\":\"481852\",\"last4Digits\":\"3553\",\"expiryMonth\":\"01\",\"expiryYear\":\"2030\"},\"threeDSecure\":{\"eci\":\"07\",\"verificationId\":\"AwAAAAAAPtAYkWQAAAAAgBxgEwA=\"},\"risk\":{\"score\":\"0\"},\"buildNumber\":\"c90a4b5aa476a11b858eb7abcd8ca88b9598d315@2025-01-27 00:42:27 +0000\",\"timestamp\":\"2025-01-28 11:51:12+0000\",\"ndc\":\"8ac7a4c981ea24bf0181ee7dd2fc1e73_1427999ee31245c6bf3a9ecb0cdd10b4\",\"source\":\"OPP\",\"paymentMethod\":\"CC\",\"shortId\":\"6970.4105.1341\"}",
            "statusCode": "200"
          }
        ],
        "responseCode": "0000",
        "responseDescription": "Operation succeeded.",
        "localTime": "2025-01-28T12:51:13+01:00"
      }
    },
    "responseCode": "0000",
    "responseDescription": "Operation succeeded.",
    "localDateTime": "2025-01-28T12:51:13+01:00",
    "additionalData": [
      {
        "name": "externalCalls",
        "value": [
          {
            "url": "{baseURL}/api/v1/payment/completeAuthorize",
            "httpMethod": "POST",
            "httpStatusCode": 200
          }
        ]
      }
    ]
  },
  "partnerReference": "52a90ad0-b21e-4f39-bdb3-31465d221d02",
  "localDate": "2025-01-28",
  "localTime": "125112",
  "sysDate": "2025-01-28",
  "sysTime": "115113",
  "responseCode": "0000",
  "responseDescription": "Successful execution.",
  "additionalInformation": {
    "requestId": "b1c42c27038d4c4784a9bca7b94f6d9c"
  }
}
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.