The order model
One endpoint creates both kinds of order: Endpoint:POST /crypto/order/headless/onramp
paymentMethodType selects the method:
Transfers have their own endpoint,
POST /crypto/order/headless/transfer, and their own order shape.
The order
Every card and Apple Pay order comes back in the same envelope. OnlypaymentMethodResponseDetails differs by method, and fields with nothing in them are omitted rather than returned null.
Pass the whole response to the Meld SDK. Do not read individual fields to decide how to render: the SDK dispatches on the shape it is given, so adding a provider that uses an existing shape needs no change in your client.
External order IDs and idempotency
externalOrderId is your own reference. It must be unique per account; reusing one is rejected. Generate a fresh id for every attempt.
Send X-Idempotency-Key: <uuid> on order creation. A repeated key returns the original order rather than creating a second one.
Before you start
- A Meld API key with payment access (sandbox first, production for go-live)
- Headless onramps enabled on your account. Contact your Meld representative to enable Headless for your Meld account
- For production, your own account and credentials with each provider you use, except Coinbase. See provider credentials
- A webhook endpoint configured in Developer → Webhooks in the dashboard
Your customer must be KYC’d first
Create the customer and verify them through Unified KYC before their first order. Almost every provider refuses an order for a customer Meld has not cleared, and the refusal arrives at order creation — after the customer has entered an amount and expects to pay. Clearing the customer is not enough for providers that take their KYC as a share from Meld, such as Banxa. Name each of them inkycShareProviders when you start KYC, or add them later with a PATCH — see Share KYC with providers. A provider you leave out refuses the order with 403 KYC_NOT_COMPLETED.
Coinbase is the exception: it has a guest checkout, where the customer verifies their email and phone with a one-time code and accepts Coinbase’s agreements, with no KYC. Once the customer reaches Coinbase’s lifetime transaction limit, they must complete KYC to keep using Coinbase Apple Pay, through the limitUpgrade process. Stripe runs its own KYC, but complete Unified KYC first so the SDK can fill it. Transfers need no Unified KYC. See Providers.
Some providers provision their own customer record at order time and reject the call without an email. If your users can sign up without one, sync it onto the Meld customer with
PATCH /accounts/customers/{customerId} before the first order — a missing email surfaces later as a 404 naming a service-provider customer, which is harder to read than it sounds. Stripe and Coinbase check for it up front instead, and refuse the order with 403 VERIFICATION_REQUIRED and email: MISSING.Provider credentials
In production, every order runs on your own merchant account at the provider, using credentials registered to your Meld account. Coinbase is the exception: Meld sets it up on your account. In sandbox, Meld enables Stripe, Coinbase and Banxa on your sandbox account with its own sandbox credentials. They appear under Integrations as Shared Meld Integration, and you add no keys or webhooks for them. Ask your Meld representative to enable them.Environments
Configure the Meld SDK for the environment your backend created the order in.
Next steps
Pick what you are integrating:- Cards — the provider’s card form, mounted inside your checkout
- Apple Pay — present the system sheet in your app or site
- Transfers — send crypto the customer holds at an exchange, such as Coinbase, to their own wallet