Overview

This section explains how a parent account can act on behalf of a child account for payment-related endpoints. This allows the parent to perform payment operations as if the child account is the one processing—while still preserving ledger accounting, visibility and compliance separation.

Prerequisites

Before you can act on behalf of a child account, ensure you have:

Activated child account - The child account must be fully activated and verified
Product configuration - The child account must have the necessary payment products provisioned and properly configured

Request Context & Behavior

To act on behalf of a child account, include the child account context in your API requests. This specifies which connected account the operation applies to, allowing your platform to create and retrieve payment-related resources on behalf of that child account.

Authentication Headers

Authorization: Basic <encoded_parent_secret_key>
Account-Id: org_childId

Automatic Metadata Enhancement

Any records created while acting as a child account automatically include additional metadata fields that indicate which accounts were involved in the request. PayMongo does not overwrite any existing metadata you send — it simply adds these internal keys to your existing metadata object.

"metadata": {
  "order_id": "your_existing_metadata_1",
  "customer_id": "your_existing_metadata_2",
  "PYM_executed_for": "org_childId",
  "PYM_requested_by": "org_parentId"
}

Supported Resources

The following resources support parent account operations on behalf of child accounts:

Resource	Supported Actions
Payment Intents	Create, Retrieve, Attach
Payment Methods	Create, Retrieve, Update
Payments	Retrieve, List
Refunds	Create, Retrieve, List
Checkout Sessions	Create, Retrieve, Expire
Webhooks	Create, Retrieve, List, Update, Enable, Disable

Code Examples

Payment Intent Creation Example

Request

curl --request POST \
     --url https://api.paymongo.com/v1/payment_intents \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Basic base64(sk_parentKey)' \
     --header 'Account-ID: org_childId' \
     --data '
{
  "data": {
    "attributes": {
      "amount": 2000,
      "payment_method_allowed": [
        "qrph",
        "card"
      ],
      "payment_method_options": {
        "card": {
          "request_three_d_secure": "any"
        }
      },
      "currency": "PHP",
      "capture_type": "automatic",
      "split_payment": {
        "recipients": [
          {
            "merchant_id": "org_parentID",
            "split_type": "fixed",
            "value": 1000
          }
        ],
        "transfer_to": "org_childId"
      },
      "description": "Sample payment"
    }
  }
}
'

Response

{
    "data": {
        "id": "pi_38enr4EUH3TJf3qsNT2k3y1x",
        "type": "payment_intent",
        "attributes": {
            "amount": 2000,
            "capture_type": "automatic",
            "client_key": "pi_38enr4EUH3TJf3qsNT2k3y1x_client_CNxvkfuGqozYMwRZmnkE76Hv",
            "currency": "PHP",
            "description": "Sample payment",
            "livemode": true,
            "original_amount": 2000,
            "statement_descriptor": "PayMongo Test Account",
            "status": "awaiting_payment_method",
            "last_payment_error": null,
            "payment_method_allowed": [
                "card",
                "qrph"
            ],
            "payments": [],
            "next_action": null,
            "payment_method_options": {
                "card": {
                    "request_three_d_secure": "any"
                }
            },
            "metadata": {
                "PYM_executed_for": "org_childId",
                "PYM_requested_by": "org_parentID"
            },
            "setup_future_usage": null,
            "split_payment": {
                "transfer_to": "org_childId",
                "recipients": [
                    {
                        "merchant_id": "org_parentID",
                        "split_type": "fixed",
                        "value": 1000
                    }
                ]
            },
            "created_at": 1761197876,
            "updated_at": 1761197876
        }
    }
}

Webhook Considerations

🚧
Important: Webhook events, such as payment.paid, are sent only to the child account’s webhook endpoint, since the payment is attributed to that child account. They are not delivered to the parent account’s webhooks.

For now, we recommend creating webhooks while acting as a child account to receive the correct webhook events for transactions processed on that account’s behalf.

To create a webhook for a child account, include the same Account-Id header in your webhook API requests:

curl --request POST \
     --url https://api.paymongo.com/v1/webhooks \
     --header 'accept: application/json' \
     --header 'authorization: Basic base64(sk_parentKey)' \
     --header 'Account-ID: org_childId' \
     --data '
{
  "data": {
    "attributes": {
      "events": [
        "payment.paid"
      ],
      "url": "https://parent-site.com/webhooks"
    }
  }
}
'

Error Handling

On most cases, you'll receive the same errors as if you're using the existing routes. However, there are specific scenarios to be aware of when acting on behalf of child accounts.

Common Error Scenarios

Invalid Child Account

When the Account-Id in the header is not a valid child account of the parent:

{
    "errors": [
        {
            "code": "resource_not_found",
            "detail": "No such child account with id org_incorrectChildId."
        }
    ]
}

Child Account Not Configured

When the child account doesn't have the required payment methods or products configured:

{
    "errors": [
        {
            "code": "payment_method_not_allowed",
            "detail": "gcash payment method is not allowed.",
            "source": {
                "pointer": "type",
                "attribute": "type"
            }
        }
    ]
}