📘
TLDR
When writing policies:

Focus on one rule at a time

Decide clearly when an action should be allowed or blocked

Use draft mode before activating

Layer multiple policies for stronger control

Policies give you flexibility without changing code—use them to reflect how your business actually operates.

How to Write Policies for Your Account

Policies allow you to define rules that control how actions are allowed or blocked in your PayMongo integration. This section explains how to write clear, effective policies that match your business needs.

1. Understand What a Policy Controls

Every policy is written for a specific resource and operation.

resource: What the policy applies to Example: wallet
pperation: The action being performed on the resource Example: CreateTransfer

A policy is evaluated only when that specific operation occurs.

2. Decide the Rule You Want to Enforce

Before writing a policy, clearly answer:

“When should this action be allowed, and when should it be blocked?”

Good policies usually answer one focused question, such as:

Who is allowed to perform the action?
Where can funds be sent?
How much can be transferred?
When can the action occur?

Keeping policies focused makes them easier to understand and maintain.

3. Write Policies as “Allow or Deny” Rules

Policies evaluate request data and return a simple decision:

Allow → the operation continues
Deny → the operation is blocked

You do not need to handle:

Database operations
API calls
Business process execution

Your policy only decides whether the action should be allowed based on the data provided.

4. Use Available Request Data

When a policy is evaluated, PayMongo provides all relevant data for that operation, such as:

User role or permissions
Source and destination accounts
Transaction amount
Provider details
Time and context of the request

Your policy should only rely on this provided data and avoid assumptions.

5. Keep Policies Small and Specific

Instead of writing one large policy that handles many conditions, we recommend:

✅ One policy = one concern

Examples:

“Only finance admins can transfer”
“Transfers must be below ₱500,000”
“Transfers can only go to approved accounts”

Multiple policies can be active at the same time, and all must pass for the action to proceed.

6. Use Clear and Descriptive Names

Policy names should clearly describe their purpose.

Good examples:

Wallet Transfer – Finance Admin Only
Wallet Transfer – Amount Limit
Wallet Transfer – Approved Destinations

Clear naming makes it easier to audit and troubleshoot blocked actions.

7. Start in Draft Mode

When you create a policy, it starts as deactivated (draft).

Best practice:

Create the policy in draft mode
Review and test it
Activate it only when you’re confident it behaves as expected

Draft policies have no impact on live operations.

8. Understand How Multiple Policies Work Together

If multiple active policies apply to the same resource and operation:

All policies are evaluated
All must allow the action

If any policy denies the action, the operation is blocked.

This allows you to layer controls safely and predictably.

9. Handle Violations Clearly

When a policy blocks an action, the system returns:

A denial result
A list of policy violations

Write policies with clear intent so violations are easy to understand and fix.

10. Common Mistakes to Avoid

🚫 Writing overly complex policies 🚫 Combining many unrelated rules in one policy 🚫 Activating policies without testing 🚫 Using unclear or generic policy names

Example Policy Writing Approach

Instead of:

“Allow transfers only for finance admins, during business hours, below ₱500k, and only to approved accounts”

Write:

Policy A: Role restriction
Policy B: Time restriction
Policy C: Amount limit
Policy D: Destination whitelist

This makes policies easier to manage and safer to update.