Meld KYCes the User

This guide is for developers who want Meld to host the KYC flow. You’ll call Meld’s API to launch the KYC provider UI, KYC the user, then route them to an onramp that accepts the shared KYC token so they don’t need to verify again.

Summary of the steps

Create a Meld customer and store the customerId
Check whether that customer is already KYC-approved
If not, launch Meld’s hosted KYC link and wait for the APPROVED webhook
Start the transaction with bypassKyc: true

Before you begin

You have contacted your Meld account manager to enable a KYC provider for you
You can store the Meld customerId against each of your users
You have a webhook endpoint configured to receive CUSTOMER_KYC_STATUS_CHANGE events (or you plan to poll)

To test this flow in Meld’s sandbox, see KYC testing.

If the user’s KYC status ends in REJECTED, the user has failed KYC. They can retry once, but a user who fails KYC here will very likely also fail directly with any onramp.

To enable this flow, do the following:

Step 1: Create a Meld customer

This step is required for the user to skip logging into the onramp, and is a one-time setup per user. Call POST /accounts/customers and pass in the user’s first name, last name, email address, phone number, and birthday.

Request

{
  "name": {
    "firstName": "First",
    "lastName": "Last"
  },
  "email": "test@user.com",
  "dateOfBirth": "1990-01-30",
  "phone": "+15551234567",
  "externalCustomerId": "testUser1"  // optional, for you to pass in your own reference id for the user
}

Field	Notes
`dateOfBirth`	ISO date `yyyy-MM-dd`
`externalCustomerId`	Your internal user id (optional but recommended). Response echoes it as `externalCustomerId`.
`phone`	E.164 format

Response

{
  "name": {
    "firstName": "First",
    "lastName": "Last"
  },
  "email": "test@user.com",
  "dateOfBirth": "1990-01-30",
  "phone": "+15551234567",
  "externalCustomerId": "testUser1",
  "id": "WmYumpKThCLWdgdK4fu2oh", // customerId to pass into /widget
  "key": "N/A",
  "accountId": "W932jkkjn2jnjn",
  "addresses": [],
  "serviceProviderCustomers": [],
  "subAccountId": "N/A"
}

The id in the response is now the Meld customerId of that user. The customerId is critical for all of the following steps, make sure you safely store it and tie it to the user in your system.

Step 2: Check if the User is Already KYCed

You can keep track in your own system if a particular user has been KYCed via Meld. If you don’t keep track, you can call GET /accounts/customers, passing the customerId of the user, to check whether the user has already been KYCed with Meld. If the user has been KYCed successfully, then you do not have to KYC the user again. The response will look something like this for a KYCed user, with the key field being serviceProviderCustomers.kyc.status.

Response

{
  "id": "WmYumpKThCLWdgdK4fu2oh",
  "accountId": "W932jkkjn2jnjn",
  "externalCustomerId": "testUser1",
  "name": {
	"firstName": "First",
	"lastName": "Last"
  },
  "dateOfBirth": "1990-01-30",
  "email": "test@user.com",
  "phone": "+15551234567",
  "addresses": [],
  "serviceProviderCustomers": [
  {
	"serviceProvider": "SUMSUB",  // sample KYC provider
	"id": "699e243ff55da9f719ad1d15",
	"serviceProviderAccessProfileId": "WmZLEt7PVzFKYNvdyHLmc7",
	"kyc": {
	  "status": "APPROVED",
	  "updatedAt": "2026-02-24T22:22:43.012616Z"
	},
	"wallets": [],
	"serviceProviderDetails": null,
	"createdAt": "2026-02-24T22:20:47.148504Z",
	"deletedAt": null,
	"status": "ACTIVE"
  }
  ],
  "status": "ACTIVE",
  "subAccountId": null
}

If the user has not been successfully KYCed, then either serviceProviderCustomers.kyc.status will show a status other than APPROVED, or the serviceProviderCustomers object will be blank, depending on if the user has attempted KYC previously or not. Either way, the user will have to be KYCed successfully with Meld first.

Step 3: Have Meld KYC the User

This step is only needed if the user isn’t already successfully KYCed. In other words, if the value of serviceProviderCustomers.kyc.status in the previous step is APPROVED then you can skip this step. To KYC the user, call POST /accounts/customers/{customerId}/kyc/initiate. The customerId is in the path. Note that Sumsub is being used as the sample KYC provider in these requests.

Request

{
  "serviceProvider": "SUMSUB",
  "mode": "HOSTED_URL"
}

The response will include a url that you should then launch from your UI.

Response

{
  "customerId": "WmYumpKThCLWdgdK4fu2oh",
  "serviceProvider": "SUMSUB",
  "status": "PENDING",
  "url": "https://kyclink.com"
}

As the user goes through the KYC flow, you will receive webhooks informing you that the KYC status of the user has changed. The body of the webhook will look like this:

{
  "eventType": "CUSTOMER_KYC_STATUS_CHANGE",
  "eventId": "4cWK83avakzy8jG4ztmBUk",
  "timestamp": "2026-02-25T18:55:08.968360756Z",
  "accountId": "W9jSUfLiRWx1GkaMGt7DTT",
  "profileId": "WmZ1rqsv532RYW9ELxM4eo",
  "version": "2026-02-02",
  "payload": {
    "requestId": "4456e4e9b0174c53b962227df6766ca7",
    "customerId": "WmYumpKThCLWdgdK4fu2oh",
    "serviceProvider": "SUMSUB",
    "status": "APPROVED",
    "statusUpdatedAt": "2026-02-25T18:55:08.960052Z"
  }
}

Each time you receive a webhook, repeat Step 2 until the serviceProviderCustomers.kyc.status shows as APPROVED. If the serviceProviderCustomers.kyc.status is REJECTED, this means the user has failed KYC. They may retry submit with corrected data. If they still fail, then the user will have to try KYCing with the onramp directly, in the onramp’s widget.

Step 4: Initiate a transaction

Pass Meld the customerId of the user when you call POST /crypto/session/widget. Make sure to include the param "bypassKyc": true, which tells Meld to look up that customer’s KYC information and forward it to the onramp.

Request

{
  "sessionData": {
    "countryCode": "US",
    "destinationCurrencyCode": "BTC",
    "serviceProvider": "MERCURYO",
    "sourceAmount": "100",
    "sourceCurrencyCode": "USD",
    "walletAddress": "1EEo4ioA4spdJ2ZxiSQ1hWsp3Ve81ZRZ2F"
  },
  "sessionType": "BUY",
  "bypassKyc": true,
  "customerId": "WmYumpKThCLWdgdK4fu2oh"        // should be the same as the customer created above
}

Response

{
  "id": "WmYtVn52MCZkXQSdCFDU8N",
  "externalSessionId": null,
  "externalCustomerId": null,
  "customerId": "WmYumpKThCLWdgdK4fu2oh",
  "widgetUrl": "https://meldcrypto.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ7.eyJpc3MiOiJtZWxkLmlvIiwiaWF0IjoxNzcxMjY3MDM4LCJzdWIiOiJjcnlwdG8iLCJleHAiOjE3NzEyNjg4MzgsImFjY291bnRJZCI6Ilc5a2c5aVAxc2JweVpwdFFEY0NNSnUiLCJzZXNzaW9uSWQiOiJXbVl0Vm41Mk1DWmtYUVNkQ0ZEVThOIn0.eqFYseggwUyv-F7WyO-LKEhwEqLiWVOmAV4lNjuth60",
  "serviceProviderWidgetUrl": "https://exchange.mercuryo.io?widget_id=34c04adf-d04a-42de-a4aa-609a302b24tz&currency=BTC&fiat_currency=USD&fiat_amount=100&address=1EEo4ioA4spdJ2ZxiSQ1hWsp3Ve81ZRZ2F&type=buy&network=BITCOIN&merchant_transaction_id=WmYtVmRXgDnavemEzb3k6K&redirect_url=https%3A%2F%2Fmeldcrypto.com&country_code=US&email&payment_method=card&signature=zxcvbnmasdfghjkl",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtZWxkLmlvIiwiaWF0IjoxNzcxMjY3MDM4LCJzdWIiOiJjcnlwdG8iLCJleHAiOjE3NzEyNjg4MzgsImFjY291bnRJZCI6Ilc5a2c5aVAxc2JweVpwdFFEY0NNSnUiLCJzZXNzaW9uSWQiOiJXbVl0Vm41Mk1DWmtYUVNkQ0ZEVThOIn0.eqFYseggwUyv-F7WyO-LKEhwEqLiWVOmAV4lNjuth60"
}

If you executed every step correctly, then when you open either the widgetUrl or serviceProviderWidgetUrl, then the user go straight to the onramp’s payment screen, as seen in this demo video.

And that’s it! Congrats, you are now using Meld’s Unified KYC product to enhance your users’ experience!

Welcome

AI Toolkit

Meld API

Stablecoins & Digital Assets

Bank Linking

Meld KYCes the User

Summary of the steps

Before you begin

Step 1: Create a Meld customer

Request

Response

Step 2: Check if the User is Already KYCed

Response

Step 3: Have Meld KYC the User

Request

Response

Step 4: Initiate a transaction

Request

Response

​Summary of the steps

​Before you begin

​Step 1: Create a Meld customer

​Request

​Response

​Step 2: Check if the User is Already KYCed

​Response

​Step 3: Have Meld KYC the User

​Request

​Response

​Step 4: Initiate a transaction

​Request

​Response

Summary of the steps

Before you begin

Step 1: Create a Meld customer

Request

Response

Step 2: Check if the User is Already KYCed

Response

Step 3: Have Meld KYC the User

Request

Response

Step 4: Initiate a transaction

Request

Response