Who this section is for

Engineers and product leads building the form your platform uses to collect remaining child-account details. Skim before designing the UI and validation rules.

Tips

Call Update in chunks, not one giant PATCH

Update accepts partial payloads. Send what the user just answered, save progress, then move on. This avoids losing a 30-field form if one field fails validation.

A reasonable rhythm: one PATCH per logical step in your UI — person details, then business details, then address, then bank.

Validate enums on your side before posting

Most validation errors at Update time are mismatched enum values: an industry code that does not exist, a state code that is not ISO 3166-2 (PH-MNL not Manila), a nature_of_work that is not in the accepted list. Hold the canonical lists from the Appendix in your form and validate locally before calling PayMongo.

Pre-fill from the identity verification result

After identity verification passes, name, date of birth, and parts of the address may be set already. Read the account with Get account before showing the Update form so the user does not retype what was already captured.

Treat TIN as required, not optional

person.tin (and business.tin for merchants) is required at activation, but Update accepts the account without it. Many platforms forget this and only discover the gap when Activate returns a parameter_required error. Collect TIN as part of the Update flow.

Keep the bank account optional until you need disbursements

bank fields are only required when the child is provisioned with wallet disbursements at activation. For accounts that only accept QR Ph, you can skip the bank section entirely. If the child needs payouts later, request the Account capability and add the bank then.

Frequently asked

Can I update fields after activation?

No. Once activation_status is activated, the account becomes immutable through the API. Confirm everything is correct before calling Activate.

The user wants to change their address after activation. What do I do?

The user can update their own address through the PayMongo Dashboard for an activated child account. The Accounts API does not currently support post-activation edits by the parent.

Do I need to send the full nested object every time?

No. Partial PATCH is supported. To update only person.tin, send { "person": { "tin": "..." } }. The rest of the person object is untouched.

Can I send null to clear a field?

For most optional fields, yes. For fields that have a stricter "required at activation" rule, sending null may pass validation at Update time but fail at Activate. Treat clearing a required field as a deliberate action, not an oversight.

Best practices — Updating