Account lifecycle
Every merchant account in dpay Connect moves through a sequence of statuses. You see the same status in the status response and receive it through webhooks. The webhook event has the same name as the status. The table below explains each status and how you should respond.
Transition diagram
Statuses
| Status | Meaning | What you should do |
|---|---|---|
started | The draft has been created, but data is incomplete. | Collect and submit data (iframe / redirect / API). |
in_progress | Onboarding is in progress; the merchant is completing data or personal actions. | Wait and optionally remind the merchant. |
agreement_signed | The merchant has signed the agreement. You now have delegation for account access and payments. | Nothing; dpay continues the process. |
pending_transfer | The account is awaiting the activation fee from the merchant's bank account. | Guide the merchant through the payment - see Activation fee. |
under_review | dpay is performing a manual KYC/AML review. | Wait. Do not register payments or request payouts yet. |
completed | The account is active. The merchant can accept payments. | Full on-behalf access (payments and, after the merchant opts in, payouts). |
blocked | The account is blocked because verification failed or dpay made a blocking decision. | Ask the merchant to contact dpay. |
Key stages
Agreement signing (agreement_signed)
Signing the channel agreement with an SMS code grants you delegation for account access and payments. Technically, on-behalf calls in these scopes are allowed from this point. In practice, wait until the account is fully active (completed) before registering payments, because the merchant has not yet completed the entire verification process.
Activation fee (pending_transfer)
Before full activation, the merchant pays an activation fee from their bank account. The fee covers the cost of verification and at the same time confirms that the payout account belongs to the merchant.
The merchant can pay straight from their bank (and optionally activate the account within minutes) or by ordinary transfer, with activation once the money is credited. Details and endpoints: Activation fee and instant activation.
Activation (completed)
The completed status means the account is active and you can use the full on-behalf functionality: register payments and request payouts, with payouts requiring the merchant's separate opt-in.
Blocking (blocked)
An account can be blocked if verification fails or because of a later compliance decision. dpay controls the block. Your merchant should contact dpay for clarification.
An active account may later undergo verification again as part of periodic CDD required by AML regulations. The merchant may be asked to update data, and on-behalf payouts may temporarily return 409. dpay does not send a webhook when reverification begins. You receive a reverification_submitted event when the merchant submits the required data. This is a normal part of the account lifecycle, not an integration error.
Responding to status changes
Do not poll the status in a loop. Configure webhooks and react to push events:
The webhook is the source of truth for a change. Treat GET /onboarding/{ref} as a supplementary check, for example when the merchant starts a session in your product.