Who this section is for

Developers who open capability requests over the API instead of the merchant dashboard —
activating a payment method (GCash, Maya, GrabPay, ShopeePay, cards), requesting account
activation or a standard wallet, filing a tax document, or changing the business profile.

A capability request is an application to turn something on for an account. PayMongo reviews
it, and the request moves through a fixed set of statuses. Every status change is also pushed as
a webhook event — those payloads live in
Capability request webhooks.

Before you begin

Base URL: https://api.paymongo.com.

Endpoints

pending_clarification, processing, completed and declined are set by PayMongo during
review. There is no merchant-facing API call for them — you observe them through the webhook (or
by polling GET /v1/requests/{id}).

Status lifecycle

flowchart LR
  A[draft] -->|submit| B[submitted]
  B -->|review| C[under_review]
  C -->|needs info| D[pending_clarification]
  D -->|resubmit| C
  C -->|approved| E[processing]
  E --> F[completed]
  C -->|rejected| G[declined]

Entry points. Most requests start in draft and move on submit, but payment method,
account activation and tax document requests are created directly in submitted.

Terminal statuses. completed, declined and cancelled. A declined request can only be
reopened by PayMongo, which re-emits capability_request.submitted on the same request ID.

Cancelling. Allowed from draft, submitted, under_review and pending_clarification —
these paths are left off the diagram to keep it readable. Cancel is rejected from processing,
because the capability is already being provisioned, and from all three terminal statuses.

Creating a request

curl -X POST https://api.paymongo.com/v1/requests \
  -u sk_live_xxxxxxxxxxxx: \
  -H 'Content-Type: application/json' \
  -d '{
    "request_type": "product_request",
    "product_code": "prd_svc_paymongo_ewallet_maya",
    "requester_id": "usr_xxxxxxxxxxxx",
    "kyb_data": {}
  }'

Only one open request per product code is allowed. A second create while one is still in
draft, submitted, under_review or pending_clarification is rejected. For
account_update the check is per field: a second request is rejected only if it touches a field
or document already being changed by an open request.

Check eligibility first

For payment methods, check first so you fail fast:

curl https://api.paymongo.com/v1/requests/eligibility/prd_svc_paymongo_ewallet_maya \
  -u sk_live_xxxxxxxxxxxx:

{ "eligible": false, "missing": ["business_type", "files_valid_id"] }

missing lists the business type, documents and fields the account still has to supply. Fix
those on the account first — the same set is enforced when creating the request.

Moving a request

Transitions take no request body:

curl -X POST https://api.paymongo.com/v1/requests/req_xxxxxxxxxxxx/review \
  -u sk_live_xxxxxxxxxxxx:

Use resubmit after a capability_request.pending_clarification event, once you have supplied
what data.merchant_note asked for. To correct kyb_data first, PATCH the request — the patch
shallow-merges into the stored kyb_data, replacing top-level keys you send and leaving the rest
alone — then call resubmit.

Product codes

For parent platforms

A capability request is always scoped to the account whose secret key made the call. There is
no Account-Id header on this API, and the account_id field on POST /v1/requests is ignored
for merchant keys — merchant authentication is locked to its own account. So a parent uses these
endpoints for its own capabilities, not a child's.

What a parent can do today

Recommended parent flow

1. Check eligibility — GET /v1/requests/eligibility/{product_code} before you show the
   capability as available in your own UI.
2. Create the request — POST /v1/requests. Store the returned req_ ID against your own
   record, and read the returned status: payment method and activation requests come back
   already submitted.
3. Listen, do not poll — subscribe to capability_request.* and key your handler on
   data.attributes.data.id. See
   Capability request webhooks.
4. Handle pending_clarification — read merchant_note.note, merchant_note.requested_fields
   and merchant_note.requested_files, collect what is asked for, PATCH the request, then
   POST .../resubmit.
5. Settle on completed or declined — both are terminal. A declined request can only be
   reopened by PayMongo, which re-emits capability_request.submitted.

Related pages

• Capability request webhooks — every event, payload sample, and resource field.
• Account capabilities — what a child gets at activation and what is coming.
• Troubleshooting — stuck, parked, and declined requests.
• Account capabilities (catalog) — the canonical capability catalog and requirements.
• Quick start — create, verify, update, activate a child account.
• Linked transactions — operating on an activated child.