Migrating from legacy Widget

Migration Guide: Widget v1 → Widget v2

What's Changed

Widget v2 is a simplified, single-page experience. The key differences:

1. Single entry URL — No more locale paths (/en/widgets/kyc). Everything lives at the root.
2. PostMessage by default — Events are always sent to the parent window. No need to opt-in.
3. New scenarios — More control over the user flow.
4. New UI controls — Hide buttons you don't need with continuebutton and closebutton.
5. Legacy user_uuid renamed — Now identification_id

---

URL Change

Before (v1)

https://widget.depasify.com/en/widgets/kyc?partner=YOUR_PARTNER_ID&user_uuid=abc123&postmessage=true

After (v2)

https://widget.depa.finance/?partner=YOUR_PARTNER_ID&identification_id=abc123

That's it. The widget handles KYC, payment selection, and transaction processing in a single flow.

---

PostMessage is Now Always Active

In v1, you had to pass postmessage=true to receive events. In v2, events are always sent to the parent window — no parameter needed.

Events you'll receive:

Payment completed:

JSON

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

Payment failed:

JSON

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

SEPA transfer submitted:

JSON

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

KYC completed (only when scenario=kyc_only):

JSON

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

Listen for these in your parent page:

JavaScript

window.addEventListener('message', (event) => {
  const { type, payload } = event.data
  // Handle event
})

---

Parameters

Parameter	Required	Default	Notes
partner	✅	—	Your partner identifier
identification_id	No	—	User's identification. If omitted, a new one is created. Required if user already passed KYC. Legacy user_uuid still accepted
amount	No	—	Pre-fills and locks the amount field
currency	No	EUR	Pre-fills and locks currency. Options: EUR, USD, GBP, ETH, USDT, USDC, POL
scenario	No	—	Controls the flow (see below)
name	No	—	User's first name
surname	No	—	User's last name
email	No	—	User's email
address	No	—	Billing address
postal_code	No	—	Billing postal code
city	No	—	Billing city
country_code	No	—	Billing country (ISO)
state	No	—	Billing state
trx_uuid	No	auto-generated	Your transaction reference
redirect_url	No	—	Redirect after success
redirect_failure_url	No	—	Redirect after failure
lang	No	en	en or es
mode	No	light	light or dark
continuebutton	No	true	Set to false to hide the "Finish" button on result screens
closebutton	No	true	Set to false to hide the close button on failure/3DS screens

---

Scenarios

Scenario	What it does	Required params
(none)	Full flow: KYC → Payment	—
kyc_only	KYC only, fires kycCompleted event on success	—
signin	Skips KYC, shows sign-in directly	—
reset-password	Password reset flow	—
direct_card_payment	Skips to card payment form	amount, name, surname, address, postal_code, city, country_code
direct_bank_payment	Skips to SEPA bank transfer form	amount
crypto_payment	Skips to crypto payment form	amount, currency

Removed scenarios from v1:

• direct_payment → use direct_card_payment
• direct_funding → use default flow with amount param
• fund_without_amount_select → use direct_bank_payment or direct_card_payment

---

Renamed Parameters

v1	v2	Notes
user_uuid	identification_id
postmessage=true	(removed)	Always active now

---

New: UI Controls

You can now control what buttons appear on completion/failure screens:

?continuebutton=false   → Hides "Finish" button (useful if you rely only on postMessage)
?closebutton=false      → Hides close (X) button on failure and 3DS screens

This is useful when you want full control over the user experience from your parent page using postMessage events.

---

Iframe Setup

HTML

<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>

---

Removed Features

• Locale-based URLs (/en/widgets/...) — replaced by ?lang= parameter
• postmessage parameter — always on
• direct_payment / direct_funding / fund_without_amount_select scenarios — replaced by clearer names

---

Migration Checklist

• Update your iframe src from /en/widgets/kyc?... to /?...
• Remove postmessage=true from your URL (it's always on now)
• Rename user_uuid to identification_id (optional — both work)
• Update scenario names if you used direct_payment or direct_funding
• Add a message event listener if you haven't already — you'll now always receive events
• Consider using continuebutton=false if you handle flow entirely via postMessage
• Test with the sandbox test cards:
  • Success: 4000000000002503 (Visa) / 5200000000002151 (MC)
  • Failure: 4000000000002420 (Visa) / 5200000000002664 (MC)

---

Support

Questions? Contact us at [email protected]