Apple Pay®

Prerequisites: Authentication

An AI skill is available for this guide, get it on the Skills Marketplace (GitHub).

Apple Pay® is a digital wallet application that Apple customers can use to store payment card details and to pay for goods and services using their Apple devices.

When you add Apple Pay to your integration, your merchants can accept Apple Pay as a payment method for online transactions. When a customer uses Apple Pay to make a payment, your integration communicates with the Apple JS API and the Payroc gateway to make the sale.

To simplify your integration, our gateway creates and handles the Apple Pay Certificate that you need to run transactions with Apple Pay.

How it works

sequenceDiagram
    participant AP as Apple Pay JS API
    participant YI as Your integration
    participant GW as Gateway

    rect rgba(0, 81, 194, 0.4)
        Note over AP,GW: Start an Apple Pay session
        Note over YI: 1. Cardholder chooses to pay with Apple Pay
        YI->>AP: 2. Request the validation URL
        AP-->>YI: 3. Return the validation URL
        YI->>GW: 4. Send the validation URL to the Apple Pay sessions API
        Note over GW: 5. Start the session with Apple and retrieve the merchant session object
        GW-->>YI: 6. Return the merchant session object
    end

    rect rgba(0, 224, 184, 0.3)
        Note over AP,GW: Run a sale
        Note over YI: 1. Cardholder confirms their payment method
        YI->>AP: 2. Send payment request to Apple
        Note over AP: 3. Apple encrypts the payment details
        AP-->>YI: 4. Return encrypted payment details
        YI->>GW: 5. Send the payment details in a payment request
        GW-->>YI: 6. Return payment response
    end

Start an Apple Pay session

1. Cardholder chooses to pay with Apple Pay, for example, they select the Apple Pay button on the merchant's web page.
2. Your integration requests the validation URL from Apple.
3. Apple returns the validation URL to your integration.
4. Your integration sends a request to our Apple Pay sessions endpoint. The request must include the unique domainId and validation URL.
5. We start an Apple Pay session and get the merchant session object from Apple.
6. We return the merchant session object to your integration.

Run a sale

1. Cardholder confirms the payment method they want to use.
2. Your integration sends a request to Apple that includes details about the transaction and the merchant session object.
3. Apple returns the cardholder's encrypted payment details to your integration.
4. Your integration sends a request to our Payments endpoint. The request must include the cardholder's encrypted payment details in hexadecimal format.
5. Our gateway returns a successful payment response to your integration.

Your integration journey

To set up Apple Pay for a merchant, complete the following actions:

Step 1. Add Apple Pay to your integration:

• Integrate with the Apple Pay JS API - Use the Apple Pay JS API to validate the merchant's domain and to receive a cardholder's encrypted payment details.
• Integrate with the Payroc API - Use our gateway to start a merchant session with Apple and to run a sale with the encrypted payment details you received from Apple.

Step 2. Set up Apple Pay for a merchant:

• Domain verification file - Add the domain verification file to the merchant's domain.
• Self-Care Portal - Use the Self-Care Portal to set up Apple Pay for a merchant, and to get their unique domain ID that you send to Apple.

Extend your integration

You can extend your integration to add convenience fees and to split a payment between multiple third parties.

Guides

Add Apple Pay to your integration

Set up Apple Pay to run transactions with our gateway.

Set up Apple Pay for a merchant

Configure Apple Pay with the Self-Care Portal.

Add a convenience fee

Apply a convenience fee to Apple Pay payments.

Split a payment with multiple merchants

Divide a payment with other merchants or third parties.