Who this section is for

Anyone hitting an unexpected response from Onboarding-as-a-Service. Errors are organized by the step that produced them.

Error response shape

PayMongo error responses share the same envelope.

{
  "errors": [
    {
      "code": "parameter_invalid",
      "detail": "Human-readable message explaining what is wrong.",
      "source": { "pointer": "field.path" }
    }
  ]
}

The pointer identifies the offending field. The code is machine-readable; the detail is what to show your engineer (and, after translation, your end user).

Create account

parameter_required on type

{
  "errors": [{
    "code": "parameter_required",
    "detail": "type is required.",
    "source": { "pointer": "type" }
  }]
}

Cause. The Create call omitted the account type.
Fix. Send "type": "merchant" or "type": "consumer" in the request body. The type is permanent for the account.

parameter_invalid on person.email_address or person.mobile_number

Cause. The email is malformed or the mobile number is missing a country code (PH numbers should be in E.164 form, for example +639991234567).
Fix. Validate format on your side and resubmit.

5xx on Create

Cause. Transient PayMongo error.
Fix. Do not blindly retry — first list existing children or look up by email and mobile to confirm whether the account was created despite the error. If it was not, retry with a back-off.

Identity verification

Session expired

Symptom. The hosted identity verification URL returns "session expired" or the API returns verification_session_expired.
Cause. Sessions are valid for 72 hours from creation.
Fix. Create a new verification session and send the new URL to the user.

parameter_invalid on document URLs (API-only flow)

Cause. The provided URL is not HTTPS, is unreachable, or returns a non-image content type.
Fix. Host the image on HTTPS, confirm a 200 OK response with image/jpeg or image/png, then resubmit.

Webhook event has result: failed

{
  "failure_reason": "Please retry. Move closer to the camera, use even lighting, and ensure the face takes up at least half the image height."
}

Cause. The verification was attempted but failed (poor image quality, document not recognized, liveness check failed).
Fix. Show failure_reason to the user and start a new identity verification session. See Best practices — Identity verification for retry guidance.

Webhook event has result: invalid

Cause. The submitted data was incomplete or malformed (for example, a secondary ID without the required second secondary document).
Fix. Review the submission, correct the payload, then start a new session.

Update account

parameter_invalid on an enum field

Cause. The provided value is not in the accepted enum list. Common culprits: industry MCC, state code, nature of work, source of funds.
Fix. Look up the accepted values in the Appendix, correct your payload, and PATCH again.

parameter_invalid on person.tin or business.tin

Cause. The TIN format is not recognized.
Fix. Use the canonical format including dashes (for example, 123-456-789-000 for businesses, 123-456-789 for individuals).

"Cannot update activated account"

Cause. The account is already in activation_status: activated. Updates are no longer allowed via the API.
Fix. For most fields, the account holder can edit through the PayMongo Dashboard. For fields locked even there, contact [email protected].

Activate account

parameter_required listing missing fields

{
  "errors": [{
    "code": "parameter_required",
    "detail": "business.industry is required for activation.",
    "source": { "pointer": "business.industry" }
  }]
}

Cause. One or more required-at-activation fields are not set.
Fix. Call Update account to set the listed fields, then call Activate again. See Required information per account type.

merchant.declined / consumer.declined webhook

Cause. Risk review declined the account. The decision is final.
Fix.

• Show the user a clear message (translate declined_message for your audience; do not show it raw).
• If you believe the decision was made in error, email [email protected] with the org_* ID and your context.
• For the user, the typical next step is a new account with corrected information.

Activate returns 200 but no webhook arrives

Cause. Either the activation is still under manual risk review, or your webhook delivery failed.
Fix.

1. Wait — most automated activations complete in minutes, manual reviews can take up to 14 business days.
2. Check the PayMongo Dashboard for the account's current activation_status.
3. Inspect your webhook log for delivery failures and re-deliver if needed.

Acting on behalf of a child (after activation)

resource_not_found with "No such child account"

{
  "errors": [{
    "code": "resource_not_found",
    "detail": "No such child account with id org_incorrectChildId."
  }]
}

Cause. The Account-Id header references an account that is not a child of the authenticated parent.
Fix. Confirm the org_* ID and that the account is linked to your parent. See Linked transactions.

payment_method_not_allowed

Cause. The child does not have the requested payment method enabled.
Fix. Request the capability via Account capabilities, then retry the call.

Webhooks

Events not arriving

Run through, in order:

1. Confirm the endpoint is registered in the correct scope (test vs. live, parent vs. child).
2. Confirm your endpoint returns 2xx within the timeout window.
3. Check the PayMongo Dashboard webhook log for delivery attempts and HTTP status codes.
4. Re-deliver any failed events from the Dashboard.

Same event received twice

Cause. Normal retry behavior — your handler did not respond 2xx fast enough on the first delivery.
Fix. Implement idempotency on evt_*. See Best practices — Webhooks.

Signature verification fails

Cause. Wrong signing secret, mutated payload (proxy added headers or rewrote JSON), or clock drift on signature timestamp.
Fix.

• Verify against the raw request body, before any JSON parsing.
• Use the signing secret listed in the Dashboard for the matching scope (test vs. live).
• Confirm the request reached your handler unchanged through any reverse proxy.

Where to get more help

• The relevant Best practices page for the stage you are debugging.
• Account resource — full field shapes for diagnosing payload errors.
• Email [email protected] for anything not covered here. Include the org_* ID, the evt_* ID (for webhook issues), and the full error response.