Skip to main content

Apple Pay

  1. Initiate Storing of New Payment Option
  2. Collect Payment Option Details via KC UPCF Web SDK
  3. Complete Storing of New Payment Option

info

Storing Apple Pay is allowed only in case of subscriptions and unattended MIT payments.

1. Initiate Storing of New Payment Option​

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 Apple Pay payment option for account number 7228905548.

Initiate Storing of New Payment Option Request​

Path:

POST {baseURL}/account/{accno}/storedPaymentOptions/initAdd
POST {baseURL}/account/7228905548/storedPaymentOptions/initAdd

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJjb25uZW***AwMjZ2PTQifQ==
User-Agent: ***
{
  "programCode": "JPMCONS",
  "partnerReference": "e70015bf-2b69-4811-8e07-4d579915dfbe",
  "accnoType": "01",
  "criteria": [
    {
      "name": "appleMerchantDomain",
      "value": "your-shop.com"
    },
    {
      "name": "appleButtonType",
      "value": "plain"
    },
    {
      "name": "appleButtonStyle",
      "value": "black"
    }
  ],
  "paymentOptionCode": "APPLPAY",
  "localDate": "2025-01-30",
  "localTime": "100744"
}

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 Storing of New Payment Option Response​

Status Code:

201 (Created)

Header:

Content-Type: application/json
Accept-Language: en-US
{
  "accno": "7228905548",
  "authorizationToken": "eyJjb25uZW***AwMjZ2PTQifQ==",
  "paymentOptionCode": "APPLPAY",
  "paymentProviderResponse": {
    "result": {
      "kcAuthorizationToken": "eyJjb25uZW***AwMjZ2PTQifQ==",
      "providerRequestDetails": {
        "processedData": {
          "authorizationToken": "e448a0fd***c717d199f3",
          "connectorParentWebSDKUrl": "{baseURL}/static/apc_aps_main_v1.js?merchant=bWVyY2hhbnQucmVnaXN0ZXIuaW8udndmc3BheS5kZXY=&v=4"
        },
        "providerResponse": [],
        "responseCode": "0000",
        "responseDescription": "Operation succeeded.",
        "localTime": "2025-01-30T10:07:45+01:00"
      }
    },
    "responseCode": "0000",
    "responseDescription": "Operation succeeded.",
    "localDateTime": "2025-01-30T10:07:45+01:00",
    "additionalData": [
      {
        "name": "externalCalls",
        "value": [
          {
            "url": "{baseURL}/api/v1/storedPaymentOptions/initAdd",
            "httpMethod": "POST",
            "httpStatusCode": 200
          }
        ]
      }
    ]
  },
  "programCode": "JPMCONS",
  "partnerReference": "e70015bf-2b69-4811-8e07-4d579915dfbe",
  "localDate": "2025-01-30",
  "localTime": "100744",
  "sysDate": "2025-01-30",
  "sysTime": "090745",
  "responseCode": "0000",
  "responseDescription": "Successful execution.",
  "additionalInformation": {
    "requestId": "5230fbea318842eebf4d67509d389612"
  }
}

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 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 (iOS).

A complete and detailed description of the KC UPCF Web SDK can be found here.

The KC UPCF 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 UPCF Web SDK with the storing process.

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.

3. Complete Storing of New Payment Option​

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. After the onComplete callback confirms successful payment processing, you should call the API method 1.54 Complete Add Stored Payment Option from your server-side application to finalize the transaction. Merchants are responsible for defining the actions within the "onComplete" function, such as showing a confirmation page or initiating additional server-side processes.

important

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

Complete Storing of New Payment Option Request​

Path:

PUT {baseURL}/account/7228905548/storedPaymentOptions/completeAdd

Header:

Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJjb25uZW***AwMjZ2PTQifQ==
User-Agent: ***
{
  "partnerReference": "e70015bf-2b69-4811-8e07-4d579915dfbe",
  "programCode": "JPMCONS",
  "accnoType": "01",
  "paymentOptionCode": "APPLPAY",
  "authorizationToken": "eyJjb25uZW***AwMjZ2PTQifQ==",
  "criteria": [
  ],
  "localDate": "2025-01-30",
  "localTime": "100819"
}
info

There might be cases where a user's device might lose internet connectivity. 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": "7228905548",
  "paymentOptionCode": "APPLPAY",
  "storedPaymentOptionReference": "cXGhIeOS8Jm149uw2fE1s",
  "paymentProviderResponse": {
    "result": {
      "providerRequestDetails": {
        "processedData": {
          "paymentOptionToken": "6a1be729-ce40-443d-8ee4-0d59ed9c8417",
          "paymentOptionBrand": "APPLPAY",
          "carrierNumber": "481852****3553",
          "bic": "",
          "cardExpiryMonth": "01",
          "cardExpiryYear": "2030",
          "eci": "07",
          "registrationTrxReference": "8ac7a4a294b52aa20194b677e9292bb2",
          "country": "DEU",
          "holderName": {
            "fullName": "JPM-MPS-CONS GmbH"
          },
          "paymentOptionData": {
            "additionalData": [
              {
                "name": "appleMerchantDomain",
                "value": "your-shop.com"
              }
            ]
          }
        },
        "providerResponse": [
          {
            "method": "POST",
            "url": "{baseURL}/v1/payments",
            "request": "amount=0.00&currency=EUR&standingInstruction.source=CIT&standingInstruction.type=UNSCHEDULED&standingInstruction.mode=INITIAL&card.number=48185288****3553&card.expiryMonth=01&card.expiryYear=2030&threeDSecure.verificationId=AwAAAAAASHyCER0AAAAAgB5gEwA%3D&threeDSecure.eci=07&applePay.source=web&paymentBrand=APPLEPAY&entityId=8ac7a4c981ea24bf0181ee7dd2fc1e73&merchantTransactionId=cXGhIeOS8Jm149uw2fE1s&paymentType=PA",
            "response": "{\"id\":\"8ac7a4a294b52aa20194b677e9292bb2\",\"paymentType\":\"PA\",\"paymentBrand\":\"VISA\",\"amount\":\"0.00\",\"currency\":\"EUR\",\"descriptor\":\"cXGhIeOS8Jm149uw2fE1s\",\"merchantTransactionId\":\"cXGhIeOS8Jm149uw2fE1s\",\"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\":\"AwAAAAAASHyCER0AAAAAgB5gEwA=\"},\"risk\":{\"score\":\"0\"},\"buildNumber\":\"c90a4b5aa476a11b858eb7abcd8ca88b9598d315@2025-01-27 00:42:27 +0000\",\"timestamp\":\"2025-01-30 09:08:19+0000\",\"ndc\":\"8ac7a4c981ea24bf0181ee7dd2fc1e73_b2f1b60a1e4940af93caa57639f559ce\",\"standingInstruction\":{\"source\":\"CIT\",\"type\":\"UNSCHEDULED\",\"mode\":\"INITIAL\"},\"source\":\"OPP\",\"paymentMethod\":\"CC\",\"shortId\":\"5210.8213.2941\"}",
            "statusCode": "200"
          }
        ],
        "responseCode": "0000",
        "responseDescription": "Operation succeeded.",
        "localTime": "2025-01-30T10:08:19+01:00"
      }
    },
    "responseCode": "0000",
    "responseDescription": "Operation succeeded.",
    "localDateTime": "2025-01-30T10:08:20+01:00",
    "additionalData": [
      {
        "name": "externalCalls",
        "value": [
          {
            "url": "{baseURL}/api/v1/storedPaymentOptions/completeAdd",
            "httpMethod": "POST",
            "httpStatusCode": 200
          }
        ]
      }
    ]
  },
  "initiationCountryCode": "DE",
  "initiationCountryCode3": "DEU",
  "additionalData": [
    {
      "name": "appleMerchantDomain",
      "value": "your-shop.com"
    }
  ],
  "storedPaymentOptionProviderReference": "6a1be729-ce40-443d-8ee4-0d59ed9c8417",
  "programCode": "JPMCONS",
  "partnerReference": "e70015bf-2b69-4811-8e07-4d579915dfbe",
  "localDate": "2025-01-30",
  "localTime": "100819",
  "sysDate": "2025-01-30",
  "sysTime": "090820",
  "responseCode": "0000",
  "responseDescription": "Successful execution.",
  "additionalInformation": {
    "requestId": "7db06ed51fbd4d0dbda9893e94f9ab36"
  }
}

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).

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