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 — either per-child by email today, or by setting Auto-configuration defaults so future activations include them automatically.

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_message raw — 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].

What does the API key in the activation webhook give me?

merchant.activated payloads include the child's API keys for fully-owned arrangements. Persist them securely on your side. You typically do not need them for normal linked transactions (you use the Account-Id header with the parent's key) — they exist for cases where the child needs its own API access.

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, or set Wallets in your Auto-configuration defaults so they appear automatically on future activations.

Best practices — Activation