Best practices — Creation
Create child accounts cleanly the first time and avoid the most common early-stage mistakes.
Who this section is for
Engineers building the Create account step on the Accounts API. Skim before you wire the call, and come back when designing retries or idempotency.
Tips
Pick the account type based on who will hold the funds
type based on who will hold the fundsA merchant account is for an entity that accepts payments and earns revenue. A consumer account is for an individual transacting on your platform (storing value, receiving funds, paying bills). The type is permanent — you cannot change it after creation.
If the same human owns a business but you only ever transact for them as an individual, consumer is the right choice. If they ever need to receive payments under a business identity, use merchant.
Store the org_* ID before doing anything else
org_* ID before doing anything elseThe Create call returns the child's id. Persist it in your own system on the same transaction as the user record. Every downstream step — identity verification, Update, Activate, webhooks, linked transactions — uses this ID.
Send the minimum payload
The Create call only requires type, person.email_address, and person.mobile_number. Save fuller person and business details for the Update step, after identity verification fills in name, date of birth, and address from the captured ID.
Use idempotency on retries
If the Create call times out or returns a 5xx, retry only after checking whether the account was already created — list the parent's children or look for the email and mobile combination. Creating two children for the same user wastes an activation slot.
Validate email and mobile before creating
Both are used for OTP, notifications, and webhook reference. A valid email reduces hosted identity verification abandonment. A reachable mobile reduces support tickets later.
Frequently asked
Can I bulk-create accounts?
Not via a single API call. Loop through your records and call POST /v2/accounts per child. For very high volumes, contact [email protected] to discuss rate accommodations.
Can I delete a child account I created by mistake?
Not directly via the API. Email [email protected] with the org_* ID. If the account is still in pending status, support can remove it.
Can I create a child under another parent (sub-platform)?
Multi-level parents are supported by the model, but most platforms operate one flat layer. If you need a multi-level arrangement, talk to PayMongo first to make sure the capability set and risk treatment work for your case.
Related
Updated 16 days ago