Activation fee and instant activation
The final step of onboarding is the activation fee. The merchant pays it straight from their own bank, without copying account numbers or transfer titles. The fee does two jobs at once: it covers the cost of verification and it confirms the account the merchant will receive payouts to.
On top of that there is an optional step - the merchant signs in to the same account and dpay confirms that the account really belongs to them. This step cuts activation from one to two business days down to a few minutes.
The fee covers the cost of verification, which we incur regardless of the outcome. You must tell the merchant this before the payment starts - in our hosted flow it is a separate, deliberate consent, not fine print. If you build your own interface, that message is your responsibility.
The whole flow
Step 1: show the list of banks
We return only the banks available at that moment - switched off and temporarily unavailable ones are already filtered out. The result changes rarely, so cache it on your side.
GET/api/partner/v1/onboarding/{ref}/activation/banksBanks the activation fee can be paid through.Full contract in the API Reference
Step 2: show both banking categories
Banks differ in where they serve businesses. Some keep company accounts in ordinary online banking, others run a separate corporate system. This cannot be inferred from the merchant's legal form - so show both categories and let them choose:
account_variant | Label for the merchant | When |
|---|---|---|
retail | Personal banking | Ordinary sign-in; in many banks company accounts too |
company | Business banking | A separate system for companies |
GET /activation returns suggested_variant - use it as the default selection, not as the decision. The wrong variant means the merchant cannot see their account and cannot pay.
Step 3: start the payment
You do not pass the amount - dpay sets it based on the entity type.
POST/api/partner/v1/onboarding/{ref}/activationStart the activation fee payment and get the bank address.Full contract in the API Reference
The merchant must pay from the bank account declared for payouts. A payment from a different account will not activate the account. Some banks let us restrict the choice to the right account upfront (supports_sender_account in the bank list); in the others we check it afterwards, so it is worth stating the requirement in your interface.
Calling again while a payment is in flight returns the existing attempt rather than creating a second one. Once the fee has been settled, further calls return 409 - the fee is non-refundable and is never charged twice. After a refused or cancelled payment the merchant may start again.
Step 4: offer instant activation
Once the fee is settled, the merchant has a choice. Present it plainly, because both routes are valid:
- Activate now - the merchant signs in to the same account, activation within minutes
- I will wait - no sign-in, activation once the transfer is credited, 1-2 business days
/api/partner/v1/onboarding/{ref}/activation/verify-ownerConfirm the account owner - instant activation.Full contract in the API Reference
This step costs nothing - the fee is already settled. If confirmation fails, the merchant corrects the payout account and repeats only this step.
Step 5: poll the status
GET/api/partner/v1/onboarding/{ref}/activationState of the fee, the owner confirmation and the account activation.Full contract in the API Reference
Bank confirmation arrives with very different delays - from seconds to hours. Treat any non-terminal state as "still waiting", not as a failure.
How to read the response
| Field | Note |
|---|---|
status | Payment state. null means no payment has been started yet |
sender_account_match | null is not the same as false. null means "not determined" - the bank did not report the sender account. false means a real mismatch |
owner_result | manual means a person is reviewing it. Do not present this to the merchant as a refusal |
activated | The only field that tells you the account is ready to take payments |
Fallback route
The merchant can always pay the activation fee by ordinary bank transfer - with details to copy and activation once the money is credited. Keep this route visible, because sometimes it is the only one available:
- the merchant's bank is not on the list
- the service is temporarily unavailable (
503onGET /activation/banksorPOST /activation) - the merchant does not want to sign in to their bank inside somebody else's interface
The amount is the same either way; only the payment method and the activation time differ.
What cannot move into your UI
Authorising the payment and signing in to the bank always happen on the merchant's bank side - you receive an address to send them to. Do not act as an intermediary for sign-in credentials and do not embed the bank page in a frame: banks block embedding and the attempt ends in a blank screen. If you run onboarding in an iframe, open the bank address in a new tab and poll the status on your side.