Skip to main content

Redirect onboarding (hosted)

In this mode, you redirect the merchant to the full-page, dpay-hosted onboarding flow and receive progress and completion updates through webhooks. This is the simplest option when you do not want to embed an iframe or when merchants' browsers block third-party cookies.

Flow​

Step 1: create onboarding and retrieve the hosted flow URL​

Create a draft from your server by calling the API with the merchant's contact details and consents:

POST/api/partner/v1/onboardingCreate an onboarding draft (merchant contact details and consents).Full contract in the API Reference

The hosted flow URL is returned by POST /onboarding/{ref}/finalize (or GET /onboarding/{ref}) in the next_action.url field. See API onboarding for field details.

POST/api/partner/v1/onboarding/{ref}/finalizeRetrieve the hosted flow URL (next_action.url).Full contract in the API Reference GET/api/partner/v1/onboarding/{ref}Read the status (as a complement to webhooks).Full contract in the API Reference

Step 2: redirect the merchant​

Redirect the merchant's browser to next_action.url:

HTTP/1.1 302 Found
Location: https://panel.dpay.pl/onboarding-v3/continue/...

The merchant completes the entire onboarding flow on the hosted dpay page, including the consistent branded UI, all KYC/AML steps, and agreement signing. The flow also ends there: dpay does not redirect the merchant back to your URL.

Step 3: track progress with webhooks​

Webhooks are the source of truth for progress. You receive an event after every status change (agreement_signed, pending_transfer, completed, ...). You can also query GET /onboarding/{ref} as a supplementary check.

There is no return_url parameter

The API does not accept a return URL. The merchant completes the process in the dpay-hosted flow. If you need to bring the merchant back into your product after completion, embed the flow in an iframe and react to SDK events such as completed, or instruct the merchant to return to your application.

next_action.url - lifetime and resuming​

The link is resumable. If the merchant leaves onboarding, you can redirect the merchant to the same URL to continue where they stopped, because dpay retains the progress.

  • Link lifetime: 45 days. The link also stops working after the account is activated.
  • An expired link returns 410 Gone. Repeating POST /onboarding with the same ref returns the existing draft without replacing the token. You cannot renew an expired link yourself; contact dpay.
Resuming with the SDK

If you also use the SDK, you can embed the hosted flow with DpayOnboarding.mountResume(target, { token }). The token is the last segment of the next_action.url path. See API onboarding for details.

When to choose a redirect​

  • You do not want to embed an iframe or depend on third-party cookies.
  • You prefer the simplest possible integration: create a draft and redirect.
  • The merchant can complete onboarding as a separate, one-time step.

If you want the merchant to stay on your page, use an iframe. If you want to build your own onboarding UI, see the API.