Apple Pay Direct Integration - Yuno Merchant Guide

Pick your path

Direct or SDK

Both routes process Apple Pay through Yuno. The difference is who builds the Apple Pay sheet and manages the token. Direct gives you full control. The SDK does the heavy lifting.

This guide

Direct integration

You implement Apple Pay yourself (PassKit on iOS, Apple Pay JS on web).
You handle merchant validation and receive the raw Apple payment_token.
You call Create Payment with workflow: DIRECT.
Best when you have an existing payment stack or need custom checkout control.

Alternative

SDK integration

Yuno's SDK renders the Apple Pay flow and manages the token for you.
You create a checkout session and the SDK handles authorization.
Less code, less control over the sheet.
Best for a fast, standardized integration.

The flow

Five steps, end to end

The customer authorizes on device, you get an encrypted token, and Yuno does the rest. You never see the underlying card.

1

Customer authorizes on their iOS device

Face ID or Touch ID confirms the payment inside the Apple Pay sheet you presented.

2

Apple SDK returns the payment_token

You receive an encrypted token object containing the network-tokenized card data and a cryptogram. Apple has already replaced the real PAN.

3

Create the payment with Yuno

Send the stringified token to POST /v1/payments with workflow: DIRECT and type: APPLE_PAY.

4

Yuno decrypts and routes

Using your processing certificate, Yuno decrypts the token and forwards the transaction to the provider in your configured routing.

5

Monitor the result via webhooks

Track the final status asynchronously. Do not rely only on the synchronous API response for the outcome.

Before you build

Prerequisites

This setup is where most Direct integrations stall. Two certificates and a Merchant ID must line up between Apple and the Yuno Dashboard before a single payment will clear.

01

Register an Apple Merchant ID

In the Apple Developer portal, create a Merchant ID with an identifier like merchant.com.y.uno.YourId. Then add your merchant domains for web.

02

Create a Payment Processing Certificate

Generate a CSR in Keychain Access, download the signed apple_pay.cer from Apple, convert it to apple_pay.pem, and export the private key. This is what lets Yuno decrypt the token.

03

Create a Merchant Identity Certificate

Generate a second CSR and certificate used for merchant validation during the Apple Pay session on web.

04

Upload to the Yuno Dashboard

Add the processing certificate to the Payment Processing Certificate field in your Yuno provider connection. The Merchant ID must match exactly across Apple and Yuno.

Most common setup failure Merchant ID mismatch. If the Merchant ID in Apple Developer does not match the one configured in your Yuno Dashboard provider connection, merchant validation fails and no token can be decrypted.

The artifact

Anatomy of the payment_token

The Apple SDK hands you a structured object. Yuno needs the whole thing, but as a single escaped string, not a nested JSON object.

apple_sdk_response.json

"paymentMethod": {
  "type": "credit",        // display only
  "displayName": "Visa 3748",
  "network": "Visa"
},
"paymentData": {
  "data": "B5NSQI0TdXuLwqad...",   // encrypted card + cryptogram
  "signature": "MIAGCSqGSIb3...",    // Apple signature chain
  "header": {
    "publicKeyHash": "YK8kdoBX...",
    "ephemeralPublicKey": "MFkwEwYH...",
    "transactionId": "87a03c4c..."
  },
  "version": "EC_v1"          // elliptic-curve encryption
}

Critical The payment_token must be stringified. Yuno expects this entire object as an escaped string in detail.wallet.payment_token, not as inline JSON. Sending it as a nested object is the number-one cause of failed Direct payments. Generate a fresh token per transaction. Apple tokens are single use and expire quickly.

One-time payment

The Create Payment request

A single Apple Pay charge. The stringified token goes inside payment_method.detail.wallet. Set vault_on_success if you want to keep the method for later.

POST https://api-sandbox.y.uno/v1/payments

# header: X-idempotency-key: <uuid>   // prevents duplicate charges
{
  "country": "US",
  "amount": { "currency": "USD", "value": 2000 },
  "customer_payer": { "id": "24e25748-...-eb0204bb0954" },
  "workflow": "DIRECT",
  "payment_method": {
    "vault_on_success": true,
    "type": "APPLE_PAY",
    "detail": {
      "wallet": {
        "payment_token": "{\"paymentMethod\":{...},\"paymentData\":{...}}",  // stringified
        "soft_descriptor": "TEST"
      }
    }
  },
  "account_id": "fe14c7c6-...-4c87ad52c482",
  "merchant_order_id": "order-123"
}

Why the idempotency key matters Network retries on a payment call can fire the same charge twice. Sending a unique X-idempotency-key on every Create Payment request guarantees Apple Pay charges are not duplicated.

Recurring

Subscriptions: CIT then MIT

Recurring Apple Pay over Direct splits into two transaction types. The first is customer-authorized and produces a vaulted token. Every charge after that is merchant-initiated and reuses it.

Step 1 / customer present

CIT

Customer Initiated Transaction

The customer authorizes the subscription via Apple Pay. You send the stringified token and flag it as the first in a series. On success, Yuno returns a vaulted_token.

Token sentdetail.wallet.payment_token

vault_on_successtrue

stored_credentialsreason: SUBSCRIPTION

usageFIRST

Returnsvaulted_token

Step 2+ / customer absent

MIT

Merchant Initiated Transaction

Each billing cycle, you charge automatically with no customer interaction. No Apple token is needed. You reuse the vaulted token from the CIT.

Token sentvaulted_token (no payment_token)

Credential pathdetail.card.stored_credentials

stored_credentialsreason: SUBSCRIPTION

usageUSED

Customer actionnone

Easy to miss The credential path moves between calls. The CIT carries the token under detail.wallet, but the MIT places stored_credentials under detail.card and switches usage from FIRST to USED. Store the returned vaulted_token securely.

When it breaks

Troubleshooting

Symptom	Likely cause and fix
Merchant validation failed	Apple Pay certificates or Merchant ID are misconfigured. Confirm the processing certificate is uploaded to Yuno and the Merchant ID matches across Apple and the Dashboard.
Invalid or expired token	The Apple token is stale or malformed. Obtain a fresh token from the Apple SDK and confirm it is stringified before sending.
Unsupported network or country	Your routed provider does not support Apple Pay for that currency or country. Confirm provider coverage for the requested market.
Duplicate charges	Retries fired the same payment twice. Always send a unique X-idempotency-key on Create Payment.