---
title: "Create a crypto widget"
method: POST
path: "/crypto/session/widget"
tags: ["Retail Ramp"]
---

# Create a crypto widget

`POST /crypto/session/widget`

Use this endpoint to create a crypto widget for a session to buy or sell crypto.

## Request body

- SessionTokenForWidgetRequestV20231219
  - `bypassKyc` boolean — 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` string — Meld generated unique identifier for your customer. This should be used to track customer activity.
  - `externalCustomerId` string — Your unique identifier for your customer. If maintaining your own customer management system this can also be used for tracking customer activity.
  - `externalSessionId` string — Your reference id for your widget session, if you use this optional field you must pass in a unique value each time
  - `externalSubaccountCustomerId` string — 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` union, required — Data related to the session
    - object
      - `clientIpAddress` string — The client's IP address
      - `countryCode` string, required — Two-letter country code (ISO 3166-1 alpha-2)
      - `destinationCurrencyCode` string, required — The cryptocurrency the customer is buying (e.g. BTC, ETH).
      - `institutionId` string — 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` object — KYC verification information for token passthrough
        - `kycProvider` 'SUMSUB' — The KYC provider that issued the token
        - `kycShareToken` string — 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.
      - `lockFields` string[] — 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.
      - `paymentMethodType` string — Payment Method Type The 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` string — The url to redirect to following completion of the widget flow
      - `refundWalletAddress` string — 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` 'ALCHEMYPAY' | 'BANXA' | 'BILIRA' | 'BINANCECONNECT' | 'BINANCEPAY' | 'BLOCKCHAINDOTCOM' | 'BOOMFI' | 'BTCDIRECT' | 'COINBASEPAY' | 'FONBNK' | 'GUARDARIAN' | 'KOYWE' | 'KRYPTONIM' | 'MERCURYO' | 'MESH' | 'MESO' | 'ONMETA' | 'ONRAMPMONEY' | 'PAYBIS' | 'PAYPAL' | 'RAMP' | 'REVOLUT' | 'ROBINHOOD' | 'SARDINE' | 'SHIFT4' | 'SIMPLEX' | 'SKRILLCRYPTO' | 'STRIPE' | 'SWAPPED' | 'TOPPER' | 'TRANSAK' | 'TRANSFI' | 'UNLIMIT' | 'YELLOWCARD', required — The service provider used for this transaction Reference [Crypto supported service providers](https://www.meld.io/coverage/service-providers) for a full list of supported service providers
      - `sourceAmount` string, required — The amount of source currency your customer wants tosend in this transaction (e.g., 50.05)
      - `sourceCurrencyCode` string, required — The fiat currency the user is buying crypto with (e.g. USD, EUR).
      - `walletAddress` string, required — Your customer's wallet address
      - `walletTag` string — Your customer's wallet tag/destination tag/memo. This field is required for certain cryptocurrencies.
    - object
      - `clientIpAddress` string — The client's IP address
      - `countryCode` string, required — Two-letter country code (ISO 3166-1 alpha-2)
      - `destinationCurrencyCode` string, required — The fiat currency the customer is selling crypto for (e.g. USD, EUR).
      - `kycInfo` object — KYC verification information for token passthrough
        - `kycProvider` 'SUMSUB' — The KYC provider that issued the token
        - `kycShareToken` string — 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.
      - `lockFields` string[] — 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.
      - `paymentMethodType` string — Payment Method Type The 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` boolean — 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` string — The url to redirect to following completion of the widget flow
      - `refundWalletAddress` string — 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` 'ALCHEMYPAY' | 'BANXA' | 'BILIRA' | 'BINANCECONNECT' | 'BINANCEPAY' | 'BLOCKCHAINDOTCOM' | 'BOOMFI' | 'BTCDIRECT' | 'COINBASEPAY' | 'FONBNK' | 'GUARDARIAN' | 'KOYWE' | 'KRYPTONIM' | 'MERCURYO' | 'MESH' | 'MESO' | 'ONMETA' | 'ONRAMPMONEY' | 'PAYBIS' | 'PAYPAL' | 'RAMP' | 'REVOLUT' | 'ROBINHOOD' | 'SARDINE' | 'SHIFT4' | 'SIMPLEX' | 'SKRILLCRYPTO' | 'STRIPE' | 'SWAPPED' | 'TOPPER' | 'TRANSAK' | 'TRANSFI' | 'UNLIMIT' | 'YELLOWCARD', required — The service provider used for this transaction Reference [Crypto supported service providers](https://www.meld.io/coverage/service-providers) for a full list of supported service providers
      - `sourceAmount` string, required — The amount of source currency your customer wants tosend in this transaction (e.g., 50.05)
      - `sourceCurrencyCode` string, required — The cryptocurrency the customer is selling (e.g. BTC, ETH).
      - `walletAddress` string — Your customer's wallet address. Not required for selling crypto.
      - `walletTag` string — Your customer's wallet tag/destination tag/memo. This field is required for certain cryptocurrencies.
    - object
      - `clientIpAddress` string — The client's IP address
      - `countryCode` string, required — Two-letter country code (ISO 3166-1 alpha-2)
      - `institutionId` string — 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` object — KYC verification information for token passthrough
        - `kycProvider` 'SUMSUB' — The KYC provider that issued the token
        - `kycShareToken` string — 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.
      - `lockFields` string[] — 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.
      - `redirectUrl` string — The url to redirect to following completion of the widget flow
      - `serviceProvider` 'ALCHEMYPAY' | 'BANXA' | 'BILIRA' | 'BINANCECONNECT' | 'BINANCEPAY' | 'BLOCKCHAINDOTCOM' | 'BOOMFI' | 'BTCDIRECT' | 'COINBASEPAY' | 'FONBNK' | 'GUARDARIAN' | 'KOYWE' | 'KRYPTONIM' | 'MERCURYO' | 'MESH' | 'MESO' | 'ONMETA' | 'ONRAMPMONEY' | 'PAYBIS' | 'PAYPAL' | 'RAMP' | 'REVOLUT' | 'ROBINHOOD' | 'SARDINE' | 'SHIFT4' | 'SIMPLEX' | 'SKRILLCRYPTO' | 'STRIPE' | 'SWAPPED' | 'TOPPER' | 'TRANSAK' | 'TRANSFI' | 'UNLIMIT' | 'YELLOWCARD', required — The service provider used for this transaction Reference [Crypto supported service providers](https://www.meld.io/coverage/service-providers) for a full list of supported service providers
      - `sourceAmount` string — 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` string[], required — 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.
      - `walletAddress` string — Your customer's wallet address
      - `walletTag` string — Your customer's wallet tag/destination tag/memo. This field is required for certain cryptocurrencies.
  - `sessionType` 'BUY' | 'SELL' | 'TRANSFER', required — The type of widget session to create
  - `subaccountCustomerId` string — Optional Meld customer id used to track the business sub-account this transaction belongs to when multiple businesses operate under one Meld account.

## Response `200`

Widget created

## Other responses

- `400` — Bad Request : check request values and format
- `401` — Invalid credentials
- `403` — Unauthenticated or authenticated with insufficient access
- `500` — Server Error. This applies to all 5xx errors, including but not limited to 500, 501, 502, 503, and 504 errors. You should treat all of these errors the same.

---

[API](https://skmtc.net/meld/apis/bank-linking.md) · [All operations](https://skmtc.net/meld/apis/bank-linking/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/meld/bank-linking/versions/818d6079a611/schema)