# Accept payments with Apple Pay

> Learn how to accept payments with Apple Pay through API-only integration.

 Through the  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md)  service, buyers can make payments using the credit or debit cards stored in their  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md)  accounts.       When using the Native API method, the merchant frontend needs to directly integrate the  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md)  SDK. After obtaining the card asset information, call Antom’s   [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md)  API to initiate the payment. For details on integrating the  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md)  SDK, refer to   [Apple Pay on the Web](https://developer.apple.com/documentation/applepayontheweb)   or   [Apple Pay (Native)](https://developer.apple.com/documentation/passkit/setting-up-apple-pay?language=objc)  .

 > **[INFO]** **Note**    :    When integrating  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md)  using the Native API method, you need to have your own Apple merchant identifier and certificate. For the  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md)  Web integration method, merchants must complete   [domain verification](https://developer.apple.com/help/account/capabilities/configure-apple-pay-on-the-web)   on Apple’s side.

## **User experience** {#esj7b}

 The following figures demonstrate the user experience of paying with  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md) :

<!-- TabGroup -->

**Tab: Web**

![Web user experience for buyers completing payment with Apple Pay through APM API-only integration](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2025/png/7fefda7b-9883-4871-8e5c-b0c459232301.png)

**Tab: Mobile**

![Mobile user experience for buyers completing payment with Apple Pay through APM API-only integration](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/13387e3b-8dcb-40dd-a03c-044d69e34d83.png)

<!-- /TabGroup -->

## Integration preparations {#BqMj6}

 Before you start integrating, read the   [Integration Guide](https://docs.antom.com/integration_guide_en.md)   and   [API Overview](https://docs.antom.com/ac/ams/api_fund.md)   documents to understand the integration steps of the server-side API and the precautions for calling the API. Furthermore, ensure that the following prerequisites are met:

 - Obtain a client ID
- Complete the key configuration
- Complete the configuration of        *paymentNotifyUrl*        to receive the asynchronous notification
- Integrate the server-side SDK package, install the server-side library, and initialize a request instance. For more details, refer to   [Server-side SDKs](https://docs.antom.com/ac/sdks/server_sdks.md)  .

## Integration Steps {#ILjTF}

 Follow these steps to start the integration:

 1. Decrypt     *ApplePayPaymentToken*
2. Initiate an authorized payment
3. Obtain the authorization result
4. Capture

### Step 1: Decrypt ApplePayPaymentToken {#RO8WX}

 When the buyer completes  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md)  payment authorization using Touch ID, Face ID, or a passcode, the frontend obtains     *ApplePayPaymentToken*     in the  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md)  authorization event.       For details, refer to      `[onpaymentauthorized (Web](https://developer.apple.com/documentation/applepayontheweb/applepaysession/onpaymentauthorized)  )`  or  `[paymentAuthorizationViewController:didAuthorizePayment:handler: (Native](https://developer.apple.com/documentation/passkit/pkpaymentauthorizationviewcontrollerdelegate/paymentauthorizationviewcontroller(_:didauthorizepayment:handler:)?language=objc)  )`   **.**     After you obtain     *ApplePayPaymentToken*    , you can choose one of the following methods to decrypt the token and call the   [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md)      API to initiate an authorized payment request.

 - Hosted    decryption: Antom manages certificates and performs decryption on your behalf, so you do not need to be PCI-qualified.
- Merchant    decryption: You manage your own certificates and perform decryption operations yourself, and this mode requires that you are PCI-qualified.

 > **[INFO]** **Note**    :    For more information about PCI DSS compliance requirements, see   [PCI DSS standard](https://www.pcisecuritystandards.org/)  .

### Step 2: Initiate an authorized payment   **[Server-side]** {#UaYcL}

 The parameters required for initiating an authorized payment differ depending on the decryption method used. Refer to the corresponding instructions based on the decryption method you adopt.

<!-- TabGroup -->

**Tab: Hosted decryption**

The following illustrates the payment flow for Antom-hosted decrypted     *ApplePayPaymentToken*    ：

 ![Payment flow for Antom-hosted decrypted ApplePayPaymentToken across merchant client, merchant server, Apple Pay SDK and Antom server](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/c94f7dcf-9890-4e72-839b-75723058aa49.png) After y   ou obtain     *ApplePayPaymentToken*     and delegate its decryption to Antom, use Antom’s card authorization payment capability to initiate the payment. You can pass the decrypted     *ApplePayPaymentToken*     through the     *paymentMethod.paymentMethodMetaData.applePayConfiguration*     parameter in the   [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md)   API.

 Before using hosted decryption for     *ApplePayPaymentToken*    , you need to complete the certificate exchange process. Generate a Payment Processing Certificate according to Antom’s standard and provide it to Antom for configuration. The steps are as follows:

 1. ​   When generating the CSR, you need to specify the DN values to Antom CN (Common Name). The CN (Common Name) is typically used to identify the organization name or project name.

   - L: Locality name
  - ST: State or province name
  - O: Organization name   , typically the company’s legal name.
  - (Optional) OU: Organizational unit name
  - C: Country name

 2. Antom generates the CSR certificate and delivers it to you. You then uploads the CSR to   [Apple Developer](https://developer.apple.com/help/account/capabilities/configure-apple-pay)  , downloads the Payment Processing Certificate with .CER suffix, and then sends it to Antom.
3. Antom completes the configuration after obtaining the CER file.

 If you have any questions, contact Antom SA for support.

 > **[INFO]** **Note**    : When using this integration method, pay attention to the expiration time of the CER certificate, and contact Antom Technical Support (  [TechnicalService@antom.com](mailto:TechnicalService@antom.com)  ) at least one month before the certificate expires to complete the certificate renewal.

 Follow   [Step 1: Initiate an authorized payment](https://docs.antom.com/ac/cashierpay/cardinfocallmerchant.md#z5Nqg)   to call the   [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md)   API and submit the payment request. You need to pass in the basic parameters, order parameters, and device parameters in the payment request. While you do not need to pass in card payment parameters, you need to pass in the following parameters:

 | **Parameter name** | **Required** | **Description** |
| --- | --- | --- |
| *paymentMethod.paymentMethodType* | Yes | Payment method enumeration values. For  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md) , pass in   `APPLEPAY`  . |
| *paymentMethod.paymentMethodMetaData.applePayConfiguration.applePayToken* | Yes | Pass in     *ApplePayPaymentToken*     you obtained. |

 For more information about the parameters used to initiate an authorized payment, refer to   [Step 1: Initiate an authorized payment](https://docs.antom.com/ac/cashierpay/cardinfocallmerchant.md#z5Nqg)  .

 The following sample code shows how to call the   [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md)      API:

 ```java
public static void payByApplePayServer2Server() {
   AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
        alipayPayRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);

        // replace with your paymentRequestId
        String paymentRequestId = UUID.randomUUID().toString();
        alipayPayRequest.setPaymentRequestId(paymentRequestId);

        // set amount
        Amount amount = Amount.builder().currency("SGD").value("4200").build();
        alipayPayRequest.setPaymentAmount(amount);

        // set paymentMethod
        PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("APPLEPAY").build();
        alipayPayRequest.setPaymentMethod(paymentMethod);

        // set ApplePay related parameters-hosted decryption
        Map<String, String> applePayToken = new HashMap<String, String>();
        applePayToken.put("applePayToken", "{\"paymentData\":{....}");
        paymentMethodMetaData.put("applePayConfiguration", applePayToken);
        paymentMethod.setPaymentMethodMetaData(paymentMethodMetaData);
  
        // replace with your orderId
        String orderId = UUID.randomUUID().toString();

        // set buyer info
        Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

        // set order info
        Order order = Order.builder().referenceOrderId(orderId)
                .orderDescription("antom testing order").orderAmount(amount).buyer(buyer).build();
        alipayPayRequest.setOrder(order);

        // set env info
        Env env = Env.builder().terminalType(TerminalType.WEB).clientIp("1.2.3.4").build();
        alipayPayRequest.setEnv(env);

        // replace with your notify url
        alipayPayRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");

        // replace with your redirect url
        alipayPayRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");

    // pay
    AlipayPayResponse alipayPayResponse = null;
    try {
        alipayPayResponse = CLIENT.execute(alipayPayRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}
```

 The following shows the sample code of a request:

 ```json
{
	...........

  "paymentMethod": {
      "paymentMethodType": "APPLEPAY",
      "paymentMethodMetaData": {
        "applePayConfiguration":{
          "applePayToken": "{\"paymentData\":{\"data\":\"a9+mMMEXE5iIL***\",\"signature\":\"MIAGCSqGSIb***\",\"header\":{\"publicKeyHash\":\""Ch94ASjh***\"",\"ephemeralPublicKey\":\"MFkwEw****\",\"transactionId\":\"940bf1714c***\"},\"version\":\"EC_v1\"},\"paymentMethod\":{\"displayName\":\"Visa 0869\",\"network\":\"Visa\",\"type\":\"debit\"},\"transactionIdentifier\":\"940bf17****\"}"
        }
      },
    },

	...........

}
```

 For the complete sample code, refer to   [Step 1: Initiate an authorized payment](https://docs.antom.com/ac/cashierpay/cardinfocallmerchant.md#z5Nqg)  .

**Tab: Merchant decryption**

The following illustrates the payment flow merchant-decrypted     *ApplePayPaymentToken*    ： ![Payment flow for merchant-decrypted ApplePayPaymentToken across merchant client, merchant server, Apple Pay SDK and Antom server](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2026/png/49a1fb9a-20b0-44f0-bd8c-c44180d61659.png)

 After you obtain        *ApplePayPaymentToken*    ,    decrypt it according to  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md) ’s      [Payment token format reference](https://developer.apple.com/documentation/PassKit/payment-token-format-reference)      to retrieve the DPAN information. Once you have obtained the DPAN information, use Antom’s card authorized payment capability to initiate the payment.       For more information about the parameters used to initiate an authorized payment, refer to   [Step 1: Initiate an authorized payment](https://docs.antom.com/ac/cashierpay/cardinfocallmerchant.md#z5Nqg)  .

 > **[INFO]** **Note**    : Using this mode requires that you are PCI-qualified.

 The following are key parameters for initiating a authorized payment request:

 | **Parameter name** | **Required** | **Description** |
| --- | --- | --- |
| *paymentMethod.paymentMethodType* | Yes | Payment method enumeration values. For  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md) , pass in   `APPLEPAY`  . |
| *paymentMethod.paymentMethodMetaData.cardNo* | Yes | Pass in the value of the     *applicationPrimaryAccountNumber*     parameter         from the obtained DPAN information. |
| *paymentMethod.paymentMethodMetaData.expiryMonth* | Yes | Pass in the month value of the     *applicationExpirationDate*     parameter from the obtained DPAN information. |
| *paymentMethod.paymentMethodMetaData.expiryYear* | Yes | Pass in the year value of the     *applicationExpirationDate*     parameter from the obtained DPAN information. |
| *mpiData.cavv* | No | Pass in the value of the     *paymentData.onlinePaymentCryptogram*     parameter         from the obtained DPAN information. |
| *mpiData.eci* | No | Pass in the value of the     *paymentData.eciIndicator*     parameter         from the obtained DPAN information. |

 The following sample code shows how to call the   [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md)      API:

 ```java
public static void payByApplePayServer2Server() {
   AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
        alipayPayRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);

        // replace with your paymentRequestId
        String paymentRequestId = UUID.randomUUID().toString();
        alipayPayRequest.setPaymentRequestId(paymentRequestId);

        // set amount
        Amount amount = Amount.builder().currency("SGD").value("4200").build();
        alipayPayRequest.setPaymentAmount(amount);

        // set paymentMethod
        PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("APPLEPAY").build();
        alipayPayRequest.setPaymentMethod(paymentMethod);

        // set ApplePay related parameters-merchant decryption
        Map<String, Object> paymentMethodMetaData = new HashMap<String, Object>();
        paymentMethodMetaData.put("cardNo", "***********");
        paymentMethodMetaData.put("expiryMonth", "11");
        paymentMethodMetaData.put("expiryYear", "30");

        MpiData mapiDate=new MpiData();
        mapiDate.setCavv("Af9**********A=");
        mapiDate.setEci("5");
        paymentMethodMetaData.put("mpiData",mapiDate);
        paymentMethod.setPaymentMethodMetaData(paymentMethodMetaData);

        // replace with your orderId
        String orderId = UUID.randomUUID().toString();

        // set buyer info
        Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

        // set order info
        Order order = Order.builder().referenceOrderId(orderId)
                .orderDescription("antom testing order").orderAmount(amount).buyer(buyer).build();
        alipayPayRequest.setOrder(order);

        // set env info
        Env env = Env.builder().terminalType(TerminalType.WEB).clientIp("1.2.3.4").build();
        alipayPayRequest.setEnv(env);

        // replace with your notify url
        alipayPayRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl.com");

        // replace with your redirect url
        alipayPayRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");

    // pay
    AlipayPayResponse alipayPayResponse = null;
    try {
        alipayPayResponse = CLIENT.execute(alipayPayRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}
```

 The following shows the sample code of a request:

 ```json
{

   ........
   "paymentMethod": {
    "paymentMethodType": "APPLEPAY",
    "paymentMethodMetaData": {
      "cardNo":"***********",
      "expiryYear":"30",
      "expiryMonth":"12",
      "mpiData":{
          "cavv":"Af9xA/3bAyP6CAP3FngiMAABAAA="
          "eci":"5"
       }
    },
  },

  .........
 }
```

 For the complete sample code, refer to   [Step 1: Initiate an authorized payment](https://docs.antom.com/ac/cashierpay/cardinfocallmerchant.md#z5Nqg)  .

<!-- /TabGroup -->

### Step 3: Obtain the authorization result   **[Server-side]** {#kBb1r}

 After the buyer completes payment or the payment times out, you can obtain the payment result either by receiving asynchronous notifications from Antom or by proactively querying the result. For detailed steps, refer to   [Step 3: Obtain the authorization result](https://docs.antom.com/ac/cashierpay/cardinfocallmerchant.md#Uflu0)  .

### Step 4: Capture   **[Server-side]** {#kBb2r}

 After successful authorization, Antom will automatically initiate capture for you, or you can choose to initiate capture manually. After capture, you can obtain the capture result either via asynchronous notification or active query. For specific steps, refer to   [Capture](https://docs.antom.com/ac/cashierpay/capture.md)  .

## **After payments** {#tx5xG}

 After completing the payment, you can perform the following actions:

### Cancellation    ​  **[Server-side]** {#t2tAM}

 For successful payments, if the buyer requests cancellation or a refund on the same day, you can use Antom’s cancellation capability to cancel the order or release funds. Orders not yet completed can also be cancelled directly. For details, refer to   [Cancel](https://docs.antom.com/ac/cashierpay/cancel.md)  .

### Refund   **[Server-side]** {#SHB4j}

 To learn about Antom refund rules and how to initiate a refund for a successful transaction, see  [Refund](https://docs.antom.com/ac/cashierpay/refund.md)      for more information.

### Dispute   **[Server-side]** {#9fZTO}

 Antom provides dispute resolution services for contested transactions. For more information, refer to [Dispute Guidance](https://docs.antom.com/ac/dispute/overview.md) and [Dispute resolution](https://docs.antom.com/ac/dispute/dispute_resolution.md).

### Reconciliation  **[Server-side]** {#Ac5We}

 After the transaction is completed, use the financial reports provided by Antom for reconciliation. For more information on how to reconcile and the settlement rules of Antom, refer to   [Reconciliation](https://docs.antom.com/ac/cashierpay/reconcile.md)  .

## Additional content {#OwA04}

### Card payment features {#NfW2T}

 [Card payment features](https://docs.antom.com/ac/cashierpay/mf.md)   also apply to  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md) . The following table outlines the support status of these features for  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md) :

 | **Type** | **Supported** | **Conditions** |
| --- | --- | --- |
| [**Antom Tokenization**](https://docs.antom.com/ac/pm/tokenization.md) | Conditional | - Not supported in CIT (Cardholder-Initiated Transaction) scenarios. It is recommended to store cards via Apple accounts. - Supported in MIT (Merchant-Initiated Transaction) scenarios. |
| [**COF**](https://docs.antom.com/ac/pm/cof.md) | Conditional | Only supported in MIT (Merchant-Initiated Transaction) scenarios. |
| [**3D Secure 2**](https://docs.antom.com/ac/pm/3ds.md) | Yes | After completing 3D Secure 2 authentication,  [Apple Pay](https://docs.antom.com/ac/antomop/applepay.md)  passes the encrypted transaction cryptogram and ECI (E-Commerce Indicator) to Antom. Antom processes this authentication data following standard third-party card network procedures. For details, refer to   [Apple Developer: Payment token format reference](https://developer.apple.com/documentation/passkit/payment-token-format-reference)  . As a result, no additional 3DS authentication flow will be triggered by the payment method within Checkout Page, ensuring a seamless user experience. It is recommended to use the default values for the     *is3DSAuthentication*     and     *enableAuthenticationUpgrade*     parameters when initiating payment requests. |
| [**Antom 3DS-Retry**](https://docs.antom.com/ac/pm/3ds_retry.md) | Yes | None |
| [**MIT**](https://docs.antom.com/ac/pm/mit.md) | Yes | None |
| [**Installment payments**](https://docs.antom.com/ac/pm/installment.md) | No | None |