What is Linked accounts?

PayMongo accounts can be linked to one another in a parent / child relationship. A parent account invites other PayMongo accounts to become its children, or creates new ones, and then onboards, verifies, and operates on those children through the API.

This is how you build a platform on PayMongo: a business that serves other businesses or individuals and handles payments on their behalf. Common examples include marketplaces, SaaS products with embedded payments, franchise networks, and disbursement platforms.

Account linking applies to every PayMongo product that supports platform use cases, including payment acceptance, wallets, payouts, QR Ph, and more.

📘

Previously referred to as PayMongo Platforms or Seeds. Account linking is no longer a separate product. It is a feature available on every PayMongo account. The capabilities are the same; the framing and naming have changed.

Two ways to establish a link

A child account is linked to a parent in one of two ways. Pick the path that matches your use case and jump to the section for full details.

• Invite an account: send a linking request to a prospective child, who accepts to establish the link. Best for cases where the child needs to consent, already operates their own PayMongo account, or both.
• Create an account directly via the Accounts API: provision a brand-new child via the Accounts API. The parent owns the child from creation. Best for embedded use cases where your platform is the child's only entry point to PayMongo.

After an invite is accepted, the parent runs through the same onboarding flow used by direct creation. Either path ends at Onboard and activate the child.

Managing linked accounts

If you prefer a no-code workflow, manage links entirely from the PayMongo dashboard:

• Linked accounts → Sent: invites the parent has sent, with status.
• Linked accounts → Received: invites a child has received, with accept and decline actions.
• Linked accounts → Child accounts: the list of linked children, with search, filters, and per-child capability management.
• Linked accounts → Child payouts: payout activity across linked children.

The dashboard uses the same APIs described on this page.

Key concepts

Terminology

An account can be both a parent (to its children) and a child (of another parent) at the same time. Multi-level arrangements are allowed by the model, but most platforms operate a single flat layer.

What linking enables

Once a linking request is accepted, or a child is created directly, the parent can:

• Onboard the child. Create the child account (if not already created), submit KYC documents and requirements, and activate it for live transactions.
• Operate on the child's behalf. Create payment intents, checkouts, payouts, wallets, and other resources that belong to the child, using the parent's API keys with the child's account scope.
• [Coming soon] Manage the child's capabilities. Enable or disable features such as payment acceptance and wallet access per child. See Account capabilities for the full list.
• View the child's activity. Read payments, payouts, and other transaction data across linked children.

A child account that has accepted a link can:

• Transact normally on its own, using its own API keys and dashboard, independent of the parent.
• Accept, decline, or later disconnect linking requests from the parent.

🚧

All linked-account API calls require a secret API key (sk_test_… or sk_live_…). Public keys (pk_*) cannot create or manage linking requests.

Linking accounts via Invite [Coming soon]

Who is this for and what it enables

Use the invite flow when the child needs to consent to the relationship before the parent acts on their behalf. This typically applies when the child already operates their own PayMongo account, or when you want a clean record of mutual agreement before linking.

Once the child accepts the invite, the parent gains scoped access to act on the child. From there, the parent runs through Onboard and activate the child to make the child ready for live transactions.

The linking request lifecycle

A linking request moves through one of the following statuses.

stateDiagram-v2
  direction LR
  [*] --> pending: parent sends invite
  pending --> accepted: child accepts
  pending --> declined: child declines
  pending --> cancelled: parent cancels
  accepted --> [*]
  declined --> [*]
  cancelled --> [*]

Only the two parties involved can move the state forward: the parent can cancel, and the child can accept or decline. A declined or cancelled request is terminal and cannot be revived. To try again, the parent sends a new invite.

Sending an invite

The parent sends an invite to the prospective child. Invites are batch-capable, so a platform can onboard many children in a single call. Specify a child in one of two ways:

• By email: for a business or individual that does not yet have a PayMongo account. PayMongo emails them a link to sign up and accept.
• By child account ID: for a business or individual that already has a PayMongo account. They see the invite in their dashboard and can accept it immediately.

curl --request POST \
     --url https://api.paymongo.com/v2/linking-requests/invites \
     --header 'Content-Type: application/json' \
     --header 'authorization: Basic <base64-encoded-secret-key>' \
     --data '{
       "data": {
         "attributes": {
           "invites": [
             {
               "email": "[email protected]",
               "account_type": "merchant"
             },
             {
               "child_account_id": "acct_abc123",
               "account_type": "merchant"
             }
           ]
         }
       }
     }'

For the full request and response schema, see Send linking request invites in the Accounts API reference.

Responding to an invite

The child receives the invite and responds from their PayMongo dashboard under Linked accounts → Received, or via API.

curl --request POST \
     --url https://api.paymongo.com/v2/linking-requests/{id}/accept \
     --header 'authorization: Basic <base64-encoded-secret-key>'

curl --request POST \
     --url https://api.paymongo.com/v2/linking-requests/{id}/decline \
     --header 'authorization: Basic <base64-encoded-secret-key>'

Until the child responds, the parent can withdraw the invite.

curl --request POST \
     --url https://api.paymongo.com/v2/linking-requests/{id}/cancel \
     --header 'authorization: Basic <base64-encoded-secret-key>'

Either party can list and filter their linking requests at any time.

curl --request GET \
     --url 'https://api.paymongo.com/v2/linking-requests?status=pending' \
     --header 'authorization: Basic <base64-encoded-secret-key>'

List results are cursor-paginated. Filter by status, email, account_type, or caller_role (use sender to see what you sent as a parent, receiver to see what you received as a child).

Onboard and activate the child

Who is this for and what it enables

Onboarding applies to every child the parent has access to, whether through an accepted invite or direct provisioning via the Accounts API. The flow covers creation, identity verification, account update, and activation. All steps run through the Accounts API.

Once activated, the child can transact. Until activation, the child cannot accept payments or move money.

🚀

Auto-configuration is coming soon. Today, the parent sets the child's capabilities (payment acceptance, wallet access, and so on) per child after creation. Auto-configuration will let you define a default capability set at the parent level and have it applied to every new child created through the API.

Child account onboarding lifecycle

flowchart LR
  A[Create account] --> B[Identity verification]
  B -->|passed| C[Update account]
  B -->|failed| B
  C --> D[Activate account]
  D -->|missing required fields| C
  D -->|approved by risk review| E[Activated]
  D -->|declined by risk review| F[Declined]

The flow has three retry points:

• Identity verification fails. The authorized representative restarts identity verification and submits another attempt. Repeat until the result is passed before proceeding to activation.
• Activation reports missing fields. The API returns an error listing the incomplete items. Call Update account to supply them, then call Activate account again.
• Activation is declined by risk review. The child cannot transact. The decision is final for this account; contact PayMongo support if you believe it was made in error.

Onboarding steps

1. Create the child account (if invited by email and not yet created) with Create account.
2. Complete identity verification for the authorized representative via Account identity verification. Choose between a hosted flow (PayMongo provides the capture microsite) or an API-only flow (you submit the selfie and ID images directly).
3. Update remaining account details with Update account. Some fields are pre-filled from identity verification; you fill in the rest. This endpoint can be called multiple times to save progress.
4. Upload supporting documents via the File record endpoints when needed. Business documents (SEC, DTI, and similar) are required only when upgrading the child to payment methods beyond QR Ph.
5. Submit the child for activation with Activate account.

The specific required fields depend on the account type. See the child merchant onboarding reference and the related consumer reference for the full list.

⚠️

Once a child account is activated, its details can no longer be edited through the API. Confirm all information is correct before calling Activate account.

Activation webhooks

Once a child is activated or declined, PayMongo emits account lifecycle webhook events to the parent's configured webhook endpoint. These events are the reliable signal that a linked child is ready to transact.

See the accounts webhook reference for payload shapes.

🚧

PayMongo does not currently emit dedicated linking_request.* events for the invite lifecycle. If your integration needs to react the moment a child accepts (before activation), poll GET /v2/linking-requests/{id}, or use merchant.activated and consumer.activated as the downstream signal.