---
title: "Create capability request on a merchant's behalf (S2S only)"
method: POST
path: "/v1/internal/requests"
tags: ["Internal Capability Requests"]
---

# Create capability request on a merchant's behalf (S2S only)

`POST /v1/internal/requests`

## Request

- Base URL: `https://api.paymongo.com`
- URL: `https://api.paymongo.com/v1/internal/requests`
- Auth: HTTP bearer

Creates a capability request for the account named in `account_id`. Takes the same body as `POST /v1/requests` — JSON, or `multipart/form-data` with a `payload` part plus `files_<purpose>` parts — and applies the same validation, duplicate check and activation precondition. Per-product `kyb_data` rules, document purposes and upload limits are in the [Capability requests API](https://docs.paymongo.com/docs/onboarding-aas-capability-requests) guide; the two internal-only products' shapes are in the request body below.

This is where PayMongo opens the two requests that are part of activating an account, and which a merchant does not open themselves: `prd_svc_paymongo_account_activation` and `prd_svc_paymongo_std_wallet`. Neither needs the account to be activated first.

**Which account.** An S2S token carrying an `account_id` claim creates the request for that account, and the body's `account_id` is ignored. Otherwise `account_id` in the body is required.

**Status the request is created in.** `prd_svc_paymongo_account_activation` is created `submitted`. `prd_svc_paymongo_std_wallet` is created `draft`: the wallet upgrade and profile write already happen at create time. Every other product is created as `POST /v1/requests` describes.

`request_type` values: `onboarding` (every product except account update — what every current caller sends), `account_update` (`prd_svc_paymongo_account_update`), and `product_request` / `config_update`, which are accepted but sent by nobody today and are not documented publicly.

`request_type` is not validated against `product_code`, but assignee-group permissions are granted per (`request_type`, `product_code`) pair — a value nobody holds a permission for leaves the request unassignable.

Unlike the public endpoint, the response carries the ops-only fields (`requester_id`, `assignee_email`, `internal_note`, `kam_ids`, `changes`).

## Request body

- object
  - `account_id` string: AccountID is the account the request belongs to. On create, a merchant key is locked to its own account and any value sent here is ignored; service-to-service callers have no bound account and must supply it.
  - `kyb_data` union: Pick the shape for the request's `product_code`. Any `files_<purpose>` key beyond the ones listed is also accepted and stored verbatim (except `files_draft`).
    - object: `prd_svc_paymongo_account_activation`. The identity of the business, plus its business documents.
      - `account_type` string
      - `business_type` 'individual' | 'sole_proprietor' | 'partnership' | 'corporation'
      - `is_one_person_corporation` boolean
      - `business_legal_name` string
      - `business_trade_name` string
      - `business_dti_registered_name` string
      - `business_description` string
      - `files_dti_registration` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_sec_registration` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_articles_of_incorporation` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_articles_of_partnerships` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_by_laws` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_latest_gis` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
    - object: `prd_svc_paymongo_std_wallet` ("Enabled Wallet"). The full business profile, plus the business documents for the business type (sole proprietor: `files_dti_registration`; partnership: `files_articles_of_partnerships`, `files_sec_registration`; corporation / OPC: `files_articles_of_incorporation`, `files_sec_registration`, `files_by_laws`, `files_latest_gis`, `files_appointment_of_officers`).
      - `business_trade_name` string
      - `business_description` string
      - `business_industry` string: The business's Merchant Category Code (MCC). See [Merchant Category Codes](https://docs.paymongo.com/docs/account-settings-merchant-category-codes) for the list.
      - `business_size` 'less_than_10' | 'between_10_and_50' | 'between_51_and_250' | 'greater_than_250'
      - `business_age` 'less_than_1_year' | 'between_1_and_2_years' | 'between_2_and_5_years' | 'greater_than_5_years'
      - `business_estimated_monthly_volume` 'less_than_100K' | 'between_100K_and_300K' | 'between_300K_and_500K' | 'between_500K_and_1M' | 'between_1M_and_3M' | 'greater_than_3M'
      - `business_tin` string
      - `business_email` string, email
      - `business_has_physical_stores` boolean
      - `business_address` KybDataAddress
        - `line1` string
        - `line2` string
        - `city` string
        - `state` string
        - `postal_code` string
        - `country` string: ISO 3166-1 alpha-2 country code.
      - `ack_sd_requirement` boolean
      - `plugin` boolean
      - `tax_gross_remittances` 'do_not_exceed_500k' | 'exceed_500k'
      - `files_bir_certificate_of_registration` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_sworn_declaration` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_dti_registration` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_sec_registration` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_articles_of_incorporation` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_articles_of_partnerships` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_by_laws` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_latest_gis` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_appointment_of_officers` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
    - object: `prd_svc_paymongo_account_update`. A PARTIAL payload — only the fields being changed. `change_reason` is required unless the payload changes only `business_size` and/or `business_age`. Validation rules and required documents: [Account update](https://docs.paymongo.com/docs/onboarding-aas-capability-requests#account-update).
      - `change_reason` string: Why the merchant is changing their details. Required unless the payload is auto-approvable.
      - `business_trade_name` string
      - `business_legal_name` string
      - `business_type` 'individual' | 'sole_proprietor' | 'partnership' | 'corporation'
      - `is_one_person_corporation` boolean
      - `business_description` string
      - `business_industry` string: The business's Merchant Category Code (MCC). See [Merchant Category Codes](https://docs.paymongo.com/docs/account-settings-merchant-category-codes) for the list.
      - `business_size` 'less_than_10' | 'between_10_and_50' | 'between_51_and_250' | 'greater_than_250'
      - `business_age` 'less_than_1_year' | 'between_1_and_2_years' | 'between_2_and_5_years' | 'greater_than_5_years'
      - `business_estimated_monthly_volume` 'less_than_100K' | 'between_100K_and_300K' | 'between_300K_and_500K' | 'between_500K_and_1M' | 'between_1M_and_3M' | 'greater_than_3M'
      - `business_website` string
      - `business_tin` string
      - `business_has_physical_stores` boolean
      - `business_address` KybDataAddress
        - `line1` string
        - `line2` string
        - `city` string
        - `state` string
        - `postal_code` string
        - `country` string: ISO 3166-1 alpha-2 country code.
      - `customer_service_number` string
      - `support_email` string, email
      - `plugin` boolean
      - `tax_gross_remittances` 'do_not_exceed_500k' | 'exceed_500k': `do_not_exceed_500k` requires `ack_sd_requirement` true in the same payload.
      - `ack_sd_requirement` boolean
      - `files_signed_request_letter` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
    - object: `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 `{}` — nothing needs re-sending. If `GET /v1/requests/eligibility/{product_code}` reports a missing field, include it here (for example `business_website`); a missing document is attached as a `files_<purpose>` part of a `multipart/form-data` body. What you send fills the gap for the eligibility check and is written to the account on approval.
    - object: `prd_svc_paymongo_tax_document`. Documents only.
      - `files_bir_2303` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_tax_exemption` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
      - `files_tax_sworn_declaration` union: The id of a file uploaded with this request, or an array of them. To upload a document, send it as a `files_<purpose>` part of a `multipart/form-data` body.
        - string
        - string[]
  - `product_code` 'prd_svc_paymongo_account_activation' | 'prd_svc_paymongo_card_visa_mastercard' | 'prd_svc_paymongo_ewallet_gcash' | 'prd_svc_paymongo_ewallet_grabpay' | 'prd_svc_paymongo_ewallet_maya' | 'prd_svc_paymongo_ewallet_shopeepay' | 'prd_svc_paymongo_std_wallet' | 'prd_svc_paymongo_tax_document' | 'prd_svc_paymongo_account_update', required: ProductCode is what is being asked for. Every product code is accepted here, including the two that are not part of the public contract: prd_svc_paymongo_account_activation and prd_svc_paymongo_std_wallet.
  - `request_type` 'account_update' | 'config_update' | 'onboarding' | 'product_request', required: RequestType classifies the request; it follows from product_code. Nothing branches on it.
  - `requester_id` string, required: RequesterID identifies who initiated the request. Caller-supplied. Required, but not validated for shape and not used for authorization.

## Response `200`

OK

- object: Standard response containing data and its metadata if any
  - `data` RequestResDTO
    - `account_id` string: AccountID is the account the request belongs to. On create, a merchant key is locked to its own account and any value sent here is ignored; service-to-service callers have no bound account and must supply it.
    - `allowed_kyb_override_keys` string[]: AllowedKybOverrideKeys is the set of kyb_override keys this request's product accepts, sorted. Ops-only, and attached to the internal single-request responses only. It is served rather than documented because the admin dashboard was mirroring it by hand, transcribed out of a rejection message — a mirror that goes stale silently, and did: keys the API accepts stopped being offered, so a reviewer could no longer ask a merchant for certain documents.
    - `applied_kyb_override_keys` string[]: AppliedKybOverrideKeys is the subset of THIS call's kyb_overrides that was written to the merchant's account, sorted. Present on the internal PATCH response only. It exists because a partial save is not uniformly applied: account_update writes the armed profile fields immediately, but defers business_type (one-way — it flips has_selected_business_type, and a later decline could not walk that back) and files_* keys (promotion deletes the documents it supersedes, and the request is still under review). Without this list a reviewer would have to assume an armed key was written, which is the silent-no-op failure the whole contract exists to prevent.
    - `applied_to_account` boolean: AppliedToAccount says whether a kyb_override write on this product reaches the merchant's ACCOUNT, or only stages values on the request for a later approval to apply. Pointer so that false is serialised rather than dropped — false is the whole point of the field. account_update stages; the payment-method and activation flows write through. The caller should not have to hard-code which is which.
    - `assigned_at` string, date-time
    - `assignee_email` string
    - `audit_history` RequestAuditLogResDTO[]: Audit trail - populated when fetching single request details
      - `action_type` string: assigned, unassigned, reassigned, status_changed, field_updated
      - `actor` string: Who performed the action (from JWT admin_id)
      - `created_at` string
      - `field_name` string: Which field was changed
      - `id` string
      - `new_value` string: Value after change (empty for removal)
      - `note` string: Optional human-readable note
      - `previous_value` string: Value before change (empty for initial)
      - `request_id` string
    - `cancelled_at` string, date-time
    - `changes` object: Changes gives an old/new view per submitted kyb_data field for account_update requests: old is the organization's current value (fetched live from Core API), new is the submitted value. Populated on the internal detail endpoint only.
    - `completed_at` string, date-time
    - `created_at` string
    - `declined_at` string, date-time
    - `email_notifications_enabled` boolean: EmailNotificationsEnabled is false when ops have stopped the merchant-facing emails for this request. Webhooks still fire. Ops-only.
    - `id` string: ID is the unique identifier of this request.
    - `internal_note` string
    - `kam_ids` string[]
    - `kyb_data` object: KybData is the KYC/KYB details submitted for this request, as a JSON object.
    - `merchant_note` MerchantNoteDTO
      - `note` string
      - `requested_custom_files` string[]: RequestedCustomFiles are reviewer-typed names for documents outside the purpose list.
      - `requested_fields` string[]: RequestedFields are kyb_data field keys the merchant must resupply.
      - `requested_files` string[]: RequestedFiles are document purposes the merchant must re-upload, without the `files_` prefix.
      - `set_at` string
    - `organization_data` object
    - `pending_clarification_at` string, date-time
    - `processed_at` string, date-time
    - `product_code` 'prd_svc_paymongo_account_activation' | 'prd_svc_paymongo_card_visa_mastercard' | 'prd_svc_paymongo_ewallet_gcash' | 'prd_svc_paymongo_ewallet_grabpay' | 'prd_svc_paymongo_ewallet_maya' | 'prd_svc_paymongo_ewallet_shopeepay' | 'prd_svc_paymongo_std_wallet' | 'prd_svc_paymongo_tax_document' | 'prd_svc_paymongo_account_update': ProductCode identifies the product the request is for: account activation, one of the four e-wallets, card (Visa/Mastercard), Standard Wallet ("Enabled Wallet"), a tax document, or a business-profile update (account_update). All product behaviour keys off this field.
    - `request_type` 'account_update' | 'config_update' | 'onboarding' | 'product_request', required: RequestType classifies the request; it follows from product_code. Nothing branches on it.
    - `requester_id` string, required: RequesterID identifies who initiated the request. Caller-supplied. Required, but not validated for shape and not used for authorization.
    - `status` 'draft' | 'submitted' | 'under_review' | 'pending_clarification' | 'processing' | 'completed' | 'declined' | 'cancelled'
    - `submitted_at` string, date-time
    - `under_review_at` string, date-time
    - `updated_at` string
  - `has_more` boolean

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `500`: Internal Server Error

---

[API](https://skmtc.dev/paymongo/apis/onboarding-api.md) - [All operations](https://skmtc.dev/paymongo/apis/onboarding-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paymongo/apis/onboarding-api/revisions/36885f98768f?raw)