Linked accounts

Link PayMongo accounts in a parent / child relationship to invite, onboard, and operate on other accounts through the Accounts API.

Who this section is for

Business owners, product leads, and engineers at registered businesses that connect to and manage other accounts on PayMongo — a marketplace with sellers, a platform with sub-merchants, or a group managing multiple entities or branches. This page explains what linked accounts are and walks through linking accounts by invitation.

What are linked accounts

Linked accounts connect two PayMongo accounts in a relationship where one side, the parent, can onboard and operate on behalf of the other, the child. It is the foundational model behind every PayMongo product that works across more than one account.

Parent and child are roles in a relationship, not account types. Both sides are full PayMongo accounts: the child keeps its own login, Dashboard, and independent operation, while the relationship gives the parent a defined set of actions it can perform on the child's behalf.

A relationship enables the parent to:

The parent canWhere it's documented
Onboard the child — create, verify, and activate itOnboarding-as-a-Service
Transact on the child's behalfLinked transactions
View the child's transactionsLinked transactions

A relationship grants the parent only what its policy contract permits. Broader access is explicit, never implied.

How relationships connect

Every relationship is direct and one-directional: it links exactly two accounts, with one side as the parent and the other as the child. Whatever a relationship allows applies only between those two accounts, in that one direction.

Three consequences are worth spelling out:

  • A relationship does not reach past its two accounts. Suppose your platform is the parent of a merchant, and that merchant is itself the parent of its own branch accounts. Your platform holds no relationship with those branches — there is no "grandchild." To operate on a branch, your platform must link with it directly.
flowchart LR
  P[Your platform] -->|parent of| M[Merchant]
  M -->|parent of| B[Merchant's branch]
  P -.->|no relationship| B
  • Two accounts can hold a relationship in each direction. Your account can be the parent of a partner's account while the partner's account is, separately, the parent of yours. These are two independent relationships, each with its own scope — the role you play depends on which relationship the action runs under.

  • An account can hold many relationships at once (Coming soon). With multi-association, the same account can be the parent of many accounts and, at the same time, the child of others — your platform manages its merchants while itself sitting under a group account. Each relationship stands on its own; parent and child describe the account's role in one relationship, never the account itself.

The relationship graph once multi-association ships (Coming soon):

flowchart TD
  G[Group account] -->|parent of| P[Your platform]
  P -->|parent of| M1[Merchant A]
  P -->|parent of| M2[Merchant B]
  X[Partner platform] -->|parent of| M2

How relationships are established

There are two ways to establish a relationship:

  • Invite — the parent invites an account in, and the recipient creates or owns it. This page covers the Invite flow.
  • Create an account — the parent creates the account directly via API. Documented under Onboarding-as-a-Service.

Whichever way the relationship starts, the access the parent ends up with depends on one question: is the parent enabled for full access?

From wanting to act on an account to the access tier that applies

You choose the access each time you invite or create a child. Custom access is open to every approved parent: you pick a scope for each module. Full access is an extra option that grants everything at once, and only platforms that have opted in and signed a mandate with PayMongo can pick it. To opt in, contact PayMongo or your account manager; there is no self-serve toggle. See Policy contracts for what each permission means.

🚀

Coming soon — Q4 2026

The linking model is expanding to multi-association — an account holding many relationships at once, acting as parent in some and child in others — with each relationship governed by an explicit policy contract both sides agree to. See Policy contracts for the full model.

Invite a new account by email

You can link a brand-new business or individual to your account by inviting them with their email address. This is for people who don't have a PayMongo account yet. Once they sign up and finish onboarding, they become your linked child account, and you can transact on their behalf.

There are two ways to do this, and this page covers both:

MethodBest forWhat it takes
Merchant DashboardLinking one or a few accounts by handPoint-and-click, no code
APIPlatforms that link accounts programmatically or at scaleA few API calls with your secret key

Both methods do the same thing behind the scenes, and they end the same way: your invitee receives a signup link, creates their PayMongo account, and completes standard onboarding.

📘

Two things to know before you begin

  • PayMongo does not send the invitation email for you. You generate a signup link and share it with your invitee through your own channel, such as your email or chat.
  • The email must match. Your invitee has to sign up using the exact email address you invited. Signup is rejected if the email is different.

What you'll need

  • Access to the parent account, which is the one doing the inviting.

  • A registered business type. The parent must be a Sole Proprietor, Partnership, One Person Corporation or Corporation. Individual accounts can't invite or create child accounts; Settings → Linked Accounts shows an Upgrade business type notice instead. Individual accounts can still be child accounts, and links you already have keep working.

  • Approval from PayMongo. Linked accounts are available by request. Until PayMongo approves your account, Settings → Linked Accounts shows Linked accounts are available by request in place of the invite actions. Click Request access there and confirm. PayMongo reviews the request within 3–7 business days, and the page shows its status until it is approved. See Account capabilities — Linked accounts.

  • Fully managed child accounts are a separate request. You can ask for them only after PayMongo approves your account for linked accounts. See Full access.

    To invite from the Dashboard, use the Account Owner, or any user whose role has the View & invite child accounts permission.

  • Your invitee's email address.

  • For the API, your account's secret API key.


Method 1: Merchant Dashboard

Step 1. Open Linked Accounts

Go to Settings and open Linked Accounts.

Step 2. Send the invitation

  1. Click Invite.
  2. Type the invitee's email address and press Enter to add it. You can add more than one address to invite several accounts at once.
  3. Choose the account Type:
    • Merchant: a business that will complete full business verification.
    • Non-business Individual: an individual who completes identity verification only.
  4. Under What you can do on child accounts, choose Custom access or Full access. Custom access lets you set each module yourself. Full access is available only to platforms that have opted in to full-access delegation. Opting in is a separate request that you can make after PayMongo approves your account for linked accounts; contact PayMongo or your account manager.
  5. Under Custom access, pick None, Linked, or All for each module. See Selecting permissions in the Merchant Dashboard for what each option means.
  6. Click Review invitation, check the summary, then click Send invitation.

Choosing permissions for each module

Your invitation appears in the Sent list with the status Pending and an invitation ID that starts with lr_.

Step 3. Copy and share the signup link

  1. On the new invitation row, click Copy signup link.
  2. Send that link to your invitee. It looks like this:
https://dashboard.paymongo.com/[email protected]&invitation_code=lr_xxxxxxxxxxxxxxxxxxxxxxxx

Share the copied link exactly as it is

The link already contains your invitee's email and invitation code. Don't retype or edit it. Just copy and share it directly so the values aren't changed.

Step 4. Your invitee signs up and onboards

When the invitee opens the link while signed out, they land on PayMongo's Create your account page with their email and invitation code already filled in. They then:

  1. Set a password and accept the Terms, leaving the pre-filled email unchanged.
  2. Verify their email with the one-time code.
  3. Complete standard PayMongo onboarding. This is identity verification, followed by business information (for merchants) or personal information (for individuals).

Step 5. Confirm the link

Back on the Invitations page, the invitation status changes from Pending to Accepted and shows the linked child account. The two accounts are now linked. Open the invitation to see the permissions the relationship grants.

Permissions granted on the new relationship


Method 2: API

Use the API to create and track invitations programmatically. This is ideal for platforms that want to link accounts to their platform programmatically. Full request and response schemas are in the Create invitations API reference.

📘

What the API does, and what it doesn't do

The API creates and tracks the invitation. It does not onboard your invitee for you. A new user still opens the signup link in a browser and completes signup and identity verification themselves. In other words, the API handles the invitation, and your invitee completes the rest. That rest is the same standard onboarding as any PayMongo account.

Authentication. Authenticate with your secret API key using HTTP Basic auth: your secret key is the username, and the password is left empty. Public keys cannot create or manage links.

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

Step 1. Create the invitation

Send a POST to /v2/linking_requests/invites with one or more invitees. Set account_type to merchant for a business or consumer for a non-business individual.

curl -X POST https://api.paymongo.com/v2/linking_requests/invites \
  -u sk_live_your_secret_key: \
  -H "Content-Type: application/json" \
  -d '{
    "invites": [
      { "email": "[email protected]", "account_type": "merchant" }
    ]
  }'

The response has one entry in results for each invitee, in the order you sent them. Each created invitation has an invitation ID in id (starting with lr_) and a status of pending:

{
  "data": {
    "total_invites": 1,
    "success_count": 1,
    "failed_count": 0,
    "results": [
      {
        "success": true,
        "linking_request": {
          "id": "lr_xxxxxxxxxxxxxxxxxxxxxxxx",
          "status": "pending",
          "request_type": "association",
          "parent_account_id": "org_parentxxxxxxxxxxxxxxxx",
          "child_account_id": null,
          "account_type": "merchant",
          "email": "[email protected]",
          "created_by": "org_parentxxxxxxxxxxxxxxxx",
          "created_at": 1792583080,
          "updated_at": 1792583080
        }
      }
    ]
  }
}

The linking_request object is trimmed here. See the Create invitations API reference for every field.

You can include several invitees in one request. Each one is reported independently, so some can succeed while others fail. A failed entry has "success": false and an error with a code and detail instead of linking_request.

Step 2. Build the signup link

Construct the signup link from the invitee's email and the invitation id you got back:

https://dashboard.paymongo.com/signup?email={EMAIL}&invitation_code={INVITATION_ID}

Encode the email

Encode the email before you put it in the link. In particular, a + must become %2B. For example, [email protected] becomes jane%[email protected]. Otherwise the invitee's prefilled email won't match the invitation, and signup will fail.

Step 3. Share the link and let your invitee onboard

Send the link to your invitee. They open it in a browser, create their PayMongo account with the prefilled email, and complete standard onboarding. This is identity verification, followed by business or personal information.

Step 4. Track the invitation

Listen for webhooks instead of polling. Register a webhook on your parent account and subscribe to linking_request.accepted, linking_request.declined, and linking_request.cancelled.

When your invitee signs up, PayMongo sends linking_request.accepted. Its data is the invitation: id is the invitation ID from Step 1, and child_account_id is the account your invitee created. Store that mapping. It's the only event that carries both IDs, because the activation events don't name the invitation.

{
  "data": {
    "id": "evt_xxxxxxxxxxxxxxxxxxxxxxxx",
    "type": "event",
    "attributes": {
      "type": "linking_request.accepted",
      "livemode": true,
      "data": {
        "id": "lr_xxxxxxxxxxxxxxxxxxxxxxxx",
        "status": "accepted",
        "request_type": "association",
        "parent_account_id": "org_parentxxxxxxxxxxxxxxxx",
        "child_account_id": "org_childxxxxxxxxxxxxxxxxx",
        "account_type": "merchant",
        "email": "[email protected]",
        "created_by": "org_parentxxxxxxxxxxxxxxxx",
        "accepted_at": 1792583087,
        "created_at": 1792583080,
        "updated_at": 1792583087
      },
      "previous_data": {},
      "pending_webhooks": 1,
      "created_at": 1792583087,
      "updated_at": 1792583087
    }
  }
}

See Invitation webhooks for every event and field.

You can also fetch an invitation by ID, for example to backfill invitations accepted before you subscribed:

curl https://api.paymongo.com/v2/linking_requests/lr_xxxxxxxxxxxxxxxxxxxxxxxx \
  -u sk_live_your_secret_key:
{
  "data": {
    "id": "lr_xxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "accepted",
    "request_type": "association",
    "parent_account_id": "org_parentxxxxxxxxxxxxxxxx",
    "child_account_id": "org_childxxxxxxxxxxxxxxxxx",
    "account_type": "merchant",
    "email": "[email protected]",
    "created_by": "org_parentxxxxxxxxxxxxxxxx",
    "accepted_at": 1792583087,
    "created_at": 1792583080,
    "updated_at": 1792583087
  }
}

The response is trimmed here. See the Get an invitation API reference for every field.

When status becomes accepted, child_account_id is filled in and the accounts are linked. You can also list invitations and filter by status, for example GET /v2/linking_requests?statuses=accepted. See the List invitations API reference for every filter.

If you can't receive webhooks

Poll once per day, in the morning. Invitations are usually not accepted for several days, so polling more often won’t surface the update any sooner.


After the invitation is accepted

When your invitee signs up with the invitation:

  • The invitation status becomes Accepted, and the invitation now carries the new child account ID. PayMongo sends linking_request.accepted.
  • The child account still has to finish onboarding before it can transact.

Once your invitee finishes onboarding and their account is activated:

  • PayMongo sends merchant.activated or consumer.activated for that child account. See Onboarding webhooks.
  • The link between your account and the child account is live, and you can transact on the child's behalf according to your Linked Accounts setup.
  • The child can also sign in and operate their own account independently.

Managing invitations

You can manage invitations from either the Dashboard or the API.

ActionMerchant DashboardAPI
See invitation statusOpen the row in Invitations → SentGET /v2/linking_requests or GET /v2/linking_requests/{id}
Cancel a pending invitationOpen the row and click CancelPOST /v2/linking_requests/{id}/cancel
Re-share the signup linkClick Copy signup link againRebuild the link from the email and invitation id

A couple of things to keep in mind:

  • Invitations don't expire. A pending invitation stays valid until it's accepted, declined, or cancelled.
  • One active invitation per email. You can't send a second pending invitation to an email that already has one. Cancel the first if you need to resend.

Invitation webhooks

PayMongo sends these events to the parent account's webhooks when an invitation leaves pending. Subscribe to them through the Webhook resource.

EventFires when
linking_request.acceptedThe invitee signed up with the invitation, or an existing account accepted it. The accounts are now linked.
linking_request.declinedThe invitee declined the invitation.
linking_request.cancelledThe invitation was cancelled.
  • Live mode only. Invitations created with test keys are not stored, so they send no webhooks.
  • Accepted is not activated. A new account sends linking_request.accepted as soon as it signs up, before it finishes onboarding. Wait for merchant.activated or consumer.activated with the same child_account_id before you transact on its behalf.
  • You get the event for your own actions too. Cancelling an invitation from the Dashboard or the API still sends linking_request.cancelled, so every system you run sees the change.
  • Handle each event once. Deliveries can repeat. Use the event ID (data.id) to skip events you have already processed. See Best practices for webhooks.
{
  "data": {
    "id": "evt_xxxxxxxxxxxxxxxxxxxxxxxx",
    "type": "event",
    "attributes": {
      "type": "linking_request.cancelled",
      "livemode": true,
      "data": {
        "id": "lr_xxxxxxxxxxxxxxxxxxxxxxxx",
        "status": "cancelled",
        "request_type": "association",
        "parent_account_id": "org_parentxxxxxxxxxxxxxxxx",
        "child_account_id": null,
        "account_type": "merchant",
        "email": "[email protected]",
        "metadata": { "reference": "store-42" },
        "created_by": "org_parentxxxxxxxxxxxxxxxx",
        "cancelled_at": 1792583187,
        "created_at": 1792583080,
        "updated_at": 1792583187
      },
      "previous_data": {},
      "pending_webhooks": 1,
      "created_at": 1792583187,
      "updated_at": 1792583187
    }
  }
}

Field reference

data.attributes.data is the invitation, with the same fields as GET /v2/linking_requests/{id}.

FieldTypeDescription
idstringInvitation ID. Prefixed lr_.
statusstringaccepted, declined, or cancelled. Matches the event type.
request_typestringassociation for an invitation. Changes to an existing relationship's permissions (Coming soon) send the same events with amendment.
parent_account_idstringYour account. Prefixed org_.
child_account_idstringThe account that accepted or declined. null on a cancelled email invitation.
account_typestringmerchant or consumer.
emailstringThe invited email address. null when the invitation named an existing account.
metadataobjectThe metadata you set when you created the invitation. Omitted when empty.
policy_selectionobjectThe permissions the invitation offered. See Policy contracts. Omitted when there are none.
created_bystringThe account that sent the invitation.
accepted_at, declined_at, cancelled_atintegerUnix timestamp of the change. Only the one that matches status is present.
created_at, updated_atintegerUnix timestamps.

Moving from hosted onboarding

If you onboarded accounts with hosted onboarding links, invite them from Settings → Linked Accounts instead. The main differences:

  • Where: Settings → Linked Accounts, with the Invite button.
  • What you choose: the account type and the access you need on the linked account (access tier and module permissions), instead of selecting features.
  • What the invitee does: signs up for their own PayMongo account and completes onboarding; the accounts are linked when they accept.
  • Tracking: invitation status (pending, accepted, declined, cancelled) on the Sent tab of Settings → Linked Accounts.
  • After linking: act on the account with Linked Transactions, within the access the invitee granted. Child API keys are not shared.
  • Capabilities: an invited account gets the default capabilities at activation, and more are added through capability requests.

Hosted onboarding was removed and receives no new features.

Reference

Account types

TypeAPI valueOnboarding the invitee completes
MerchantmerchantIdentity verification and business information
Non-business IndividualconsumerIdentity verification only

Invitation statuses

StatusMeaningWebhook
pendingInvitation sent. The invitee hasn't signed up yet.None
acceptedThe invitee signed up, and the accounts are linked.linking_request.accepted
declinedThe invitee declined the invitation.linking_request.declined
cancelledThe parent cancelled the invitation.linking_request.cancelled

Endpoints

PurposeMethod and path
Create invitationsPOST /v2/linking_requests/invites
List invitationsGET /v2/linking_requests
Get one invitationGET /v2/linking_requests/{id}
Cancel an invitationPOST /v2/linking_requests/{id}/cancel

Did this page help you?