Apple Pay BETA

Enable Apple Pay to allow your customers to make purchases using a credit or debit card connected with their Apple Wallet. This guide walks you through the payment flow and steps to implement the service.

How to enable

• Supported Countries: Singapore
• Minimum API version: 2017-11-02

To enable Apple Pay, send an email requesting this feature to support@opn.ooo.

Payment flow

Apple Pay supports payments on websites and iOS devices. Customers who choose to make payments using Apple Pay initiate the transaction by tapping or clicking on the Apple Pay button that is embedded on your platform. Customers who have already linked a card to their Apple Wallet will be able to choose their preferred card right away. Those who have not, will be given the option to link a new card.

Once the customer selects their preferred card and confirms the payment, the card will be charged the same way as the normal credit card payments flow. Your account’s current card processing settings may apply to Apple Pay transactions.

Apple Pay transactions will only be proceeded with non-3D Secure.

Using a desktop browser

To start the Apple Pay payment, ❶ the customer selects Apple Pay as their preferred payment method during checkout on your website. ❷ The customer then chooses their preferred credit or debit card linked to their Apple Wallet. Then reviews and confirms the payment. ❸ Upon confirmation, Opn will send a webhook event (if enabled) indicating that the charge is complete.

Before deploying Apple Pay on your website, make sure your implementation follows Acceptable Use Guidelines for Apple Pay on the Web

Using a mobile application

To start the Apple Pay payment, ❶ the customer selects Apple Pay as their preferred payment method on your mobile application. ❷ The customer then chooses their preferred credit or debit card linked to their Apple Wallet. Then reviews and confirms the payment. ❸ Upon confirmation, Opn will send a webhook event (if enabled) indicating that the charge is complete.

Implementation

Follow the Apple Pay Marketing Guidelines to add Apple Pay payment buttons to your website or iOS app. After the customer taps on the button and selects their card, you will receive an Apple Pay token from Apple, which contains the card information. You then send this type of token to our Token API to obtain a card token that’s usable on our Charge API.

Opn treats Apple Pay tokens the same way as sensitive card data. Therefore, unless you have a PCI-DSS license, these tokens must first be converted to card tokens before you can use them in your servers. Read more in Collecting Cards.

In summary, to create a charge with Apple Pay, make the following API requests.

1. Obtain an Apple Pay token from Apple when the user initiates payment through the Apple Pay button.
2. Create a card token from Apple Pay token using Omise.js.
3. Create a new charge using the obtained card token from Step 2.
4. After receiving the charge completion webhook event, retrieve the charge to verify its status (optional, but recommended).

This sequence diagram below shows how to obtain the card token.

Configuring an Apple Pay environment

To support Apple Pay on your website or application, you need to complete a few set up steps before being able to use the Apple Pay web APIs and/or app APIs. Opn provides 2 options for you to select from.

1. Use Opn Apple developer account

You have the option to enable Apple Pay on your website by using the provided Opn merchant identifier, without requiring you to create an Apple developer account. This method supports only the Web integration.

Simply follow these steps to obtain an Apple Pay merchant ID, merchant identity certificate, and verifying your domains for the Apple Pay web integration.

• Obtaining Apple Pay merchant ID and Apple merchant identity certificate. You can obtain an Apple merchant ID and an Apple merchant identity certificate from the Opn dashboard.

The merchant identity certificate is a Transport Layer Security (TLS) certificate associated with your merchant ID, used to authenticate your sessions with the Apple Pay servers. To ensure uninterrupted service, please download a new certificate using with your website before the expiration of the current one.

• Verify your web domains with Opn. Register your merchant domains where you’ll display the Apple Pay button with Opn via email at support@opn.ooo to receive the domain association file and host this file at https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association on your website. Then Opn will proceed with verifying your domains.

You must register and verify all top-level domains and subdomains. For example, opn.ooo is the top-level domain and shop.opn.ooo is the subdomains that you must register.

2. Use your Apple developer account

This option enables you to integrate with Apple Pay on both Web and App. To set it up, refer to these Apple Pay configuration guides for detailed instructions on configuring. This involves registering a merchant ID, generating certificates, and validating your web domains.

• Configure Apple Pay for Apps
• Configure Apple Pay on the Web

In order for Opn to accept payments from your Apple merchant ID, you must use a Payment Processing CSR provided by us to create a Payment Processing Certificate with Apple by follow these steps.

1. Create your Apple merchant Identifier. You need to first enrolled in the Apple Developer Program and register your Apple Pay merchant ID.
2. Submit Apple merchant ID and get Payment Processing CSR with Opn. Reach out to the Opn via email at support@opn.ooo to submit your Apple merchant ID for our system and request a Certificate Signing Request (CSR) for your Payment Processing Certificate. Once received, we will create the CSR and promptly return it to you.
3. Create a Payment Processing Certificate with Apple. Please use the Payment Processing CSR from Opn to generate a Payment Processing Certificate on your Apple account.
4. Submit Payment Processing certificate to Opn. Once you have obtained the certificate, please download it and submit it to Opn for further processing. Subsequently, your Apple Pay configuration be visible on the Opn dashboard.

Obtaining an Apple Pay token

With your configuration complete, you can now adding an Apple Pay button to your app or website and able to receive an Apple Pay token.

Please Follow the Apple Pay developer documentation to render an Apple Pay button, integrate with Apple APIs and receive an Apple Pay token.

• Web - Apple Pay on the Web
• App - PassKit (Apple Pay and Wallet)

In the payment request, ensure that the following fields follow the below guidelines.

• Field supportedNetworks should reflect the supported card brands from the Capability API.
• Field merchantIdentifier is the Apple Pay merchant identifier.

After that, you will receive a token from Apple Pay. The Apple Pay token should be used within 5 minutes.

{
  "data": "...",
  "signature": "...",
  "header": {
    "publicKeyHash": "...",
    "ephemeralPublicKey": "...",
    "transactionId": "..."
  },
  "version": "EC_v1",
}

Creating a card token

Once you receive an Apple Pay token, create a new card token using the following tokenization parameters.

By default, the cardholder's name and billing address won't be attached to a card token, and the name will be displayed as Apple Pay for such case. To override this behavior, supply billing contact fields (Web, iOS) when requesting payment to Apple.

The card token can be used to create a charge within 10 minutes.

For testing, you can create the same request using curl. Please note that this example must only be used on test mode, as on live mode Apple Pay tokens must be sent from the client side.

curl https://vault.omise.co/tokens \
  -u $OMISE_PUBLIC_KEY: \
  -d 'tokenization[method]=applepay' \
  --data-urlencode 'tokenization[data]={"data":"b2SbY+mC2hlPEIommp55HuFUt1sO8w5BycURRm+4SzWCG8Q51qV7UyXCW93he5z/054wCg5p0Lldyfm8tQ2Q0ZTGz//RssqPAoLia2pyTpeKvxDvnSQC+J/9fXt2fa/36kISSe8+Cq5bR3VbPnWtZ2Yo4anjlTOCsiYulHPFfuSJww/Axci+S8eB4hjeTz1hmvYCyXnEBrB88BP8/BxnMHUECwWGsbT4gZRMT9YGtMdwYTOs2svsysvKbetjCc0cXBe6JAwTZJsUE19l735MNbBnvofmn+SWsndavPnJaCKl16/QpUBKxFFtDb7Q1ApwqmLoUGWsye4jwfBO9hYI5iNxhJlzg6B/urX25zOITL+mQZ15PWXhqNaOh+vyvaxMHhR0jhonxXs1BLu3tCXGxTQHEiVrX4UmQgB/A/qb3Q==","signature":"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","header":{"publicKeyHash":"/PbrG6EesIaHQNXliuBMw0EgbgE/CMdsxDClG6JSTaA=","ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAENqHdD4o3dLC39iWBdlP5zAp1BqDQ4JZUKPgakTm2BF6o1QD/qsWrt0yByE2TuYEy24JdJ7+qOguWaLyTfn9fCA==","transactionId":"157e2aba7874a1ab32ab94ad1b853890e49da8742028d9dbeba88dae90bed222"},"version":"EC_v1"}' \
  -d 'tokenization[merchant_id]=merchant.omise.sg.prod' \
  -d 'tokenization[brand]=Visa'

{
  "object": "token",
  "id": "tokn_test_61kik208vfupgi6qbix",
  "livemode": false,
  "location": "https://vault.omise.co/tokens/tokn_test_61kik208vfupgi6qbix",
  "used": false,
  "charge_status": "unknown",
  "card": {
    "object": "card",
    "id": "card_test_61kik2081wxvav2dy9u",
    "livemode": false,
    "location": null,
    "deleted": false,
    "street1": null,
    "street2": null,
    "city": null,
    "state": null,
    "phone_number": null,
    "postal_code": null,
    "country": "us",
    "financing": "credit",
    "bank": "JPMORGAN CHASE BANK N.A.",
    "brand": "Visa",
    "fingerprint": "lfgpKUT29328scrabNJ0Aj1CVdziBPJP4Oah/WB9O2I=",
    "first_digits": null,
    "last_digits": "1111",
    "name": "Apple Pay",
    "expiration_month": 1,
    "expiration_year": 2030,
    "security_code_check": true,
    "tokenization_method": "applepay",
    "created_at": "2024-10-29T05:48:15Z"
  },
  "created_at": "2024-10-29T05:48:15Z"
}

The id attribute is the token identifier (begins with tokn).

Creating a charge

Refer to Credit Card Payments to charge a card with the received card token. There are a couple of differences for card tokens that are generated from a specific tokenization method (applepay) compared to normal ones:

1. These card tokens have a field tokenization_method to tell what tokenization method was applied on the card.
2. These card tokens cannot be used in the Customers API.

Testing

To complete the whole user journey, you need to have an Apple account that supports an Apple Wallet and attach a chargeable card to it. We recommend using an Apple sandbox tester account and attaching one of the available test cards provided by Apple for the test mode.

You can create a token and a charge with an Omise test key to simulate a successful charge, and the card number will always be 4111 1111 1111 1111 in our system. Please note that the Apple Pay environment configuring process is also required with an Omise test key.