{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/meld/json-schema/meld-headless-order-onramp-response-schema.json",
  "title": "HeadlessOrderOnrampResponse",
  "description": "Headless onramp order response envelope",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/meld-headless-api-openapi.yml#/components/schemas/HeadlessOrderOnrampResponse",
  "type": "object",
  "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": "#/$defs/RequestPayload"
        }
      ]
    },
    "paymentMethodResponseDetails": {
      "description": "Method-specific response payload",
      "oneOf": [
        {
          "title": "ApplePayOrder",
          "allOf": [
            {
              "$ref": "#/$defs/ApplePayOrder"
            }
          ]
        },
        {
          "title": "BankTransferOrder",
          "allOf": [
            {
              "$ref": "#/$defs/BankTransferOrder"
            }
          ]
        },
        {
          "title": "CardOrder",
          "allOf": [
            {
              "$ref": "#/$defs/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."
    }
  },
  "$defs": {
    "ApplePayOrder": {
      "allOf": [
        {
          "$ref": "#/$defs/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": "#/$defs/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": "#/$defs/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"
    },
    "PaymentMethodResponseDetails": {},
    "ProviderData": {
      "description": "Provider-specific extension keyed by serviceProvider",
      "properties": {
        "serviceProvider": {
          "type": "string"
        }
      },
      "required": [
        "serviceProvider"
      ]
    },
    "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": "#/$defs/YellowcardData"
                }
              ]
            }
          ]
        },
        "redirectUrl": {
          "type": "string",
          "description": "Redirect URL"
        },
        "serviceProvider": {
          "type": "string",
          "description": "Service provider used for this order",
          "enum": [
            "NOAH",
            "DUENETWORK",
            "BRALE",
            "YELLOWCARD",
            "MERCURYO"
          ]
        },
        "sourceAmount": {
          "type": "number",
          "description": "Source amount in fiat currency"
        },
        "sourceCurrencyCode": {
          "type": "string",
          "description": "Source (fiat) currency code"
        }
      }
    },
    "YellowcardData": {
      "allOf": [
        {
          "$ref": "#/$defs/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"
    }
  }
}