Mercuryo Integration — Overview

Document type: Product overview · for Product, Compliance, and client review
Status: Draft · pending sandbox alignment
Last updated: May 26, 2026
Companion documents: Technical Design · Test Plan

Payment Service Integration · Mercuryo

Fiat in, fiat out — without leaving the platform.

Mercuryo provides an embedded buy-and-sell experience for crypto. Customers will be able to purchase crypto with a card or bank transfer, and to sell crypto back to fiat through the same flow. Identity verification done on the platform is reused inside Mercuryo's widget, so the customer does not re-upload documents.

User flows · Buy + Sell

Payment methods · Card · IBAN · Bank

KYC step · Shared with Mercuryo

~1.5–2 mo

Delivery once approved by client

Delivery timeline

Five phases from discovery to production. Calendar duration depends on the pace of vendor and client alignment in early phases.

1 · Discovery

Vendor docs review · scope locked

~4 h

2 · Alignment

Pending sandbox creds

~4 h

Here

3 · Build

Backend + frontend

~90 h

4 · QA

Scenarios + readiness

By lead

5 · Rollout

Staged enablement

~4 h

Discovery — vendor docs review and scope lock

Done · ~4 h

What was done

Vendor documentation reviewed end-to-end · API surface, widget integration, identity-sharing model
Scope locked with stakeholders · on-ramp + off-ramp, both shipped in v1
Architectural decisions captured · omnibus deposit attribution, shared payment route across tenants, identity-share forwarded on every transaction

Outputs produced

Technical specification ready for engineering review
Decisions log capturing every binding choice
Baseline effort estimate per workstream

Alignment — vendor and client sign-off

In flight · ~4 h

In flight

Sandbox credentials requested from vendor
Identity-sharing client identifier requested from vendor's integration manager
Target-market country coverage list confirmed with vendor

What unblocks the build phase

Sandbox base URL + partner token + widget secret + webhook sign key all received
Identity-share configuration confirmed
Country list signed off — defines which markets see the integration on launch

Build — backend and frontend implementation

~90 h · BE 60 + FE 30

Backend · ~60 h

Integration wired into the existing payments pipeline
Vendor API client and per-user authentication cache
Three signature schemes implemented · widget signing, webhook verification, deposit-address verification
Webhook ingestion with idempotency on the vendor's event identifier
Off-ramp branch hooked into the existing withdrawal pipeline — no fork in compliance logic

Frontend · ~30 h

Embedded widget mount in the trader UI
Widget integration in the brokerage-side embeddable widget
Re-quote handling for expired quote tokens
Error and edge-case messaging · slippage, network failure, mid-flow abort

QA — scenarios, readiness, and verification

Sized by team lead

Quality surface · what must be verified

Happy paths · buy with card, buy with IBAN, sell with card, sell with IBAN
Slippage handling · ≥1% on buy (rejected with re-quote), >5% on sell (vendor returns crypto)
Identity continuity · verified customers see no second verification inside the widget
Webhook integrity · signature verification, duplicate-event idempotency, forged-signature rejection
Authentication lifecycle · per-user token refresh and expiry handling
Compliance integration · country gating, withdrawal-freeze, limits, anti-money-laundering, Travel Rule (existing pipelines, must remain in front)
Vendor-side risks · sandbox crypto address realism, retry behaviour, threshold drift

Environments and references

Test environments · vendor sandbox, our UAT, production canary
Sandbox readiness checklist · eight pre-flight items, six from vendor, two internal
Coverage matrix · twelve scenarios across three payment methods
Error catalogue · eleven vendor error codes mapped to customer-facing messages
Out-of-scope items documented · vendor-internal flows are not in our QA surface

Full scenario catalogue, readiness checklist, vendor-side risk register, and the decision tree live in the Test Plan. Effort is sized by the QA team lead once the scope above is reviewed.

Rollout — staged enablement and monitoring

~4 h

Enablement

Production with a canary tenant first
General availability per tenant via one route-configuration change
No code deploy required to enable a new tenant

Monitoring and safety

Webhook delivery rate · alert on missing terminal events
Transaction completion rate by payment method
Error rate by vendor error code
Rollback · disabling the integration is one route-configuration change

Engineering effort

~90 h

Backend 60 + Frontend 30

QA effort is sized separately by the team lead after reviewing the Test Plan. Calendar duration is 1.5 – 2 months once approved by the client, covering vendor coordination, review cycles, and a staged rollout.

What the integration brings to the platform

Five capabilities the customer gains directly. Each is delivered as part of the same integration in a single release.

Buy with a card

Customers complete a card purchase of crypto in the embedded widget. 3-D Secure runs inside the widget; card data never touches the platform.

On-ramp · cards

Buy via bank transfer

For larger transactions, customers can fund a purchase via IBAN — either as an invoice or as a direct exchange — without leaving the experience.

On-ramp · IBAN

Sell back to fiat

Customers sell crypto and receive fiat to a card or bank account through the same widget. The off-ramp flow runs over the standard platform compliance checks.

Off-ramp

Identity is reused

Customers who completed verification on the platform skip a second identity flow inside Mercuryo. The verification record is forwarded automatically.

No re-KYC

Multi-currency

Multiple fiat and crypto pairs are supported in a single integration. The customer picks the pair, the widget surfaces the live rate and finalises the price at confirmation.

Multi-pair

Platform controls still apply

Off-ramp transactions clear the same platform-level checks (transaction limits, anti-money-laundering, Travel Rule) before any vendor call is made. No duplicated control surface.

Compliance · unchanged

What the customer does — step by step

Two flows, both inside one widget. The technical detail behind each step lives in the Technical Design document.

Buying crypto

On-ramp

Fiat in · crypto credited to the platform balance.

Customer opens the deposit screen

From the wallet, the customer chooses Mercuryo as the payment route, picks the fiat currency and the amount.

Mercuryo widget loads in place

The widget appears embedded in the platform. The customer's verified identity is already passed along, so no documents are re-requested.

Customer pays

For cards, 3-D Secure runs inside the widget. For bank transfers, the customer follows the displayed instructions or confirms an IBAN payment.

Confirmation

The widget surfaces the result. The customer can close it and return to the platform balance.

Crypto credited

Once Mercuryo confirms settlement, the corresponding crypto balance appears in the platform wallet automatically.

Selling crypto

Off-ramp

Crypto out · fiat delivered to the customer's chosen destination.

Customer opens the withdrawal screen

From the wallet, the customer picks Mercuryo as the payout route and selects the crypto-to-fiat pair plus the amount.

Customer picks a destination

Card or IBAN. The widget shows live rates and locks the quote at confirmation.

Platform compliance runs

Standard transaction limits, anti-money-laundering, and Travel Rule checks clear before any vendor call is made.

Crypto sent · fiat dispatched

The platform sends crypto to Mercuryo's settlement address. Mercuryo dispatches the fiat to the chosen destination within a defined settlement window.

Confirmation

Once settlement completes, the customer sees the transaction marked done. If market conditions cause the sale to be cancelled, the crypto is returned automatically.

Open items before delivery

None of these block design sign-off; they are items to confirm in the next phase, on the sandbox.

To confirm in Phase 2 — sandbox alignment

Six items pending confirmation

Country coverage. Final supported-country list for the target market is confirmed during the first sandbox round-trip with Mercuryo.
Identity-sharing configuration. The cross-vendor identity-sharing setup requires one shared identifier supplied by Mercuryo's integration manager.
Sandbox crypto realism. Whether Mercuryo's sandbox returns test-network addresses or real-network addresses for the off-ramp settlement step. Affects the QA test plan.
Webhook retry behaviour. Vendor documentation indicates retries on delivery failure; exact schedule confirmed on the first probe.
Error code coverage. Beyond the documented price-slippage error, other error codes appear only under live conditions and will be catalogued during the first build cycle.
Business / corporate flow. Mercuryo's documentation does not state whether business customers (KYB) are supported in this product line. Confirmed with vendor before adding KYB to scope.

In one paragraph

Mercuryo adds a single embedded experience for buying and selling crypto directly inside the platform. Card and bank-transfer methods are supported in the same widget. The customer's existing identity verification is reused — no second KYC. Platform compliance controls remain in front of every off-ramp transaction. After sandbox alignment, the build itself runs about a week, followed by QA cycles and a staged rollout.