Apple Pay Integration

Goal

Enable a user to pay with Apple Pay by initializing the Push Apple Pay launcher, displaying the payment sheet, and authorizing the payment.

Sequence Diagram

Steps

---

Step 1: Initialize the Apple Pay launcher

What you need to do

Generate an Apple Pay URL, initialize the Push SDK launcher, and render the Apple Pay button if supported.

If a user has not previously used Push, you must first register them following the create-user guide.

How to do it

1. Call create-user-url with type: "apple_pay" when the user loads the payment page.

2. Initialize the launcher with the returned URL.

3. Check ApplePaySession.canMakePayments() and render the Apple Pay button.

Initialization Example

Example code to generate a URL, initialize the Apple Pay launcher, and conditionally render the button.

// the url returned from create-user-url endpoint
const launcher = new window.PushCash.ApplePay({
  url: '<your-url>'
});

if (window.ApplePaySession) {
    const canMakePayments = ApplePaySession.canMakePayments();

    if (canMakePayments) {
        // render Apple Pay option to DOM
    }
}

For more information on how to style and display the button, please review Apple’s design guidelines and official javascript guide.

If you want to support Apple Pay on non-Apple devices (or if you are not using Safari), install the Apple Pay JS SDK on your cashier. Initiating the payment will display a QR code which you will scan with an Apple device to authorize the payment.

Step 2: Display the payment sheet

What you need to do

When the user clicks the Apple Pay button, launch the payment sheet using the SDK.

How to do it

1. Call launcher.display() with the payment amount, currency, direction, and an onAuthorize callback.

2. The SDK handles merchant validation and presents the Apple Pay payment sheet to the user.

3. You may optionally provide an onComplete callback that runs when the Apple Pay payment sheet is dismissed.

Display Example

Example code to launch the Apple Pay payment sheet.

launcher.display({
  amount: 1000,  // amount of payment in cents
  direction: 'cash_in',
  currency: 'USD',
  onAuthorize: async (token) => {
    // see Step 3
  },
  onComplete: () => {
    // handle session completion
  }
});

To launch Apple Pay on your site, you must verify ownership of your domain. Please contact Push at [e-mail] to request your Apple Pay merchant domain association file. You must place the file at https://your-domain.com/.well-known/apple-developer-merchantid-domain-association.txt to complete domain verification.

Step 3: Authorize the payment

What you need to do

Handle the onAuthorize callback to receive the token and call the Push API to authorize the payment.

How to do it

1. The onAuthorize callback receives a token after the user authorizes via Face ID / Touch ID.

2. Pass the token, along with amount, currency, and direction to authorize-payment.

3. Return the intent status (i.e. approved or declined) from the callback to complete the Apple Pay session.

Authorization Example

Example code to handle the onAuthorize callback and authorize the payment.

launcher.display({
  amount: 1000,
  direction: 'cash_in',
  currency: 'USD',
  onAuthorize: async (token) => {
    // call backend to authorize payment via Push API
    // pass token to POST /authorize
    const result = await yourBackend.authorize(token);
    return result.status; // 'approved' or 'declined'
  }
});

The amount and currency passed to POST /authorize must match the values provided to display(). The return value of onAuthorize is used to complete the Apple Pay session — return 'approved' for a successful payment or 'declined' otherwise.

Create User URL

curl --request POST \
  --url https://sandbox.pushcash.com/user/{id}/url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "apple_pay"
}
'

Create User URL - 200 OK

{
  "url": "https://cdn.pushcash.com/applepay/?param=1&param=2&param=3"
}

Integration checklist

• Simulate an approved transaction by submitting a payment
• Simulate a declined transaction by submitting a transaction for $0.01
• Verify domain association file is in place at https://your-domain.com/.well-known/apple-developer-merchantid-domain-association.txt

Next steps

Set up webhooks to receive asynchronous updates about payment status. Refer to the enabling webhooks guide for details.