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), 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

under_review, 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}).

Full request and response schemas, with a kyb_data example per product, are in the API
reference: Create capability request.

Status lifecycle

flowchart LR
  A([POST /v1/requests]) --> B[submitted]
  B -->|PayMongo picks it up| C[under_review]
  C -->|needs info| D[pending_clarification]
  D -->|PATCH, then resubmit| C
  C -->|approved| E[processing]
  E --> F[completed]
  C -->|rejected| G[declined]

Entry point. Every request you create starts in submitted. Nothing is needed from you to get
it reviewed.

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 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": "onboarding",
    "product_code": "prd_svc_paymongo_ewallet_maya",
    "requester_id": "org_xxxxxxxxxxxx",
    "kyb_data": {}
  }'

Which account. The request is created for the account whose secret key made the call, or —
for a parent — for the child named in the Account-ID header. See
Requests on linked accounts.

One open request per product code. A second create while one is still submitted,
under_review or pending_clarification is rejected as a duplicate. account_update is checked
per field: a second request is rejected only if it touches a field or document already being
changed by an open request.

Status it is created in. submitted, with two exceptions decided on the spot:

• a prd_svc_paymongo_account_update that only changes business_size and/or business_age is
  auto-approved and created completed;
• a request whose registered business website is on PayMongo's prohibited list is created and
  immediately declined.

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:

{
  "data": {
    "product_code": "prd_svc_paymongo_ewallet_maya",
    "eligible": false,
    "missing": [
      { "type": "field", "key": "business_website", "label": "Business website is required" },
      { "type": "document", "key": "dti_registration", "label": "DTI registration is required" }
    ]
  }
}

missing lists what the account still has to supply — the same set enforced when creating the
request. Each entry's type is one of:

kyb_data by product

kyb_data is a JSON object. The keys below are the ones the API understands; what is actually
required is checked per product when the request is created, and an unmet requirement returns
400 naming the missing fields.

Documents appear in kyb_data as files_<purpose> keys holding the ID of an uploaded file, or an
array of them. You do not upload files separately — send them with the request, as described in
Attaching documents, and the IDs are filled in for you.

E-wallets and card

prd_svc_paymongo_ewallet_gcash, prd_svc_paymongo_ewallet_grabpay,
prd_svc_paymongo_ewallet_maya, prd_svc_paymongo_ewallet_shopeepay and
prd_svc_paymongo_card_visa_mastercard.

The account is the source of truth, so kyb_data is normally {} or omitted — nothing already
on the account needs re-sending. Call eligibility first. If it reports
something missing, include it in this request: a missing field (for example business_website) in
kyb_data, a missing document as a files_<purpose> part. What you send fills the gap for the
eligibility check and is written to the account when the request is approved.

{
  "request_type": "onboarding",
  "product_code": "prd_svc_paymongo_ewallet_gcash",
  "requester_id": "org_xxxxxxxxxxxx",
  "kyb_data": {}
}

Account update

prd_svc_paymongo_account_update changes the business profile. kyb_data is a partial
payload: only the fields being changed, never the whole profile. You do not need to send the old
values — PayMongo records what each changed field held before.

{
  "request_type": "account_update",
  "product_code": "prd_svc_paymongo_account_update",
  "requester_id": "org_xxxxxxxxxxxx",
  "kyb_data": {
    "business_trade_name": "Acme Home",
    "change_reason": "Rebranding"
  }
}

Rules, all checked when the request is created:

• change_reason is required, unless the payload only changes business_size and/or
  business_age — those are auto-approved.
• A trade-name, legal-name or business-type change requires a passed liveness check.
• A trade-name change requires an enabled wallet, and carries the signed request letter as
  files_signed_request_letter.
• A legal-name change requires a registered business type. The type the request moves the
  account to counts, so business_type and business_legal_name can be sent together.
• business_type can be changed only while the account is still individual. It is refused once
  the account holds a registered type. The request carries the documents the new type
  requires — see Business documents by business type.
• tax_gross_remittances: "do_not_exceed_500k" requires ack_sd_requirement: true in the same
  payload.

Tax document

prd_svc_paymongo_tax_document takes documents only: files_bir_2303, files_tax_exemption and
files_tax_sworn_declaration, attached as parts of a multipart/form-data body. kyb_data can be
{}.

Attaching documents

Send the request as multipart/form-data instead of JSON:

• one part named payload, with Content-Type: application/json, carrying exactly the JSON body
  you would otherwise send;
• one part per document, named files_<purpose>. Repeat a part name to attach several documents
  of the same purpose.

curl -X POST https://api.paymongo.com/v1/requests \
  -u sk_live_xxxxxxxxxxxx: \
  -F 'payload={"request_type":"onboarding","product_code":"prd_svc_paymongo_tax_document","requester_id":"org_xxxxxxxxxxxx","kyb_data":{}};type=application/json' \
  -F '[email protected]'

The uploaded files are added to kyb_data under their part name before anything is validated, so
the request is checked exactly as if the documents had been there all along. A request with no
documents can be sent as plain application/json.

The same format works on PATCH /v1/requests/{id}. There, uploads are added to whatever that
key already holds — attaching a second document does not drop the first.

Uploaded documents are held with the request and only added to the account when PayMongo approves
it. Cancelling the request deletes them, and so does a create or update that fails validation.

Anything outside these limits is rejected with 400 before anything is stored.

Business documents by business type

What a business must provide depends on its type. This applies whenever documents are asked for:
a business_type change on an account update carries the documents for the new type, and a
payment method request fills in whichever ones eligibility reports missing.

For a payment method, eligibility is the authoritative list of what the
account is still missing. A reviewer may ask for more through pending_clarification.

Document purposes

Any files_<purpose> name is accepted, and new purposes are added over time without a new API
version. files_draft is reserved and rejected. The purposes in use today:

Business documents

Enhanced due diligence

Tax — tax document requests only

Others

Correcting a request

When PayMongo needs more, the request moves to pending_clarification and you receive a
capability_request.pending_clarification event. data.merchant_note says what is needed. Answering
takes two calls:

1. PATCH /v1/requests/{id} with the corrected kyb_data and any requested documents. The patch
   shallow-merges into the stored kyb_data — top-level keys you send replace or add, every other
   key is left alone — and is validated the same way as a create. It never changes the status.
2. POST /v1/requests/{id}/resubmit, with no body, to hand the request back for review. It
   returns to under_review, or to submitted if it has to wait to be picked up again.

curl -X PATCH https://api.paymongo.com/v1/requests/req_xxxxxxxxxxxx \
  -u sk_live_xxxxxxxxxxxx: \
  -H 'Content-Type: application/json' \
  -d '{ "kyb_data": { "business_trade_name": "Acme Home" } }'

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

To withdraw a request, POST /v1/requests/{id}/cancel (no body). Uploaded documents PayMongo has
not approved yet are deleted with it.

Product codes

Account activation (prd_svc_paymongo_account_activation) and the standard wallet
(prd_svc_paymongo_std_wallet) also appear as capability requests on an account, but PayMongo
opens them as part of activating the account — you do not request them over this API.

For parent platforms

A parent uses these endpoints for its own capabilities and for its
fully managed children's. Without an Account-ID
header, a request is scoped to the parent's own account. With one, it is scoped to the child named
in the header.

What a parent can do

Requests on linked accounts

To open, read, correct, or cancel a request on a child, authenticate with the parent's secret
key and name the child in the Account-ID header — the same pattern as
Linked transactions. Every endpoint in
Endpoints accepts it. Send the parent's organization ID as requester_id.

curl -X POST https://api.paymongo.com/v1/requests \
  -u sk_live_parentxxxxxxxx: \
  -H 'Account-ID: org_childxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "request_type": "account_update",
    "product_code": "prd_svc_paymongo_account_update",
    "requester_id": "org_parentxxxxxxxx",
    "kyb_data": {
      "business_trade_name": "Acme Home",
      "change_reason": "Rebranding"
    }
  }'

• The request belongs to the child. Its account_id is the child's, and the rules on this
  page — eligibility, kyb_data, documents, one open request per product code — are checked
  against the child's account.
• Events go to the child's webhook, not the parent's. Every capability_request.* event for
  the request is delivered to the webhook registered on the child. Register one on each child with
  the same Account-ID header — see
  Linked transactions and
  Capability request webhooks.

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: it comes back submitted (or already completed /
   declined for the on-the-spot outcomes).
3. Listen, do not poll — subscribe to capability_request.* on the webhook of the account the
   request belongs to (the child's, for a request on a child), 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. See Correcting a request.
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

• Create capability request — API reference, with a kyb_data example per product.
• Capability request webhooks — every event, payload sample, and resource field.
• Account capabilities — what a child gets at activation.
• 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 — the Account-ID header and child webhooks.