> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meld.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a headless onramp order

> Creates a headless onramp order. Caller passes customer + provider + payment method and receives a method-specific payload in paymentMethodResponseDetails:

- ACH/SEPA/PIX → bank-transfer details to display.
- CREDIT_DEBIT_CARD → a provider-hosted widget, or `NativeSdkOrder` when renderMode=SDK_NATIVE.
- STRIPE + CREDIT_DEBIT_CARD/APPLE_PAY → one `NativeSdkOrder` shape; `paymentMethodType` selects the method. `destinationNetworkCode` and `X-Idempotency-Key` are required. Stripe remains disabled until rollout gates clear.
- MERCURYO + APPLE_PAY → native (non-widget) flow: a `sessionToken` (JWT) + `merchantTransactionId`. No redirect URL. The caller renders the Apple Pay sheet itself (Safari/WebView via ApplePaySession) and drives these endpoints, authenticated with header `X-Crypto-Session-Token: <sessionToken>`: on `onvalidatemerchant` call POST /crypto/session/mercuryo/apple-pay/validate-merchant with the event's validationURL; on `onpaymentauthorized` call POST /crypto/session/mercuryo/apple-pay/process with the Apple payToken + the `merchantTransactionId` from this response. The Mercuryo buy_token is fetched and stored server-side, so the caller never handles it. If native Apple Pay is unavailable for the route the call fails with INVALID_PAYMENT_METHOD (no redirect fallback).



## OpenAPI

````yaml /openapi/crypto-20260203.json post /crypto/order/headless/onramp
openapi: 3.1.0
info:
  title: CRYPTO
  termsOfService: urn:tos
  license:
    name: Apache 2.0
    url: https://springdoc.org
  version: '2026-02-03'
  description: ''
servers:
  - url: https://api-sb.meld.io
    description: Meld API sandbox
  - url: https://api.meld.io
    description: Meld API production
security: []
tags:
  - name: Retail Ramp
    description: ''
  - name: Headless
    description: ''
  - name: Payment
    description: ''
  - name: Session
    description: ''
paths:
  /crypto/order/headless/onramp:
    post:
      tags:
        - Headless
      summary: Create a headless onramp order
      description: >-
        Creates a headless onramp order. Caller passes customer + provider +
        payment method and receives a method-specific payload in
        paymentMethodResponseDetails:


        - ACH/SEPA/PIX → bank-transfer details to display.

        - CREDIT_DEBIT_CARD → a provider-hosted widget, or `NativeSdkOrder` when
        renderMode=SDK_NATIVE.

        - STRIPE + CREDIT_DEBIT_CARD/APPLE_PAY → one `NativeSdkOrder` shape;
        `paymentMethodType` selects the method. `destinationNetworkCode` and
        `X-Idempotency-Key` are required. Stripe remains disabled until rollout
        gates clear.

        - MERCURYO + APPLE_PAY → native (non-widget) flow: a `sessionToken`
        (JWT) + `merchantTransactionId`. No redirect URL. The caller renders the
        Apple Pay sheet itself (Safari/WebView via ApplePaySession) and drives
        these endpoints, authenticated with header `X-Crypto-Session-Token:
        <sessionToken>`: on `onvalidatemerchant` call POST
        /crypto/session/mercuryo/apple-pay/validate-merchant with the event's
        validationURL; on `onpaymentauthorized` call POST
        /crypto/session/mercuryo/apple-pay/process with the Apple payToken + the
        `merchantTransactionId` from this response. The Mercuryo buy_token is
        fetched and stored server-side, so the caller never handles it. If
        native Apple Pay is unavailable for the route the call fails with
        INVALID_PAYMENT_METHOD (no redirect fallback).
      operationId: /crypto-order-headless-onramp-create
      parameters:
        - name: Meld-Version
          in: header
          description: Dated API version to use for this request, e.g. `2026-02-03`.
          required: false
          schema:
            type: string
            example: '2026-02-03'
        - name: X-Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeadlessOrderOnrampRequest'
            example:
              countryCode: US
              destinationCurrencyCode: USDC
              destinationWalletAddress: <string>
              paymentMethodType: CREDIT_DEBIT_CARD
              serviceProvider: NOAH
              sourceAmount: 200
              sourceCurrencyCode: USD
        required: true
      responses:
        '201':
          description: Headless order created
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HeadlessOrderOnrampResponse'
        '400':
          description: 'Bad Request : check request values and format'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Unauthenticated or authenticated with insufficient access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    HeadlessOrderOnrampRequest:
      type: object
      description: Request to create a headless onramp order
      properties:
        clientIpAddress:
          type: string
          description: The end-user's IP address. Required by some service providers.
        countryCode:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
          example: US
          minLength: 1
        customerId:
          type: string
          description: >-
            Meld customer id (one of customerId / externalCustomerId is
            required)
        customerPhoneNumber:
          type: string
          description: Customer phone number — required for MOBILE_MONEY
        destinationCurrencyCode:
          type: string
          description: Destination cryptocurrency code
          example: USDC
          minLength: 1
        destinationWalletAddress:
          type: string
          description: Wallet address to receive the cryptocurrency
          minLength: 1
        externalCustomerId:
          type: string
          description: >-
            Caller's external customer id (one of customerId /
            externalCustomerId is required)
        externalOrderId:
          type: string
          description: Caller's reference for the order; unique per account when provided
        paymentMethodType:
          type: string
          description: Payment method type
          enum:
            - CREDIT_DEBIT_CARD
            - APPLE_PAY
            - ACH
            - SEPA
            - PIX
            - MOBILE_MONEY
        providerData:
          description: Provider-specific extension; subtype keyed by serviceProvider
          oneOf:
            - title: YellowcardData
              allOf:
                - $ref: '#/components/schemas/YellowcardData'
        redirectUrl:
          type: string
          description: Redirect URL — required for CARD/REDIRECT flows
        serviceProvider:
          type: string
          description: Service provider to use for the order
          enum:
            - NOAH
            - DUENETWORK
            - BRALE
            - YELLOWCARD
            - MERCURYO
          example: NOAH
        sourceAmount:
          type: number
          description: Source amount
          example: 200
          minimum: 0
        sourceCurrencyCode:
          type: string
          description: Source currency code (ISO 4217)
          example: USD
          minLength: 1
      required:
        - countryCode
        - destinationCurrencyCode
        - destinationWalletAddress
        - paymentMethodType
        - serviceProvider
        - sourceAmount
        - sourceCurrencyCode
    HeadlessOrderOnrampResponse:
      type: object
      description: Headless onramp order response envelope
      properties:
        customerId:
          type: string
          description: Meld customer id
        externalCustomerId:
          type: string
          description: Caller's external customer id
        externalOrderId:
          type: string
          description: Caller's external order id
        id:
          type: string
          description: Unique order ID for tracking the onramp order
        payload:
          description: Echo of the integrator's request payload for this order
          allOf:
            - $ref: '#/components/schemas/RequestPayload'
        paymentMethodResponseDetails:
          description: Method-specific response payload
          oneOf:
            - title: ApplePayOrder
              allOf:
                - $ref: '#/components/schemas/ApplePayOrder'
            - title: BankTransferOrder
              allOf:
                - $ref: '#/components/schemas/BankTransferOrder'
            - title: CardOrder
              allOf:
                - $ref: '#/components/schemas/CardOrder'
        paymentMethodType:
          type: string
          description: Payment method type for this order
          enum:
            - CREDIT_DEBIT_CARD
            - APPLE_PAY
            - ACH
            - SEPA
            - PIX
            - MOBILE_MONEY
        serviceProviderDetails:
          type: object
          additionalProperties: {}
          description: >-
            Raw provider receiving-bank details (untyped passthrough). Present
            for bank-transfer methods when the provider returns them; carries
            fields that have no typed home on paymentMethodResponseDetails (e.g.
            beneficiary/company name, bank name, address). Omitted when empty.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Stable identifier for the failure.
        errors:
          type: array
          items:
            type: string
          description: What was rejected, one entry per field or rule.
        message:
          type: string
          description: A description of what went wrong.
        requestId:
          type: string
          description: Quote this when asking Meld about a specific failure.
        serviceProviderDetails:
          type: object
          properties:
            code:
              type: string
              description: The provider's own error code, when it sent one.
            message:
              type: string
              description: The provider's own message.
          example:
            code: '5034'
            message: >-
              Digital currency and blockchain combination is restricted for
              customer's country
          description: >-
            The provider's own error detail, when the failure came from a
            service provider. Usually `code` and `message`; a few providers pass
            their own body through, so other keys can appear.
          additionalProperties: {}
        timestamp:
          type: string
          format: date-time
          description: >-
            When the failure occurred. ISO 8601, UTC
            (`YYYY-MM-DDThh:mm:ss.sss+00:00`).
          example: '2026-08-14T09:41:22.482+00:00'
    YellowcardData:
      allOf:
        - $ref: '#/components/schemas/ProviderData'
        - type: object
          properties:
            subaccountCustomerId:
              type: string
              description: >-
                Optional Meld customer id used to track the business sub-account
                this transaction belongs to when multiple businesses operate
                under one Meld account.
            externalSubaccountCustomerId:
              type: string
              description: >-
                Optional external identifier for the sub-account customer this
                transaction belongs to. Used for tracking when multiple
                businesses operate under one Meld account. A sub-account
                customer must be created first before it can be referenced.
      description: Yellowcard-specific provider data
    RequestPayload:
      type: object
      description: Echo of the integrator's request payload for this order
      properties:
        countryCode:
          type: string
          description: Country code
        customerId:
          type: string
          description: Meld customer id
        customerPhoneNumber:
          type: string
          description: Customer phone number
        destinationCurrencyCode:
          type: string
          description: Destination cryptocurrency code
        destinationWalletAddress:
          type: string
          description: Destination wallet address
        externalCustomerId:
          type: string
          description: Caller's external customer id
        externalOrderId:
          type: string
          description: Caller's external order id
        paymentMethodType:
          type: string
          description: Requested payment method type
          enum:
            - CREDIT_DEBIT_CARD
            - APPLE_PAY
            - ACH
            - SEPA
            - PIX
            - MOBILE_MONEY
        providerData:
          description: Provider-specific request data
          oneOf:
            - title: YellowcardData
              allOf:
                - $ref: '#/components/schemas/YellowcardData'
        redirectUrl:
          type: string
          description: Redirect URL
        serviceProvider:
          type: string
          description: Service provider used for this order
          enum:
            - NOAH
            - DUENETWORK
            - BRALE
            - YELLOWCARD
            - MERCURYO
          example: NOAH
        sourceAmount:
          type: number
          description: Source amount in fiat currency
        sourceCurrencyCode:
          type: string
          description: Source (fiat) currency code
    ApplePayOrder:
      allOf:
        - $ref: '#/components/schemas/PaymentMethodResponseDetails'
        - type: object
          properties:
            sessionToken:
              type: string
              description: >-
                Session JWT used to authenticate the /crypto/session/* Apple Pay
                endpoints
            merchantTransactionId:
              type: string
              description: >-
                Merchant transaction id to pass into /apple-pay/process; equals
                the session id
      description: >-
        Apple Pay response — present when paymentMethodType == APPLE_PAY. Native
        (non-widget) flow: the caller renders the Apple Pay sheet on its own
        surface, then drives the existing session-token endpoints (GET
        /crypto/session/applepay/paymentsession, POST
        /crypto/session/mercuryo/apple-pay/validate-merchant, POST
        /crypto/session/mercuryo/apple-pay/process) authenticated with
        sessionToken. There is no provider-hosted widget URL.
    BankTransferOrder:
      allOf:
        - $ref: '#/components/schemas/PaymentMethodResponseDetails'
        - type: object
          properties:
            accountNumber:
              type: string
              description: Bank account number; populated for ACH
            routingNumber:
              type: string
              description: Bank routing number; populated for ACH
            iban:
              type: string
              description: IBAN; populated for SEPA
            bic:
              type: string
              description: BIC / SWIFT code; populated for SEPA and wire
            pixKey:
              type: string
              description: PIX key; populated for PIX
            mobileMoneyReference:
              type: string
              description: Mobile money reference; populated for MOBILE_MONEY
            paymentReference:
              type: string
              description: >-
                Payment reference the payer must quote on the incoming bank
                transfer so the provider can correlate the inbound funds to this
                order. For SEPA (Due) this is the transfer memo. Populated only
                when the provider issues the reference at order-creation time;
                null otherwise.
      description: >-
        Bank-transfer response — present for ACH, SEPA, PIX, MOBILE_MONEY. Only
        the rail-relevant fields are populated per response; the others are
        null.
    CardOrder:
      allOf:
        - $ref: '#/components/schemas/PaymentMethodResponseDetails'
        - type: object
          properties:
            serviceProviderWidgetUrl:
              type: string
              description: Provider-hosted widget URL
            renderMode:
              type: string
              description: Render mode for the card payment surface
              enum:
                - IFRAME
                - REDIRECT
      description: >-
        Card-method response — present when paymentMethodType ==
        CREDIT_DEBIT_CARD
    ProviderData:
      description: Provider-specific extension keyed by serviceProvider
      discriminator:
        propertyName: serviceProvider
      properties:
        serviceProvider:
          type: string
      required:
        - serviceProvider
    PaymentMethodResponseDetails: {}
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      x-default: BASIC <Meld API Key>

````