Skip to main content
Your backend mints the order, the Meld SDK presents the sheet, and settlement arrives by webhook.

Before you begin

  1. Create a customer and complete Unified KYC. Required — almost every provider refuses an order for a customer Meld has not cleared
  2. Configure webhooks, before KYC so you receive status changes while it runs

Apple Developer setup

Whether you need any depends on how the provider presents the sheet. You never branch on this in code — the SDK presents whichever surface the order carries. It only decides what you register with Apple up front, so do it once, before your first order with the provider concerned. You will need:
  • An Apple Developer account with admin rights on your team
  • The payment processing CSR, which your Meld representative provides
  • Xcode, to add the capability and regenerate provisioning profiles
1

Create a merchant identifier

A merchant identifier names your app to Apple Pay. It lives under your Apple Developer account, not Meld’s.
  1. Go to Certificates, Identifiers & Profiles
  2. Click Identifiers in the sidebar, then +
  3. Select Merchant IDs, then Continue
  4. Enter a description and an identifier — it must start with merchant. (e.g. merchant.com.yourcompany.yourapp)
  5. Click Continue, review, then Register
If your app already has a merchant identifier, reuse it. You do not need a new one.
2

Create a payment processing certificate

This certificate is what the Apple Pay token is encrypted to. It must be created from a CSR Meld provides — never generate your own for this step, because the processor holds the matching private key.Once you have the .certSigningRequest file from your Meld representative:
  1. Go to Certificates, Identifiers & Profiles
  2. Click Identifiers, filter by Merchant IDs, and select the one from Step 1
  3. Under Apple Pay Payment Processing Certificate, click Create Certificate
  4. Upload the .certSigningRequest file Meld provided
  5. Click Continue, then Download to save the .cer file
  6. Send the .cer file back to your Meld representative
Meld passes it to the processor. Wait for confirmation before going further — payments fail until the processor holds it.
3

Configure Xcode

  1. Open your project in Xcode and select your app target
  2. Go to the Signing & Capabilities tab
  3. Click + Capability and select Apple Pay
  4. Under the Apple Pay capability, click + and add the merchant identifier from Step 1
  5. Regenerate provisioning profiles
On React Native, the Expo config plugin does this for you — pass the same merchant identifier.
Certificate expiry. Apple payment processing certificates expire every 25 months. When yours approaches expiry, repeat Step 2 — Meld will provide a fresh CSR. An expired certificate fails every payment.

Supporting more than one provider

Each processor issues its own certificate, and Apple caps certificates per merchant ID. If you offer Apple Pay through two providers, expect to run the setup twice and check whether you need a second merchant identifier.

Registering your domain — web only

On the web there is no native sheet: the button renders on your origin, so that origin has to be registered with the provider before Apple will let it present one. Registration is not self-serve. Contact your Meld representative with the domains you need registered — Meld brokers each one with the provider, so allow for a round trip per domain, and do it before you plan to go live. Every domain you serve the button from needs its own registration, staging included. Native-only integrations skip this entirely.

Flow overview

An Apple Pay purchase, with the system sheet presented over the app

The sheet is presented by the device, and the wallet token is encrypted to a certificate only the processor can read. Your servers handle the order; they never see payment credentials.

1. Quote, then check eligibility

Every order starts here, not just the first one. Get a quote — it prices the order, names the providers that can take it, and carries the destinationNetworkCode the order needs. Then check eligibility for the provider you picked: agreements to show, a verified email or phone to collect, KYC the provider still wants. Collect whatever is outstanding before you mint the order, or the rejection lands after the customer thinks they are done.

2. Create the order

Endpoint: POST /crypto/order/headless/onramp Headers: Meld-Version: 2026-05-01, X-Idempotency-Key: <uuid>

Verification attestation

Check eligibility for the provider the quote named. Where it reports outstanding contact verification or legal agreements, the order carries a verification block:
agreementAcceptedAt is your own timestamp — the instant the customer accepted the terms you rendered. Meld holds no receipt for it, so there is nothing to look up, and your attestation is what reaches the provider. Keep your own record of which customer accepted which document, and when. It is validated before the order is built: unparseable, in the future, or older than 60 days is a 400 naming the reason. Any common ISO-8601 spelling is accepted. Capture it per order — a constant or a cached value starts failing once it ages past the window. The verification ids in the block are optional when the customer verified through Meld, which is the usual case. Supply them only if you ran verification against the provider’s own API. See Email and phone verification.
Keep clientIpAddress: the sheet inputs you pass to the SDK must carry the same IP the order was created with.
Response:
Return it to your client verbatim. paymentMethodResponseDetails carries what the sheet needs — your app does not have to read those fields itself, but it must not drop them.

3. Present the sheet

Check the device can pay before you offer the button, then hand the order to the SDK.
On React Native and iOS, pass the Apple Pay inputs for every Apple Pay order, whichever provider the quote named — they carry what the sheet shows and the order does not. The SDK presents whichever surface the order carries. On the web there is nothing extra to pass: the order carries it, and the provider’s component draws the button. A native sheet draws nothing into your view, because iOS puts it over your screen. The React Native component still has to stay mounted for as long as the sheet is up, so mount it off-screen when a button triggers it rather than a whole page. onCancel fires when the user dismisses the sheet. Treat it as a change of mind and return them to the amount screen.
Not every provider’s Apple Pay works on every platform. Check Meld.capabilities(order).embeddable on the web before you offer the button — an order the SDK cannot present there reports false rather than failing at mount.

4. Settlement

onPaymentSubmitted means the user authorised the sheet. Authorisation is not settlement. Unmount when it fires and move the user to your own processing screen. Credit them when Meld’s TRANSACTION_CRYPTO_COMPLETE webhook reaches your backend — no SDK event tells you the money moved.

Troubleshooting