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 a verification transfer from the merchant's bank account. | Tell the merchant to make the verification transfer. |
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.
Verification transfer (pending_transfer)
Before full activation, the merchant usually makes a small verification transfer from their bank account. This confirms that the payout account actually belongs to the merchant. At this stage, show the merchant a clear message and instructions.
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.