Payment Links Integration
Step-by-step guide to generating payment links, prefilling parameters, and handling completion webhooks.
Payment links take two server-side calls: configure checkout once, then create a link for each
order and send your customer to its url.
1. Configuring Checkout
Set your defaults once: language, colour mode, how long links stay valid and where customers go
after paying. Send account_id to override them for a single account.
curl -X POST https://sandbox.depasify.com/api/v1/widget_configs \
-H "Authorization: Bearer <your_jwt_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Default checkout",
"mode": "light",
"default_lang": "en",
"expiry_minutes": 60,
"default_success_redirect_url": "https://yourplatform.com/billing/success",
"default_failure_redirect_url": "https://yourplatform.com/billing/failure",
"enabled": true
}'2. Creating a Payment Link
Request
curl -X POST https://sandbox.depasify.com/api/v1/accounts/8f3a2c1e-5b7d-4e9a-9c21-7d4b6e0f1a23/widget_sessions \
-H "Authorization: Bearer <your_jwt_token>" \
-H "Content-Type: application/json" \
-d '{
"amount": "250.00",
"currency": "EUR",
"method": "card",
"trx_uuid": "ord_882910",
"description": "Subscription deposit – Enterprise tier",
"full_name": "Sarah Connor",
"country_code": "ES",
"redirect_url": "https://yourplatform.com/orders/ord_882910/paid",
"redirect_failure_url": "https://yourplatform.com/orders/ord_882910/failed"
}'Response
{
"uuid": "01a062c8-3c80-71fe-bdc8-f079ebae3fb2",
"status": "open",
"amount": "250.00",
"currency": "EUR",
"method": "card",
"trx_uuid": "ord_882910",
"embeddable": true,
"expires_at": "2026-09-04T12:30:00Z",
"url": "https://widget2.depasify.com/pl/vvvW3UvbGgernIQB"
}3. Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
amount | String | Yes | Amount as a decimal string, for example "250.00". |
currency | String | Yes | ISO 4217 code. It must be enabled on your vault's card gateway. |
method | String | Yes | card or crypto. |
trx_uuid | String | Yes | Your reference for the payment, such as an order ID. Unique per account. |
embeddable | Boolean | No | true (default) returns a page built for an iframe or modal; false a standalone checkout page. |
description | String | No | Order description shown at checkout. |
full_name, address_line_1, postal_code, city, state, country_code | String | No | Billing details to prefill the checkout. |
customer_ip_address | String | No | Locks the link to one IP address. Other IPs get 403 IP not allowed. |
redirect_url, redirect_failure_url | String | No | Override your default success and failure URLs for this link. |
The link's lifetime comes from your checkout configuration (expiry_minutes, 60 by default).
4. TypeScript Integration Example
interface CreatePaymentLinkParams {
accountId: string;
amount: string;
currency: string;
orderId: string;
}
export async function createPaymentLink({
accountId,
amount,
currency,
orderId,
}: CreatePaymentLinkParams): Promise<string> {
const response = await fetch(
`https://sandbox.depasify.com/api/v1/accounts/${accountId}/widget_sessions`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.DEPA_API_TOKEN}`,
},
body: JSON.stringify({
amount,
currency,
method: "card",
trx_uuid: orderId,
description: `Order #${orderId}`,
redirect_url: `https://myapp.com/orders/${orderId}?status=success`,
redirect_failure_url: `https://myapp.com/orders/${orderId}?status=failed`,
}),
},
);
if (!response.ok) {
throw new Error(`Failed to create payment link: ${JSON.stringify(await response.json())}`);
}
const link = await response.json();
return link.url;
}Because trx_uuid is unique per account, retrying with the same order ID can't create a second
link.
5. Handling the Result
Each link accepts one payment attempt. When it ends:
- the customer is redirected to your success or failure URL, and
- Depa sends a
widget_session_completedorwidget_session_failedwebhook.
Treat the webhook, or a call to GET /accounts/{account_id}/widget_sessions/{uuid}, as the
source of truth before fulfilling the order: redirects can be interrupted. You can revoke an
unpaid link at any time with POST …/widget_sessions/{uuid}/revoke.