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
Register as a Depa partner:
- Contact hello@depa.finance
- Configure your Partner ID, theme, logo, and trading parameters

Widget Implementation

Add the following iframe to your platform:

<iframe
  src="https://widget.depa.finance/?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>

URL Parameters

Parameter	Required	Description
`partner`	Yes	Your unique partner identifier (provided during registration)
`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 payment scenarios)
`currency`	No	Transaction currency. If provided, the selector is disabled. Available: `EUR`, `USD`, `GBP`, `ETH`, `USDT`, `USDC`, `POL`. Default: `EUR`
`scenario`	No	Workflow configuration — see Scenarios
`name`	No*	User's first name (*required for `direct_card_payment`)
`surname`	No*	User's last name (*required for `direct_card_payment`)
`email`	No	Pre-fills the user's email
`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`)
`state`	No	Billing state
`trx_uuid`	No	Custom transaction identifier for business tracking. 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

Available Scenarios

Scenario	Description	Required Parameters
(default)	Full flow: KYC + payment method selection	—
`kyc_only`	KYC verification only — no payment step. Fires `kycCompleted` postMessage on completion	—
`signin`	Skips KYC verification and goes directly to the sign-in form	—
`reset-password`	Opens the password reset form (for users arriving from a reset email link)	—
`direct_card_payment`	Starts at the payment form with Card pre-selected	`amount`, `name`, `surname`, `address`, `postal_code`, `city`, `country_code`
`direct_bank_payment`	Starts at the payment form with SEPA Bank Transfer pre-selected	`amount`
`crypto_payment`	Starts at the payment form with Crypto pre-selected	`amount`, `currency`

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
Deploy to production

Post Message Structure

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

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 submitted (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"
  }
}

Testing

Test card numbers and sandbox credentials are environment-specific and provided by the Depa team during onboarding. Contact hello@depa.finance 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 hello@depa.finance