Apple Pay

Show the Apple Pay button in your own checkout and send the payment token to myTU.

In your own checkout, you show the Apple Pay button yourself and pass the payment token from Apple to myTU. Your customer doesn't leave your website. To show Apple Pay on the hosted payment page instead, without any work with Apple, see Apple Pay and Google Pay on the hosted payment page.

Before you begin

Make sure Apple Pay is active in your project.
Read Apple's documentation and make sure your integration follows it:

You can process the payment token from Apple in two ways:

Flow	Who decrypts the Apple Pay token	Who manages the Apple Pay keys
Encrypted payload	myTU	myTU
Decrypted payload	You	You

Encrypted payload

You pass the encrypted payment token from Apple to myTU. myTU decrypts it and stores the card in the vault.

Step	Endpoint	What it does
1	`POST /v1/orders/`	Creates the order and the Apple Pay transaction.
2	`POST /v1/apple-pay/sessions/`	Validates your merchant session with Apple.
3	`POST /v1/apple-pay/payment-tokens/persist/`	Decrypts the payment token and returns a `vaultToken`, cryptogram and ECI indicator.
4	`POST /pay/{order_id}/select-payment-method/apple-pay/{transaction_id}/`	Executes the payment.

Create the order

Create an order with an apple-pay transaction:

curl https://api.gw.mytu.co/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "EUR",
    "amount": 995,
    "merchant_order_id": "EXAMPLE001",
    "description": "Example Apple Pay order",
    "return_url": "https://www.example.com/order/EXAMPLE001",
    "webhook_url": "https://www.example.com/webhook",
    "transactions": [
      {
        "payment_method": "apple-pay"
      }
    ],
    "customer": {
      "merchant_customer_id": "123456789",
      "email_address": "user@example.com",
      "first_name": "John",
      "last_name": "Smith",
      "address_type": "billing",
      "address": "100 Main St",
      "postal_code": "SW1A 1AA",
      "city": "London",
      "country": "GB",
      "locale": "en",
      "phone_numbers": ["+441234567890"],
      "ip_address": "198.51.100.1"
    }
  }'

The response contains the IDs and the setup token you need in the next steps:

{
  "id": "6bf8a727-bef2-4420-8d41-af82f6f19f3d",
  "project_id": "05ad138f-52fa-40dc-9751-5fde949dcb57",
  "status": "new",
  "transactions": [
    {
      "id": "59f5866a-c216-472e-b803-8a4e83c4578a",
      "payment_method": "apple-pay",
      "payment_method_details": {
        "setup_token": "c6d0a22b-df22-41a2-aac1-d647173ff219"
      },
      "status": "new"
    }
  ]
}

The response is shortened. Save the order id, the project_id, the transaction id and the setup_token.

Depending on your acquirer, fields of the customer can be required. See Create an order in the API reference for the fields and their formats.

Start the Apple Pay session

When your customer taps the Apple Pay button, Apple triggers the onvalidatemerchant event in the browser. Send the event.validationURL to your server, and request a merchant session from the API:

curl https://api.gw.mytu.co/v1/apple-pay/sessions/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
    "merchantIdentifier": "05ad138f52fa40dc97515fde949dcb57",
    "displayName": "Example Shop",
    "initiativeContext": "shop.example.com"
  }'

merchantIdentifier is your project ID without hyphens, and displayName the trade name of your project. See Start an Apple Pay session in the API reference.

The response contains the merchant session from Apple:

{
  "sessionData": "..."
}

Pass the sessionData to session.completeMerchantValidation() in the browser to complete the merchant validation.

Store the payment details

After your customer confirms the payment, Apple triggers the onpaymentauthorized event. It contains the encrypted payment token in event.payment.token.paymentData. Send its contents to the API, together with the setupToken from step 1:

curl https://api.gw.mytu.co/v1/apple-pay/payment-tokens/persist/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "setupToken": "c6d0a22b-df22-41a2-aac1-d647173ff219",
    "data": "C+YChH...dTlaSmc=",
    "signature": "MIAGCSqGSIb3DQ...==",
    "header": {
      "publicKeyHash": "yFMDm...s=",
      "ephemeralPublicKey": "MFkwEwYHKo...SoHnSg==",
      "transactionId": "878...4c52"
    },
    "version": "EC_v1"
  }'

Apple describes the fields in its payment token format reference.

The response contains what you need to execute the payment:

{
  "vaultToken": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3",
  "onlinePaymentCryptogram": "AgAAAAAABk4DWZ4C28yUQAAAAAA=",
  "eciIndicator": "7"
}

Execute the payment

Send the vault token, cryptogram and ECI indicator to the payment URL of the transaction:

curl https://api.gw.mytu.co/pay/6bf8a727-bef2-4420-8d41-af82f6f19f3d/select-payment-method/apple-pay/59f5866a-c216-472e-b803-8a4e83c4578a/ \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "vault_token": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3",
    "online_payment_cryptogram": "AgAAAAAABk4DWZ4C28yUQAAAAAA=",
    "eci_indicator": "7"
  }'

{
  "is_successful": true,
  "redirect_url": "https://api.gw.mytu.co/pay/6bf8a727-bef2-4420-8d41-af82f6f19f3d/59f5866a-c216-472e-b803-8a4e83c4578a/completed/",
  "reason": "none"
}

Redirect your customer to the redirect_url. Then confirm the payment before you deliver.

Decrypted payload

You decrypt the payment token from Apple yourself, with your own Apple Pay keys, and store the card details in the myTU vault.

You handle card data

The decrypted payload contains the card number. Your systems must be PCI DSS compliant to process it. See Accept a card payment.

Step	Endpoint	What it does
1	`POST /v1/orders/`	Creates the order and the Apple Pay transaction.
2	Apple Pay	Your customer confirms the payment. You decrypt the payload.
3	`POST https://tokens.gw.mytu.co/v1/cards/`	Stores the card details in the vault and returns a `vault_token`.
4	`POST /pay/{order_id}/select-payment-method/apple-pay/{transaction_id}/`	Executes the payment.

Create the order

Create an order with an apple-pay transaction, as in step 1 of the encrypted payload flow. Save the order id, the transaction id and the setup_token from payment_method_details.

Get the payment data from Apple

Your customer taps the Apple Pay button and confirms the payment. Apple returns an encrypted payload. Decrypt it with your Apple Pay keys, and take the card number, expiry date, online payment cryptogram and ECI indicator from it.

Store the card details

Store the card in the vault with the setup_token from step 1. The expiry date uses the format MMYYYY:

curl https://tokens.gw.mytu.co/v1/cards/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "pan": "4871049999999910",
    "expiry": "122028",
    "setup_token": "c6d0a22b-df22-41a2-aac1-d647173ff219"
  }'

{
  "brand": "visa",
  "brands": ["visa"],
  "truncated_pan": "4871********9910",
  "vault_token": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3"
}

The setup token can be used once, within 300 seconds after the order was created.

Send the payment

Send the vault_token from the vault, and the cryptogram and ECI indicator from the decrypted payload, to the payment URL of the transaction:

curl https://api.gw.mytu.co/pay/6bf8a727-bef2-4420-8d41-af82f6f19f3d/select-payment-method/apple-pay/59f5866a-c216-472e-b803-8a4e83c4578a/ \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "vault_token": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3",
    "online_payment_cryptogram": "AgAAAAAABk4DWZ4C28yUQAAAAAA=",
    "eci_indicator": "7"
  }'

The response is the same as in the encrypted payload flow. Redirect your customer to the redirect_url, then confirm the payment.

Make sure Apple Pay is active in your live project, and use its API key.
Test on your production domain with a real card in Wallet: make a small payment and refund it.
Set the webhook URL in your live project, or send a webhook_url with every order.

Then work through the go-live checklist.

Recurring payments

Apple Pay supports recurring payments. See Recurring payments with Apple Pay.

Before you begin

Encrypted payload

Create the order

Start the Apple Pay session

Store the payment details

Execute the payment

Decrypted payload

Create the order

Get the payment data from Apple

Store the card details

Send the payment

Confirm the payment

Test your integration

Go live

Recurring payments

On this page

Apple Pay

Before you beginCopy Anchor Link

Encrypted payloadCopy Anchor Link

Create the orderCopy Anchor Link

Start the Apple Pay sessionCopy Anchor Link

Store the payment detailsCopy Anchor Link

Execute the paymentCopy Anchor Link

Decrypted payloadCopy Anchor Link

Create the orderCopy Anchor Link

Get the payment data from AppleCopy Anchor Link

Store the card detailsCopy Anchor Link

Send the paymentCopy Anchor Link

Confirm the paymentCopy Anchor Link

Test your integrationCopy Anchor Link

Go liveCopy Anchor Link

Recurring paymentsCopy Anchor Link

On this page

Before you begin

Encrypted payload

Create the order

Start the Apple Pay session

Store the payment details

Execute the payment

Decrypted payload

Create the order

Get the payment data from Apple

Store the card details

Send the payment

Confirm the payment

Test your integration

Go live

Recurring payments