Who this section is for

Business owners, compliance leads, and engineers at platforms that will use Account Linking to operate on behalf of linked child accounts. This page describes how each linked relationship will be governed by a policy contract that both parties agree to.

Terminology bridge

The PayMongo Terms of Use and this documentation describe the same model with slightly different vocabulary. They are synonymous.

What a policy contract is

A policy contract is the agreement attached to a single linked-account relationship. It defines, in explicit terms, what the parent in that relationship may do on the child's behalf. Without an active contract, no parent action is allowed; with a contract, the parent's allowed actions are exactly what the contract permits — nothing more.

Policy contracts are tied to a specific relationship record (mr_xxxx). A different relationship — even between the same two accounts in the reverse direction — carries its own separate contract.

Why policy contracts exist

Multi-association linked accounts let an account participate in many relationships at once. Without policy contracts, every relationship would have to grant the parent full access — which is the right shape for fully-owned accounts but the wrong shape for partnerships, referrals, and embedded integrations.

Policy contracts let your platform negotiate a relationship that fits its purpose:

• A referral relationship where the parent can only view payments.
• A payment-acceptance partnership where the parent can create and refund payments but cannot read profile data.
• A fully-owned arrangement where the parent has CRUD on every resource.
• Anything in between.

The contract is the single, auditable source of truth for what is and isn't allowed on each relationship.

Where policy contracts fit in the linking model

flowchart LR
  REL[Relationship<br/>mr_xxxx<br/>parent → child] --> PC[Policy contract<br/>what parent may do<br/>on this relationship]
  C[Child account] --> CAP[Capabilities<br/>what products<br/>the child can use]
  PC -.->|"scoped by"| CAP

Three concepts work together:

• Relationship — one direction of the parent / child link. Identified by mr_xxxx. There is at most one relationship per direction per pair of accounts.
• Capability — what PayMongo products the child can use (QR Ph, wallets, cards, e-wallets, payouts). Lives on the child.
• Policy contract — what the parent may do on this specific relationship. Lives on the relationship.

A parent's effective permissions are the intersection of the two: the parent can act on a resource only if the child has the capability and the policy contract permits the action.

Capability vs. policy contract — what to use when

If your platform requests a capability for a child but the policy contract does not permit the parent to use it, the parent cannot transact for that capability on the child's behalf. The platform can still own the transaction on its own account and move funds to the child via transfer — that's a different shape, not a linked transaction.

Lifecycle

flowchart LR
  A[Parent authors policy] --> B[Invite sent with policy]
  B --> C{Child reviews}
  C -->|accepts| D[Contract active]
  C -->|declines| X[No relationship]
  D --> E{Either party<br/>proposes amendment}
  E -->|both agree| F[Amended contract active]
  E -->|either rejects| G[Either party detaches]
  D --> G
  F --> G
  G --> H[Pending-clearance state]
  H --> I[Outstanding obligations resolved]
  I --> J[Relationship severed]

Authoring

For the MVP, the parent authors the policy on every relationship. Policy contracts attach to relationships created through both onboarding paths:

• Invite path — the parent defines the policy on the invitation; the recipient accepts both the link and the policy together when they accept the invite.
• Create an account path — the parent defines the policy in the same call that creates the account and the relationship. The recipient inherits the policy implicitly (they did not go through an acceptance step in the Invite sense).

Future iterations may allow more flexible negotiation. For MVP, the contract is parent-authored and applied at relationship creation.

Acceptance

Acceptance of a linking request is acceptance of both the link and the policy contract. A child cannot accept the link while rejecting the policy — they are atomic.

Amendment

Amendments require mutual agreement. Either party can propose a change; the other must accept before the change takes effect. Until the amendment is accepted, the existing contract remains in force.

Detachment (termination)

Termination of a relationship is called detachment in PayMongo's Terms of Use (Part IV, Section 7). The two terms refer to the same action.

Either the Platform Account (parent) or the Linked Account (child) can initiate detachment at any time, and PayMongo can initiate it at its own discretion when required for compliance, fraud prevention, regulatory, dispute, or risk reasons.

flowchart LR
  A[Either party initiates<br/>detachment] --> B[Pending-clearance state]
  B --> C[No new Linked Transactions<br/>through the relationship]
  B --> D[PayMongo resolves<br/>outstanding obligations<br/>pending payouts, refunds,<br/>chargebacks, amounts owed]
  C --> E[Outstanding obligations<br/>resolved]
  D --> E
  E --> F[Relationship severed]
  F --> G[Linked Account continues<br/>as an independent Account]

Detachment is not instantaneous. On initiation, the relationship enters a pending-clearance state. During pending-clearance:

1. No new linked transactions may be initiated through the relationship.
2. PayMongo resolves outstanding obligations attached to the relationship — pending payouts, refunds, chargebacks, and any amounts owed in either direction — before the link is formally severed.

Once outstanding obligations are resolved, the relationship is severed. The Linked Account continues operating as an independent account; its history, balance, and capabilities remain on the account itself.

Liability

When operating under a linked-account relationship, liability for transactions, fees, refunds, chargebacks, and other financial obligations is allocated between the Platform Account and the Linked Account by the relationship's policy contract, the capabilities enabled on the Linked Account, and the binding rules in the PayMongo Terms of Use.

Two patterns are worth keeping in mind as you design your integration:

• Linked transactions. When the parent creates a transaction on behalf of the child through the relationship, the transaction is attributed to the child. Settlement, refund handling, and chargeback responsibility follow that attribution. The parent's role is operational; the child remains the merchant of record for the transaction.
• Parent-owned transactions. When the parent owns a transaction on its own account and later moves funds to the child via transfer (the workaround for capabilities the child does not hold), the parent is the merchant of record for that transaction and carries the corresponding obligations.

Default behavior at relationship creation

When a relationship is first established, the policy contract grants the parent visibility of linked transactions only by default. All other access — reading the child's profile, reading non-linked transactions, creating resources, updating resources — requires explicit grants in the contract.

This default protects the child. A platform that needs more than visibility must request it explicitly and have the child accept.

Multi-association implications

A child can be linked to many parents simultaneously. Each link is its own relationship with its own policy contract. The same child may grant:

• Parent A full CRUD on payment acceptance.
• Parent B read-only on wallets.
• Parent C view-only on transactions.

Each grant lives on its own mr_xxxx; revoking one does not affect the others.

Multi-level visibility is not transitive. If Parent A is linked to Account B, and B is linked to C, A cannot see C's data unless B and C separately grant A a policy that permits it.

Runtime authorization

Each request to act on a child is evaluated against the active policy contract for the relationship. If the request is outside the contract's scope, PayMongo will deny it and return a structured error explaining which rule was violated.

The exact error code, response shape, and webhook events for policy lifecycle are still being finalized. This section will be filled in when the release candidates are public.

What this means for your integration

If you operate today with single-association, fully-owned child accounts, your existing patterns continue to work — your relationships will be backfilled with policy contracts that match their current behavior as part of the release migration plan.

If you are planning a new integration that involves partnerships, referrals, or any case where the parent should not have full access to the child, design with policy contracts in mind:

• Inventory the actions the parent needs to perform on each child.
• Map each action to a resource + operation that the contract will permit.
• Confirm the child has the capabilities those actions require.
• Plan how your platform proposes amendments and handles termination on both sides.

Related pages

• PayMongo Terms of Use — Part IV (Platform Capability / Account Linking Feature) — the authoritative source for rights, obligations, detachment, and liability.
• Linked accounts — the canonical parent / child relationship model.
• Linked transactions — how parents act on linked children today; behavior will be policy-gated on release.
• Account capabilities — the per-account product enablement that policy contracts operate within.
• Onboarding-as-a-Service — Key concepts — how Onboarding-as-a-Service relates to linking.