Skip to content

Sumsub Integration for Crypto and Payment Firms

Protofire builds Sumsub integrations for crypto and payment firms. Your ledger holds a withdrawal until Sumsub's webhook clears it. Other VASPs' Travel Rule requests get answers, and your core shows each KYC status. In 2021 we built the DEX core for Swarm Markets, a BaFin-licensed DEX at launch.

Luis Medeiros

Reviewed by Luis Medeiros, Field CTO at ProtofireLast reviewed: November 2026

On this page
  1. Overview
  2. Who decides
  3. Unfinished exchanges
  4. What you get
  5. Withdrawal hold
  6. Incoming requests
  7. Sumsub facts
  8. By firm type
  9. Why Protofire
  10. Data and DORA
  11. How work starts
  12. Not the right fit
  13. Related guides and services
  14. FAQ

Work shipped for 60+ networks and 95+ protocols, including

  • Chainlink
  • Ethereum
  • Solana
  • Safe
  • Ripple
  • Aave

Sumsub's review and Travel Rule results move independently

Sumsub's review decision on a transaction and its Travel Rule status move independently. So once you have chosen Sumsub for KYC and the Travel Rule, your firm writes its own rule for each pairing. Your Sumsub integration then has to say what the ledger does under that rule.

For example, a customer asks to withdraw crypto, and Sumsub approves the transaction while its Travel Rule exchange has expired. Sumsub's documentation names this case: a transaction "approved by your rules while its Travel Rule exchange has the expired status". It adds that "there is no platform-wide default action for expired exchanges" (Sumsub). If nothing in your systems joins the two results, the withdrawal is left between two facts that nobody has put together.

Who decides each Sumsub result

Sumsub returns a result for each applicant, each transaction and each Travel Rule exchange.Your compliance team sets what each result does to the customer and the money.

Applicant review

Sumsub returns: The answer is GREEN or RED. A RED answer includes rejectLabels and either RETRY, where the applicant may resubmit, or FINAL, where the applicant may not (Sumsub).

Your team sets: Which labels freeze the account in your core. Your team also sets a guard that keeps clientComment off customer screens, because clientComment "should not be shown to your applicants".

Transfer

Sumsub returns: A review decision and, separately, a Travel Rule status such as finished or expired (Sumsub).

Your team sets: The rules and who reviews held transfers. Your team also sets the action on an expired exchange, because Sumsub sets no default.

Self-hosted wallets

Sumsub returns: A signature check, a Satoshi test, a self-declaration form or manual review (Sumsub).

Your team sets: The method your regulator accepts. In the EU, that is at least one method from para 83 of EBA/GL/2024/11.

The final call

Sumsub returns: Services that Sumsub's Terms call "not intended to be used as the sole basis for any business decision".

Your team sets: The decision on each customer and transfer, and the record of who took it.

[...] credit and financial institutions should include in their policies and procedures specifications setting out which remote customer onboarding functions and activities will be carried out or performed by the credit and financial institution, by third parties or by another outsourced service provider.
European Banking Authority (EBA), Guidelines, EU banking authority · Guidelines on the use of remote customer onboarding solutions (EBA/GL/2022/15), para 46, 22 November 2022

Approved transfers with an unfinished Travel Rule exchange

Sumsub can approve a transfer while its Travel Rule exchange has not finished.A rule that your firm writes then decides what the withdrawal does next (Sumsub).

The transfer is approved, but the exchange has expired

Your rule says whether the transfer still goes, waits for review or is canceled. EU law bars the originator's provider from moving crypto-assets "before ensuring full compliance with this Article" (Article 14(8) of Regulation (EU) 2023/1113). Your counsel decides whether an expired exchange meets that requirement.

No VASP is found for the address

The status counterpartyVaspNotFound means no VASP could be attributed, and Sumsub treats the destination as an unhosted wallet. The EBA says the CASP "should obtain that information directly from its customer" before the transfer starts (EBA/GL/2024/11, paras 78 and 79). So the withdrawal screen asks the customer.

The VASP is found but cannot be reached

The status counterpartyVaspNotReachable means the two sides share no protocol. Sumsub emails the VASP and logs the attempt. Your policy says whether that email is enough to send the funds.

What a Sumsub integration from Protofire gives you

Customer status in your core that matches Sumsub

Your core shows the status that Sumsub holds, and the event behind each change is stored. Protofire builds the consumer for the applicant webhooks and keys it on externalUserId. A RETRY opens a resubmission path, and a FINAL starts the offboarding steps in your policy.

Withdrawals held until Sumsub's results meet your rule

A withdrawal reaches custody once Sumsub's review decision and Travel Rule status, read back from the API, meet your rule. Protofire builds the VASP picker and the ledger hold. We also build the call that returns the hash to Sumsub, and the cancel path.

Other VASPs get answers that confirm your customer

Answers go out within the counterparty's timeout. Each answer is logged with the person or the rule that confirmed it. Protofire builds address-to-customer matching, both confirmation calls and a manual queue.

Wallet screening on your own provider contracts

You choose the screening providers. For Chainalysis, Elliptic or TRM Labs, Sumsub says "you hold the contract and supply the API key" (Sumsub). So a later direct KYT integration, like the one on our Chainalysis integration page, needs no new vendor. Our compliance integration page covers tools across vendors.

A webhook receiver that recovers after your outage

Protofire builds digest checks, a queue that acknowledges fast, and a job that reads state back from the API after a gap. Before production keys exist, a Sandbox script runs each case where a transfer is approved but its Travel Rule exchange has not finished. The script is evidence that each webhook ends in the right ledger state.

How a withdrawal is held until Sumsub's webhook clears it

The service that Protofire builds holds a withdrawal in your ledger from submission until a webhook clears it.The hold closes when the hash is linked or the order is canceled (Sumsub).

  1. Step 1

    The customer names the receiving VASP

    As the customer types, the withdrawal screen searches Sumsub's Get available VASPs method. The customer's choice goes in as counterparty.institutionInfo.internalId, and attribution is skipped.
  2. Step 2

    The ledger holds the amount, and Sumsub receives the transfer

    The service posts the hold, then submits a travelRule transaction with direction out. The transaction's txnId is the withdrawal's own ID. Sumsub finds the counterparty and screens the wallet in the same pass.
  3. Step 3

    Sumsub's webhook sets the next step

    On applicantKytTxnApproved, the service reads the transaction back from the API and passes the withdrawal to custody under your rule. On applicantKytTxnAwaitingUser and applicantKytOnHold, the hold remains in place. On applicantKytTxnRejected, the service reverses the hold. These meanings follow Sumsub's default bundle, and custom rules can change them.
  4. Step 4

    Custody signs, and the service returns the hash

    Custody signs under the firm's own policies and approvers. The service then sends the hash to Sumsub as paymentTxnId, and the exchange moves to finished. Sumsub calls this "the step integrations most often omit".
  5. Step 5

    Stale holds go to the operations queue

    A withdrawal held past your confirmation timeout goes to the operations queue, which shows its age. So does a withdrawal with no Travel Rule status.

What happens when another VASP asks about your customer?

Another VASP's request reaches you at onHold, and it moves on when you confirm the address and identify your customer.Two flags show what is missing: needMasking for the address and needApplicantOwnershipConfirmation for the customer (Sumsub).

Sumsub warns that "confirming only the address is the most common integration mistake". After that mistake, the exchange remains at onHold until it expires, and the other VASP's transfer "may be delayed or fail" (Sumsub). Protofire's responder matches the address to a customer by the rule your compliance team sets, and then makes both confirmation calls.

The funds can arrive before the exchange finishes. So the ledger holds the deposit on a suspense line, off the customer's balance. Article 17(1) of Regulation (EU) 2023/1113 asks the beneficiary's provider for risk-based procedures on a transfer with missing data: execute, reject, return or suspend it.

Sumsub webhooks and Travel Rule protocols

Webhooks
Each webhook is signed with an HMAC digest. The endpoint must accept within 1 second. For most webhook types, retries run from 1 minute to 18 hours. A 401, 403 or 404 answer is not retried (Sumsub).
Travel Rule protocols
Sumsub reaches other VASPs over GTR, CODE, Sygna Bridge, the Sumsub protocol and TRP. Sumsub emails the VASPs that no protocol reaches. Its docs, updated 2 November 2026, count "Close to 3,000 VASPs" in its directory (Sumsub).

Checked November 2026 against Sumsub's documentation and its Terms and Conditions. Protofire integrates Sumsub for firms that have chosen it.

Sumsub at CASPs, payment firms and custody platforms

A CASP runs all the flows on this page, and it keeps the client-balance ledger, the deposit addresses and the signer in house. The weak spot is the incoming side. If an address is confirmed without the customer, another firm's transfer is stuck at onHold.

Our record: a KYC-gated DEX for Swarm Markets

In 2021 Protofire built the DEX core of Swarm Markets, a fork of Balancer's AMM, and the subgraph behind it.We also contributed to dOTC (case study). At launch, Swarm Markets was a BaFin-licensed DEX where only KYC-verified wallets could trade. Swarm held the license and ran the KYC. The Swarm work applies to a Sumsub integration because it was engineering for a venue whose rules depend on a check its operator runs.

Where applicant data is hosted and how DORA lists Protofire

By default, Sumsub hosts data with AWS in Germany (Sumsub).The services that Protofire builds are keyed on externalUserId, txnId, statuses and wallet addresses. Identity documents are kept in Sumsub. Two flows include personal data. The withdrawal form sends the beneficiary details that the customer enters, and the responder names your customer to Sumsub.

In an EU firm's DORA register of information, Protofire falls under two service types. ICT development (S02) covers the build. ICT operation management (S14) applies once Protofire also runs the services (Regulation 2024/2956, Annex III).

How work with Protofire starts

You send your Sumsub level names, your Travel Rule settings and your withdrawal flow.Protofire's first proposal then maps each Sumsub webhook to a ledger state. Each service calls Sumsub with an app token that your staff generate, store in your vault and can disable or delete (Sumsub). Where Protofire operates a service, the written scope lists each write call that the service makes. The terms that apply to each phase are on our how we work page.

Proposal
In writing, one business day after the discovery call: findings, a plan in phases and the first step we recommend.
Price
Fixed per phase when you commission it, against written acceptance criteria. Overruns inside them are ours to absorb, invoices follow delivered milestones, and you can stop at any phase boundary. Anything we operate after launch is priced in the proposal as its own recurring line, with the notice to end it.
Ownership
Code we write for you, contracts, the keys and credentials this work creates and the accounts your infrastructure runs in are yours by contract, within the license of any third-party software involved. Keys that a custody platform or a staking provider holds under its own key model stay with it under your contract; every other custody key stays with you or the custodian you appoint. Where the scope places something on servers we rent, it says what moves to you and when. An NDA is available from your first message, and we sign a data processing agreement (DPA) together with it.
After launch
Delivery closes with a hypercare window and a defect warranty, with their terms written into the proposal. A service we operate continues under its written scope until that scope ends.
Access
Read-only by default. A role that can start requests only if your written scope names one; never a signer, approver, administrator, key holder or recovery role on your contracts, wallets or custody platform. Services we build call each platform on credentials your staff issue and keep in your vault. Anything that approves or moves funds runs in your environment, and a scope under which we operate a service lists every write call it makes. Where the scope has us operate nodes, validators, monitors, explorers or indexers, it names the role and any key we hold on those servers, and in your own cloud account you can remove it.
Licenses
Protofire is an engineering firm and holds no financial or crypto-asset license; licensed activity stays with you and your providers.

How we work shows a worked proposal.

When not to start a Sumsub project

Three situations call for a smaller Sumsub project, or for none.

  • You need onboarding only. Sumsub's own verification links and its no-code Workflow Automation cover onboarding. Sumsub's support team can also supply "a ready-made setup" (Sumsub).
  • Your platform already embeds Sumsub, as Monavate's onboarding does for its program managers. In that case the work is configuration.
  • Sumsub's Travel Rule SDK covers your withdrawal form. Then the VASP picker that Protofire builds is not needed (Sumsub).

Protofire builds the systems around Sumsub. We give no legal opinion and take no onboarding decision. We hold no financial or crypto-asset license. Your compliance team keeps the applicant reviews.

FAQ

What is a Sumsub integration?
A Sumsub integration connects Sumsub's applicant reviews, transaction decisions and Travel Rule exchanges to a firm's own systems. Protofire builds it. The integration mirrors each applicant status into the firm's core record and holds a withdrawal in the ledger until Sumsub's webhook clears it. It also returns the hash after custody signs and answers other VASPs' requests.
Who can build a Sumsub integration for a crypto firm or a payment firm?
Protofire, an engineering firm, builds the firm's own side of a Sumsub integration. Protofire builds the status sync and the withdrawal hold. It also builds the incoming responder and the analytics setup. In 2021 Protofire built the DEX core for Swarm Markets. At launch, Swarm Markets was a BaFin-licensed DEX where only KYC-verified wallets could trade.
Can we keep our Chainalysis, Elliptic or TRM Labs contract?
Yes. Chainalysis, Elliptic and TRM Labs all run behind Sumsub on your own contract and API key. Several providers can screen the same transfer at once (Sumsub). Crystal Intelligence and Merkle Science need no contract of your own.
What happens if a Sumsub webhook does not arrive?
Sumsub retries most webhook types after 1 minute, 5 minutes, 1 hour, 5 hours and 18 hours (Sumsub). An answer of 401, 403 or 404 marks the webhook as failed at once, and Sumsub does not retry it. A receiver that Protofire builds reads the transaction state from the API before it releases a hold.
Do we still need an integration if we run Fireblocks or Dfns?
Whether a firm on Fireblocks or Dfns still needs a Sumsub integration depends on where the hold is booked. The Fireblocks and Dfns connectors both handle the Travel Rule exchange, and on each one the firm encrypts the customer data itself (Fireblocks, Sumsub). When the custody platform books holds and credits itself, its setup can be enough. But neither connector documents a hold in the firm's client ledger or applicant status in the firm's core.

Get a proposal

Tell us what you are building. An engineer reads it, we have a short call, and the written proposal follows within one business day.

Luis MedeirosField CTO, reads every request · LinkedIn

A demo or repository link also works.