Widget Integration

Depa Widget Integration Guide

Overview

The Depa widget provides a seamless, customizable interface for integrating KYC (Know Your Customer) processes and fiat-to-crypto gateway functionality into your platform. This solution enables your clients to verify their identity and conduct secure cryptocurrency transactions via card, SEPA bank transfer, or crypto wallet.

User Journey

Identity Verification — Submit personal information (name, ID proof, selfie) and complete AML checks
Payment Method Selection — Choose between card, SEPA bank transfer, or crypto wallet
Transaction Completion — Process payment and optionally redirect to your system via redirect_url

Integration Process

Prerequisites

Create a client account on Depa — See our Getting Started Guide
Once registered Depa provides your Partner ID and relevant configuration details

Widget Implementation

Add the following iframe to your platform:

<iframe
  src="https://widget.depa.finance/emb?partner=YOUR_PARTNER_ID"
  allow="camera; microphone; geolocation; payment"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
  style="width: 560px; height: 650px; border: none;"
></iframe>

Available Scenarios Parameters

The scenario parameter allows you to define the specific entry point and workflow a user encounters when the widget loads. By customizing this value in the widget URL, you can edit the user journey, whether that means bypassing KYC verification for returning users or launching directly into a specific payment method. The table below outlines the available scenarios , the additional parameters required for each, and the resulting behavior of the widget flow.

Scenario	Required Parameters	Description
(default)	—	Full flow: Includes both KYC verification and payment method selection.
`kyc_only`	—	KYC verification only: Skips the payment step. Triggers a kycCompleted postMessage upon success.
`signin`	—	Direct Sign-in: Opens the login form immediately and skips the KYC process.
`reset-password`	—	Password Reset: Opens the reset form (intended for use via email recovery links).
`direct_card_payment`	`amount`, `name`, `surname`, `address`, `postal_code`, `city`, `country_code`	Pre-selected Card: Starts at the payment step with Card already selected.
`direct_bank_payment`	`amount`	Pre-selected Bank Transfer: Starts at the payment step with SEPA Bank Transfer already selected.
`crypto_payment`	`amount`, `currency`	Pre-selected Crypto: Starts at the payment step with Crypto already selected.

URL Parameters

Customizing the widget experience is handled through URL parameters. These parameters allow you to pre-fill user information, lock specific transaction values, and control the visual theme or language of the interface. While most fields are optional to allow for maximum flexibility.

Parameter	Required	Description
`partner`	Yes	Your unique partner identifier (provided during registration)
`currency`	No	Transaction currency. If provided, the selector is disabled. Available: `EUR`, `USD`, `GBP`, `ETH`, `USDT`, `USDC`, `POL`. Default: `EUR`
`scenario`	No	Sets the workflow configuration — see Scenarios
`email`	No	Pre-fills the user's email
`state`	No	Billing state
`trx_uuid`	No	Custom transaction identifier. Auto-generated if omitted
`redirect_url`	No	URL to redirect to after a successful transaction or KYC completion
`redirect_failure_url`	No	URL to redirect to after a failed transaction
`mode`	No	Color mode: `light` or `dark`. Default: `light`
`lang`	No	Language: `en` (English) or `es` (Spanish). Default: Browser language or `en`
`continuebutton`	No	Set to `false` to hide the "Finish" button on completion screens
`closebutton`	No	Set to `false` to hide the close button on the failure dialog and 3-D Secure iframe
`identification_id`	No*	UUIDv4 for user identification and session management. If omitted, the backend creates a new identification automatically. (*Required if the user has already completed KYC — omitting it will start a new identification flow from scratch.) Legacy alias `user_uuid` is also accepted
`amount`	No*	Transaction amount. If provided, the field becomes read-only (*required for `direct_card_payment` and `direct_bank_payment` scenarios)
`name`	No*	User's first name (*required for `direct_card_payment`)
`surname`	No*	User's last name (*required for `direct_card_payment`)
`address`	No*	Billing address (*required for `direct_card_payment`)
`postal_code`	No*	Billing postal code (*required for `direct_card_payment`)
`city`	No*	Billing city (*required for `direct_card_payment`)
`country_code`	No*	Billing country ISO code (*required for `direct_card_payment`)

Post Message Structure

All messages are sent from the widget to window.parent via postMessage.

The widget broadcasts real-time updates towindow.parent using the browser's postMessage. Each event follows a consistent JSON format, providing a type to identify the specific action and a detailed payload containing relevant transaction data.

Payment succeeded:

{
  "type": "isCompleted",
  "payload": {
    "transactionId": "6b5790de-e603-48ac-a4b9-3249017e688f",
    "status": "isCompleted",
    "amount": "100",
    "currency": "EUR"
  }
}

Payment failed:

{
  "type": "isFailed",
  "payload": {
    "transactionId": "6b5790de-e603-48ac-a4b9-3249017e688f",
    "status": "isFailed",
    "amount": "100",
    "currency": "EUR",
    "refusalCode": "24",
    "refusalReason": "Declined"
  }
}

SEPA transfer is awaiting processing:

{
  "type": "isAwaiting",
  "payload": {
    "transactionId": "6b5790de-e603-48ac-a4b9-3249017e688f",
    "status": "isAwaiting"
  }
}

KYC-only flow completed (only fired whenscenario=kyc_only):

{
  "type": "kycCompleted",
  "payload": {
    "status": "completed"
  }
}

Final Configuration

Provide your redirect_url to Depa for post-transaction redirects, or pass it as a URL parameter
Optionally provide a redirect_failure_url for failed transactions
Test the integration in your development environment

Testing

Test card numbers and sandbox credentials are environment-specific and provided by the Depa team during onboarding. Contact [email protected] to receive test credentials for your integration environment.

Testing Card

Test Card Scenario	Card Number
Successful	Visa: `4000000000002503`
	Mastercard: `5200000000002151`
Failed	Visa: `4000000000002420`
	Mastercard: `5200000000002664`

Support

For technical support or custom implementations, contact our team at [email protected]