Best practices — Activation
Activate child accounts reliably and know exactly what to do when an activation is declined.
Who this section is for
Engineers wiring up the Activate step, plus product and operations leads who need to design the user-facing message and recovery flow when an account is declined.
Tips
Treat Activate as a commit, not a save
Activate is destructive for editability — once it succeeds (or even once risk review begins), the account becomes read-only through the API. Run a final review on your side before the call:
- identity verification is
passed. - All required person fields are present.
- All required business fields are present (for merchants).
- TIN is set for person and (for merchants) business.
Expect retry loops on missing fields
Activate account returns errors with JSON pointers when fields are missing. Call Update account to fill them, then call Activate again. There is no penalty for repeated Activate calls — they only succeed when the account is complete.
Listen for the webhook, not the response
The synchronous response from Activate confirms the request was accepted. The actual activation result is delivered as a merchant.activated / merchant.declined (or consumer.activated / consumer.declined) webhook event after risk review completes. Build the rest of your platform around the webhook, not the synchronous response.
Know what activation provisions
By default, activation provisions QR Ph and nothing else. If the child needs wallets, additional payment methods, or other products, request them via Account capabilities Auto-configuration does not add capabilities.
Plan for declines
A declined activation is final for the account. Have a path in your product for what to do next:
- Show the user a clear message (do not expose
declined_messageraw — translate it for your audience). - If you believe the decline was made in error, email [email protected] with the
org_*ID and context. Support can review. - For the user, the path forward is typically a new account with corrected information.
Frequently asked
How long does activation take?
Most activations complete within minutes once the request reaches PayMongo. Some require manual risk review and can take up to 14 business days. Plan your UI for the asynchronous case — show a "pending review" state and notify the user when activation completes.
Can I cancel an activation request in flight?
No. Once submitted, the request goes through risk review. If you submitted an Activate call in error and the account has not yet been declined or finalized, contact [email protected].
Does the activation webhook include the child's API keys?
Only if you are the managing parent of a fully managed account. For any other account created with the Accounts API, child API keys are not shared. Act on the child with the Account-ID header and the parent's key — see Linked transactions. The legacy Onboarding API still sends child keys until January 1, 2027; see Onboarding webhooks.
Why didn't I get a wallet on activation?
Wallets are not provisioned by default. Request a wallet capability for the child via Account capabilities.
Related
Updated about 1 month ago
