PaymentsAPMsApple Pay

Overview

About

Apple Pay allows users to pay securely using cards saved to their Apple Pay Wallet, in iOS apps and on websites.

Region

International

Currencies

See the currencies page for details

Refunds

Yes, within 11 months

Disputes

Yes

Preauthorization

No

Recurring payments

Yes

Note - Supported by Checkout SDK

Apple Pay is supported by Mangopay’s Checkout SDK, which can power the payment page of your website or app. Read more →

Activation

To offer Apple Pay with Mangopay you need to set up an Apple Pay merchant identifier and Payment Processing Certificate as described in the certificates guide.

You also need to integrate directly with Apple Pay:

If not using Mangopay’s Checkout SDK, you also need to adhere to their design guidelines.

Flow diagram

The basic flow of a one-time Apple Pay payment is given in the diagram below.

One-time payments

1

Present Apple Pay to user

The user selects Apple Pay at the checkout on your app or website and confirms payment.

The user’s card must be registered in their Apple Pay wallet (see testing information).

2

Request the payment from Apple Pay

Use the Apple Pay PKPaymentRequest to request the payment, specifying the visa and masterCard values as the supportedNetworks.

The order of the array determines the order of display to the user, and the first position in the array is the default network (see Apple Pay’s documentation).

Note – Platforms in France should send CB first

If your platform offers CB co-branded cards in France, you should also include the value cartesBancaires first in the array to comply with regional standards to present the co-branded network first.

For example:

Swift - CB co-branded cards
1let request = PKPaymentRequest()
2// Other parameters
3request.supportedNetworks = [.cartesBancaires, .visa, .masterCard]
4//

In response, Apple Pay returns encrypted data specific to the payment.

3

Request the pay-in from Mangopay

Call the POST Create an Apple Pay PayIn endpoint, including the PaymentData object as received from Apple Pay. The amount and currency of your pay-in request must match your Apple Pay request.

Apple Pay payment data in Mangopay API request
1{
2    // ...
3    "PaymentData": {
4        "TransactionId": "97e64d87f13a89ff6443cdcc205d5ccf7e15368b0d64126a8a2e0888a3a5c2a0",
5        "Network": "MasterCard",
6        "TokenData": "{\"data\":\"2TihgKbmyPje02jYvkB6P+a6LCNmvKTFi4b7UN32sP4FJkllQP8CXIUPdv71xpIpBHetQ6TL7ON3Yex3L0Sc9hm15pME46/5fehwUxmgiumiK1eTupckAST6Zc0IYy2f9iJB9XpX+6dnKqTj7di12bo/iDXW4g2rbenNiDI0caiWebDaUG9DHSFjDxipQWx3Z8rf+zDiMGuDwO41LVh2SA1hRVbdINLpPpLtpxvyDeDkPQVohakcE+sK83QCHx0cEahAUKj6gAv6QuOLtWTsTtad04/ct3G0GnGeRp9p0fE0yJ+s4ybPj4WuV8lKNm6Lsg/WS9TqzT3RFgdjDjGdZ8W1CaEb/deG+Hh4MCebVJBP7iEdyfkB1afjJa0AqfbOBW2SIKXULtjP84QP\",\"signature\":\"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\",\"header\":{\"publicKeyHash\":\"xUyeFb75d359bfPEiq2JJMQj694UAxtTuBsaTWMOJxQ=\",\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEkeuICjZ7x15b7hPEBEBT5Zp43l95wCmJCU3QNxBvOCusG9w9sJMULuXlT4K8LOlPgaZzAcyWlfNwnLivVdOPfg==\",\"transactionId\":\"97e64d87f13a89ff6443cdcc205d5ccf7e15368b0d64126a8a2e0888a3a5c2a0\"},\"version\":\"EC_v1\"}"
7    }
8    // ...
9}

Note - 3DS redirection not required for Apple Pay

With Apple Pay, SCA-compliant authentication is handled by the user’s device (iPhone or Mac), meaning that the payment data received from Apple Pay is already authenticated and no 3DS redirection is required.

4

Handle the outcome

The transaction is complete when the pay-in status changes from CREATED to SUCCEEDED or FAILED, indicating the outcome.

Set up webhooks for the PAYIN_NORMAL_SUCCEEDED and PAYIN_NORMAL_FAILED event types to be notified of this.

Recurring payments

Recurring payments with Apple Pay requires a pay-in registration object to set up the recurrence, before your platform can request pay-ins linked to the registration.

The first pay-in, a customer-initiated transaction (CIT), requires the user to be on session. Once the first payment is successful, your platform can then request subsequent pay-ins without the user present, known as merchant-initiated transactions (MITs), at the frequency and amount agreed by the user.

Payment flow

The steps are as follows:

1

Request the payment from Apple Pay

In the recurring flow, you need to obtain the PaymentData from Apple Pay before calling the Mangopay API.

2

Set up the recurring registration

Call the POST Create a Recurring PayIn Registration to register details about the user, the wallet, and the payments.

Set the PaymentType to APPLEPAY and provide the tokenized PaymentData object retrieved from the Apple Pay API.

The registration object contains the amount of the first transaction and details about the recurrence. It is also possible to specify the amount of subsequent transactions, but this can be overridden when requesting subsequent pay-ins.

In the response, the RecurringPayinRegistrationId allows you to link the recurring pay-ins to this registration object. The Status of the registration object is CREATED.

3

Process the customer-initiated transaction (CIT)

Call the POST Create a Recurring Apple Pay PayIn with the CIT payload to initiate the first transaction.

With Apple Pay, authentication is handled by the user’s device (iPhone or Mac), meaning no 3DS redirection is necessary – the PaymentData is already authenticated.

The CIT pay-in request therefore does not require redirection for the user and can pass directly to SUCCEEDED. When this happens, the registration object Status becomes IN_PROGRESS to indicates that you can debit subsequent payments without the user present.

Set up a webhook for the RECURRING_REGISTRATION_IN_PROGRESS event type to be notified of this.

4

Process merchant-initiated transactions (MIT)

For subesequent payments, call the POST Create a Recurring Apple Pay PayIn with the MIT payload to initiate the pay-in.

Reauthentication

If at any point reauthentication is required by the issuer, the Registration object Status changes to AUTHENTICATION_NEEDED, which you can be notified of thanks to the RECURRING_REGISTRATION_AUTH_NEEDED event type.

In this case, you need to:

  1. Obtain a new PaymentData object from Apple Pay
  2. Call the PUT Update a Recurring PayIn Registration with the new data
  3. Process a new CIT payment with the user on session

Ending the recurrence

The registration object Status can be set to ENDED to indicate that it can no longer be used. You can do this using the PUT Update a Recurring PayIn Registration endpoint.

Set up a webhook for the RECURRING_REGISTRATION_ENDED event type to be notified of this.

Guide

Set up and renew your Apple Pay certificate

Endpoint

The Apple Pay PayIn object

Testing

Learn about testing Apple Pay