{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/meld/json-schema/meld-session-token-for-widget-request-v20231219-schema.json",
  "title": "SessionTokenForWidgetRequestV20231219",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/meld-retail-ramp-api-openapi.yml#/components/schemas/SessionTokenForWidgetRequestV20231219",
  "type": "object",
  "properties": {
    "bypassKyc": {
      "type": "boolean",
      "default": false,
      "description": "When true, the system will automatically look up the customer's KYC status and generate a share token if KYC is approved. Requires a valid customerId or externalCustomerId."
    },
    "customerId": {
      "type": "string",
      "description": "Meld generated unique identifier for your customer. This should be used to track customer activity."
    },
    "externalCustomerId": {
      "type": "string",
      "description": "Your unique identifier for your customer. If maintaining your own customer management system this can also be used for tracking customer activity."
    },
    "externalSessionId": {
      "type": "string",
      "description": "Your reference id for your widget session, if you use this optional field you must pass in a unique value each time"
    },
    "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."
    },
    "sessionData": {
      "description": "Data related to the session",
      "allOf": [
        {
          "$ref": "#/$defs/SessionDataInputV20231219"
        }
      ]
    },
    "sessionType": {
      "type": "string",
      "description": "The type of widget session to create",
      "enum": [
        "BUY",
        "SELL",
        "TRANSFER"
      ]
    },
    "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."
    }
  },
  "required": [
    "sessionData",
    "sessionType"
  ],
  "$defs": {
    "CryptoBuySessionData": {
      "type": "object",
      "properties": {
        "clientIpAddress": {
          "type": "string",
          "description": "The client's IP address"
        },
        "countryCode": {
          "type": "string",
          "description": "Two-letter country code (ISO 3166-1 alpha-2)",
          "default": "US"
        },
        "destinationCurrencyCode": {
          "type": "string",
          "description": "The cryptocurrency the customer is buying (e.g. BTC, ETH).",
          "minLength": 1,
          "default": "BTC"
        },
        "institutionId": {
          "type": "string",
          "description": "If provided, the institution to bypass the institution selection screen in the service provider's widget. Currently this is only supported for MESH widget sessions."
        },
        "kycInfo": {
          "description": "Optional KYC information for token passthrough. When provided with a valid KYC token from a supported provider, the verification can be transferred to downstream providers that support it.",
          "allOf": [
            {
              "$ref": "#/$defs/KycInfo"
            }
          ]
        },
        "lockFields": {
          "type": "array",
          "description": "Where supported by the Service Provider, Meld can help you lock the cryptocurrency and/or wallet address fields within the widget. Enable this by passing in the \"destinationCurrencyCode\" and/or \"walletAddress\" as strings in this field. See [this page](https://docs.meld.io/docs/white-label-cutomization#locking-fields) for more details.",
          "items": {
            "type": "string",
            "enum": [
              "cryptoCurrency",
              "destinationCurrencyCode",
              "sourceCurrencyCode",
              "walletAddress",
              "sourceAmount",
              "paymentMethodType"
            ]
          }
        },
        "paymentMethodType": {
          "type": "string",
          "description": "Payment Method Type\n\nThe paymentMethodType and paymentMethodSubType included here are a sample set. Review the [Supported Payment Methods](https://www.meld.io/coverage/payment-methods) section to view the complete list."
        },
        "redirectUrl": {
          "type": "string",
          "description": "The url to redirect to following completion of the widget flow"
        },
        "refundWalletAddress": {
          "type": "string",
          "description": "Optional wallet address where the swap provider sends refunds if the swap fails. Only applicable for ramp+swap (e.g. fiat->USDC->USDH) sessions."
        },
        "serviceProvider": {
          "type": "string",
          "description": "The service provider used for this transaction\n\nReference [Crypto supported service providers](https://www.meld.io/coverage/service-providers) for a full list of supported service providers",
          "enum": [
            "ACROSS",
            "AEROPAY",
            "AKOYA",
            "ALCHEMYPAY",
            "APPLEPAY",
            "AUTHORIZENET",
            "BANXA",
            "BILIRA",
            "BINANCECONNECT",
            "BINANCEPAY",
            "BLOCKCHAINDOTCOM",
            "BOOMFI",
            "BRAINTREE",
            "BRALE",
            "BTCDIRECT",
            "CASHAPP",
            "CHECKOUT",
            "CIRCLE",
            "COINBASEPAY",
            "COINFLOW",
            "DUENETWORK",
            "ELDORADO",
            "FINICITY",
            "FLASHNET",
            "FONBNK",
            "GUARDARIAN",
            "HARBOUR",
            "KOYWE",
            "KRYPTONIM",
            "MERCURYO",
            "MESH",
            "MESO",
            "MOONPAY",
            "MOOV",
            "MX",
            "NMI",
            "NOAH",
            "ONMETA",
            "ONRAMPMONEY",
            "PAYBIS",
            "PAYPAL",
            "PLAID",
            "RAMP",
            "REVOLUT",
            "ROBINHOOD",
            "ROUTERPROTOCOL",
            "SALTEDGE",
            "SALTEDGEPARTNERS",
            "SARDINE",
            "SHIFT4",
            "SHOPIFY",
            "SIMPLEX",
            "SKRILLCRYPTO",
            "SQUARE",
            "STRIPE",
            "SUMSUB",
            "SWAPPED",
            "TANGOCARD",
            "TELLER",
            "TOPPER",
            "TRANSAK",
            "TREMENDOUS",
            "TRANSFI",
            "UNLIMIT",
            "UPHOLD",
            "WYRE",
            "XANPOOL",
            "YELLOWCARD",
            "YODLEE"
          ],
          "default": "TRANSAK"
        },
        "sourceAmount": {
          "type": "string",
          "description": "The amount of source currency your customer wants tosend in this transaction (e.g., 50.05)",
          "minLength": 1,
          "default": "100"
        },
        "sourceCurrencyCode": {
          "type": "string",
          "description": "The fiat currency the user is buying crypto with (e.g. USD, EUR).",
          "minLength": 1,
          "default": "USD"
        },
        "walletAddress": {
          "type": "string",
          "description": "Your customer's wallet address",
          "minLength": 1,
          "default": "1EEo4ioA4spdJ2ZxiSQ1hWsp3Ve81ZRZ2F"
        },
        "walletTag": {
          "type": "string",
          "description": "Your customer's wallet tag/destination tag/memo. This field is required for certain cryptocurrencies."
        }
      },
      "required": [
        "countryCode",
        "destinationCurrencyCode",
        "serviceProvider",
        "sourceAmount",
        "sourceCurrencyCode",
        "walletAddress"
      ],
      "title": "Buy Crypto"
    },
    "CryptoSellSessionData": {
      "type": "object",
      "properties": {
        "clientIpAddress": {
          "type": "string",
          "description": "The client's IP address"
        },
        "countryCode": {
          "type": "string",
          "description": "Two-letter country code (ISO 3166-1 alpha-2)",
          "minLength": 1
        },
        "destinationCurrencyCode": {
          "type": "string",
          "description": "The fiat currency the customer is selling crypto for (e.g. USD, EUR).",
          "minLength": 1
        },
        "kycInfo": {
          "description": "Optional KYC information for token passthrough. When provided with a valid KYC token from a supported provider, the verification can be transferred to downstream providers that support it.",
          "allOf": [
            {
              "$ref": "#/$defs/KycInfo"
            }
          ]
        },
        "lockFields": {
          "type": "array",
          "description": "Where supported by the Service Provider, Meld can help you lock the cryptocurrency and/or wallet address fields within the widget. Enable this by passing in the \"destinationCurrencyCode\" and/or \"walletAddress\" as strings in this field. See [this page](https://docs.meld.io/docs/white-label-cutomization#locking-fields) for more details.",
          "items": {
            "type": "string",
            "enum": [
              "cryptoCurrency",
              "destinationCurrencyCode",
              "sourceCurrencyCode",
              "walletAddress",
              "sourceAmount",
              "paymentMethodType"
            ]
          }
        },
        "paymentMethodType": {
          "type": "string",
          "description": "Payment Method Type\n\nThe paymentMethodType and paymentMethodSubType included here are a sample set. Review the [Supported Payment Methods](https://www.meld.io/coverage/payment-methods) section to view the complete list."
        },
        "redirectFlow": {
          "type": "boolean",
          "default": false,
          "description": "The user is redirected back to the wallet, and the wallet gets the amount, token, and wallet address to send money to from the SP’s API, then queues up a transfer in the wallet UI and the user just hits confirm"
        },
        "redirectUrl": {
          "type": "string",
          "description": "The url to redirect to following completion of the widget flow"
        },
        "refundWalletAddress": {
          "type": "string",
          "description": "Optional wallet address where the swap provider sends refunds if the swap fails. Only applicable for sell+swap (e.g. USDH->USDC->fiat) sessions. Defaults to walletAddress if not provided."
        },
        "serviceProvider": {
          "type": "string",
          "description": "The service provider used for this transaction\n\nReference [Crypto supported service providers](https://www.meld.io/coverage/service-providers) for a full list of supported service providers",
          "enum": [
            "ACROSS",
            "AEROPAY",
            "AKOYA",
            "ALCHEMYPAY",
            "APPLEPAY",
            "AUTHORIZENET",
            "BANXA",
            "BILIRA",
            "BINANCECONNECT",
            "BINANCEPAY",
            "BLOCKCHAINDOTCOM",
            "BOOMFI",
            "BRAINTREE",
            "BRALE",
            "BTCDIRECT",
            "CASHAPP",
            "CHECKOUT",
            "CIRCLE",
            "COINBASEPAY",
            "COINFLOW",
            "DUENETWORK",
            "ELDORADO",
            "FINICITY",
            "FLASHNET",
            "FONBNK",
            "GUARDARIAN",
            "HARBOUR",
            "KOYWE",
            "KRYPTONIM",
            "MERCURYO",
            "MESH",
            "MESO",
            "MOONPAY",
            "MOOV",
            "MX",
            "NMI",
            "NOAH",
            "ONMETA",
            "ONRAMPMONEY",
            "PAYBIS",
            "PAYPAL",
            "PLAID",
            "RAMP",
            "REVOLUT",
            "ROBINHOOD",
            "ROUTERPROTOCOL",
            "SALTEDGE",
            "SALTEDGEPARTNERS",
            "SARDINE",
            "SHIFT4",
            "SHOPIFY",
            "SIMPLEX",
            "SKRILLCRYPTO",
            "SQUARE",
            "STRIPE",
            "SUMSUB",
            "SWAPPED",
            "TANGOCARD",
            "TELLER",
            "TOPPER",
            "TRANSAK",
            "TREMENDOUS",
            "TRANSFI",
            "UNLIMIT",
            "UPHOLD",
            "WYRE",
            "XANPOOL",
            "YELLOWCARD",
            "YODLEE"
          ]
        },
        "sourceAmount": {
          "type": "string",
          "description": "The amount of source currency your customer wants tosend in this transaction (e.g., 50.05)",
          "minLength": 1
        },
        "sourceCurrencyCode": {
          "type": "string",
          "description": "The cryptocurrency the customer is selling (e.g. BTC, ETH).",
          "minLength": 1
        },
        "walletAddress": {
          "type": "string",
          "description": "Your customer's wallet address. Not required for selling crypto."
        },
        "walletTag": {
          "type": "string",
          "description": "Your customer's wallet tag/destination tag/memo. This field is required for certain cryptocurrencies."
        }
      },
      "required": [
        "countryCode",
        "destinationCurrencyCode",
        "serviceProvider",
        "sourceAmount",
        "sourceCurrencyCode"
      ],
      "title": "Sell Crypto"
    },
    "CryptoTransferSessionData": {
      "type": "object",
      "properties": {
        "clientIpAddress": {
          "type": "string",
          "description": "The client's IP address"
        },
        "countryCode": {
          "type": "string",
          "description": "Two-letter country code (ISO 3166-1 alpha-2)"
        },
        "institutionId": {
          "type": "string",
          "description": "If provided, the institution to bypass the institution selection screen in the service provider's widget. Currently this is only supported for MESH widget sessions."
        },
        "kycInfo": {
          "description": "Optional KYC information for token passthrough. When provided with a valid KYC token from a supported provider, the verification can be transferred to downstream providers that support it.",
          "allOf": [
            {
              "$ref": "#/$defs/KycInfo"
            }
          ]
        },
        "lockFields": {
          "type": "array",
          "description": "Where supported by the Service Provider, Meld can help you lock the cryptocurrency and/or wallet address fields within the widget. Enable this by passing in the \"destinationCurrencyCode\" and/or \"walletAddress\" as strings in this field. See [this page](https://docs.meld.io/docs/white-label-cutomization#locking-fields) for more details.",
          "items": {
            "type": "string",
            "enum": [
              "cryptoCurrency",
              "destinationCurrencyCode",
              "sourceCurrencyCode",
              "walletAddress",
              "sourceAmount",
              "paymentMethodType"
            ]
          }
        },
        "redirectUrl": {
          "type": "string",
          "description": "The url to redirect to following completion of the widget flow"
        },
        "serviceProvider": {
          "type": "string",
          "description": "The service provider used for this transaction\n\nReference [Crypto supported service providers](https://www.meld.io/coverage/service-providers) for a full list of supported service providers",
          "enum": [
            "ACROSS",
            "AEROPAY",
            "AKOYA",
            "ALCHEMYPAY",
            "APPLEPAY",
            "AUTHORIZENET",
            "BANXA",
            "BILIRA",
            "BINANCECONNECT",
            "BINANCEPAY",
            "BLOCKCHAINDOTCOM",
            "BOOMFI",
            "BRAINTREE",
            "BRALE",
            "BTCDIRECT",
            "CASHAPP",
            "CHECKOUT",
            "CIRCLE",
            "COINBASEPAY",
            "COINFLOW",
            "DUENETWORK",
            "ELDORADO",
            "FINICITY",
            "FLASHNET",
            "FONBNK",
            "GUARDARIAN",
            "HARBOUR",
            "KOYWE",
            "KRYPTONIM",
            "MERCURYO",
            "MESH",
            "MESO",
            "MOONPAY",
            "MOOV",
            "MX",
            "NMI",
            "NOAH",
            "ONMETA",
            "ONRAMPMONEY",
            "PAYBIS",
            "PAYPAL",
            "PLAID",
            "RAMP",
            "REVOLUT",
            "ROBINHOOD",
            "ROUTERPROTOCOL",
            "SALTEDGE",
            "SALTEDGEPARTNERS",
            "SARDINE",
            "SHIFT4",
            "SHOPIFY",
            "SIMPLEX",
            "SKRILLCRYPTO",
            "SQUARE",
            "STRIPE",
            "SUMSUB",
            "SWAPPED",
            "TANGOCARD",
            "TELLER",
            "TOPPER",
            "TRANSAK",
            "TREMENDOUS",
            "TRANSFI",
            "UNLIMIT",
            "UPHOLD",
            "WYRE",
            "XANPOOL",
            "YELLOWCARD",
            "YODLEE"
          ]
        },
        "sourceAmount": {
          "type": "string",
          "description": "The amount of source currency your customer wants totransfer (e.g., 50.05). It only applies if one source currency code is passed in."
        },
        "sourceCurrencyCodes": {
          "type": "array",
          "description": "Allowable crypto currencies for the customer to transfer (e.g. BTC, ETH). If the currency to transfer is already known, then this list should be singular and the customer will not have the option to select a different crypto currency in the service provider's widget. Alternatively, if the currency to transfer is not yet known and it is desired that the customer select it themselves in the service provider widget, then this list will restrict which crypto currencies are made available. However, this latter option of passing in multiple currencies is only supported by select service providers (MESH, ROBINHOOD). At least one currency must be passed in. The accompanying sourceAmount field should only be present if a single crypto currency is passed in.",
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "uniqueItems": true
        },
        "walletAddress": {
          "type": "string",
          "description": "Your customer's wallet address"
        },
        "walletTag": {
          "type": "string",
          "description": "Your customer's wallet tag/destination tag/memo. This field is required for certain cryptocurrencies."
        }
      },
      "required": [
        "countryCode",
        "serviceProvider",
        "sourceCurrencyCodes"
      ],
      "title": "Transfer Crypto"
    },
    "KycInfo": {
      "type": "object",
      "description": "KYC verification information for token passthrough",
      "properties": {
        "kycProvider": {
          "type": "string",
          "description": "The KYC provider that issued the token",
          "enum": [
            "SUMSUB"
          ]
        },
        "kycShareToken": {
          "type": "string",
          "description": "The shareable KYC token from the KYC provider (e.g., Sumsub share token). This token can be used to transfer verified KYC status to downstream providers. Required when kycProvider is specified."
        }
      }
    },
    "SessionDataInputV20231219": {
      "type": "object",
      "description": "Data related to the session",
      "oneOf": [
        {
          "title": "CryptoBuySessionData",
          "allOf": [
            {
              "$ref": "#/$defs/CryptoBuySessionData"
            }
          ]
        },
        {
          "title": "CryptoSellSessionData",
          "allOf": [
            {
              "$ref": "#/$defs/CryptoSellSessionData"
            }
          ]
        },
        {
          "title": "CryptoTransferSessionData",
          "allOf": [
            {
              "$ref": "#/$defs/CryptoTransferSessionData"
            }
          ]
        }
      ],
      "properties": {
        "clientIpAddress": {
          "type": "string",
          "description": "The client's IP address"
        },
        "kycInfo": {
          "description": "Optional KYC information for token passthrough. When provided with a valid KYC token from a supported provider, the verification can be transferred to downstream providers that support it.",
          "allOf": [
            {
              "$ref": "#/$defs/KycInfo"
            }
          ]
        },
        "lockFields": {
          "type": "array",
          "description": "Where supported by the Service Provider, Meld can help you lock the cryptocurrency and/or wallet address fields within the widget. Enable this by passing in the \"destinationCurrencyCode\" and/or \"walletAddress\" as strings in this field. See [this page](https://docs.meld.io/docs/white-label-cutomization#locking-fields) for more details.",
          "items": {
            "type": "string",
            "enum": [
              "cryptoCurrency",
              "destinationCurrencyCode",
              "sourceCurrencyCode",
              "walletAddress",
              "sourceAmount",
              "paymentMethodType"
            ]
          }
        },
        "redirectUrl": {
          "type": "string",
          "description": "The url to redirect to following completion of the widget flow"
        },
        "serviceProvider": {
          "type": "string",
          "description": "The service provider used for this transaction\n\nReference [Crypto supported service providers](https://www.meld.io/coverage/service-providers) for a full list of supported service providers",
          "enum": [
            "ALCHEMYPAY",
            "BANXA",
            "BILIRA",
            "BINANCECONNECT",
            "BINANCEPAY",
            "BLOCKCHAINDOTCOM",
            "BOOMFI",
            "BTCDIRECT",
            "COINBASEPAY",
            "FONBNK",
            "GUARDARIAN",
            "KRYPTONIM",
            "KOYWE",
            "MESH",
            "MERCURYO",
            "MESO",
            "ONMETA",
            "ONRAMPMONEY",
            "PAYBIS",
            "PAYPAL",
            "RAMP",
            "REVOLUT",
            "ROBINHOOD",
            "SARDINE",
            "SHIFT4",
            "SIMPLEX",
            "SKRILLCRYPTO",
            "STRIPE",
            "SWAPPED",
            "TOPPER",
            "TRANSAK",
            "TRANSFI",
            "UNLIMIT",
            "YELLOWCARD"
          ]
        },
        "walletTag": {
          "type": "string",
          "description": "Your customer's wallet tag/destination tag/memo. This field is required for certain cryptocurrencies."
        }
      },
      "required": [
        "serviceProvider"
      ]
    }
  }
}