We are currently integrating under the PF (Payment Facilitator) setup and would like to clarify a few points to ensure correct implementation:
⸻
Environment Clarification
• For Maya Vault testing, should we perform testing in Sandbox or Production?
• Are there any differences in:
• Risk checks / approval behavior
• Supported test cards
• Minimum transaction amounts
⸻
Vault Transaction Issue
We encountered the following error during Vault testing: PY0101 – Acquirer decline due to high risk
Kindly help clarify:
• Are there any active sub-merchants successfully using PF MID for Vault?
• Are there any prerequisites before Vault can be used under PF?
⸻
Minimum Transaction Amount
Is there a recommended minimum transaction amount for testing?
• For USD (Checkout / Vault)
• For PHP (PWM / QRPH)
⸻
PF Metadata Validation
We have completed metadata setup for QRPH and successfully tested transactions.
Could you help confirm:
• Is our metadata structure sufficient?
• Required fields we are using:
• smi
• smn
• mcc
• mci
• mco
• mpc
• Any required format validation or additional fields?
Kindly confirm:
• Is this expected behavior?
• Are currencies strictly tied to each MID type?
⸻
Sub-merchant Setup Flow
We would like to confirm the correct process:
• Is sub-merchant created purely via metadata (API call)?
• Is no additional onboarding/approval required per sub-merchant?
• For existing (non-PF) sub-merchants, do they need to be reconfigured under PF?
⸻
Industry & MID Mapping
• PF MID = 1 industry (MCC)
• If a new industry is added → new PF MID required
Kindly confirm:
• Is MCC strictly enforced per MID?
• What happens if MCC is incorrect during initial setup?
⸻
UAT & Production Readiness
• What are the exact requirements for:
• UAT certification
• Moving to Production
• Where should we submit:
• MRCHN ticket
• UAT documents
⸻
PF Field Definitions (Clarification)
We noticed discrepancies in documentation:
• mpc → ISO 4217 currency code?
• mco → ISO country code?
• postalCode → separate field?
Kindly confirm the correct mapping.
⸻
Current Status (for reference)
• QRPH (PWM) → successful testing completed
• Checkout / Vault → encountering issues
⸻
Appreciate your support and guidance to help us proceed correctly.
Hi @DylanChen, I’m not from Maya, but I’ll try my best to help. Were you able to check their documents from the Maya Developer Hub?
note: for the articles, kindly copy-paste instead. weird, I can’t reply with links.
Environment Clarification
I think there is no significant difference, Production just uses real-life payments. But as developers, it’s always a best practice for us to test in the lower environments first.
For online payments, like vault or checkout, they have this guide on what you can consider during your development and testing: developers.maya.ph/reference/business-rules-to-code-for-online-payments
For PY0101, I saw this: developers.maya.ph/reference/payment-related-errors#py0101—acquirer-decline-due-to-high-risk, it’s an error because of the card used
My account is not onboarded to the payment facilitator, but I’ve read somewhere that you need to contact your relationship manager with Maya to enable the feature for you. Then you must include the sub-merchant details in all the requests.
Minimum transaction amount - you can check the API specs, it’s already indicated there.
I saw this article but it’s for checkout, the mandatory fields are indicated: developers.maya.ph/reference/accept-payments-as-a-payment-facilitator-in-maya-checkout#21-prepare-the-checkout-request
There’s also a payfac guide, but it didn’t say while ones are required: developers.maya.ph/page/payment-facilitator-guide
The others can confirm, but I think the MID is on a per solution and currency, example I can have a checkout USD, checkout PHP, a vault PHP; they’ll give 3 separate MIDs.
Based on the docs, it seems that the sub-merchant is configured only though the API requests. Only the main merchant MID is configured on Maya during onboarding.
not sure about this.
Their production process is different per solution, developers.maya.ph/docs/maya-partner-journey . Usually, for online payments like vault, you just need to provide successful transactions per scheme and 200 OK webhook response.
@DylanChen, adding further clarifications and a few corrections below
Environment Clarification
We recommend conducting all initial testing in the Sandbox Environment using the provided Sandbox test accounts available in the Maya Developer Hub.
Core behaviors such as risk checks and approval logic are generally consistent between Sandbox and Production, although outcomes may still vary depending on real-world risk signals in Production.
Only Sandbox test accounts/cards can be used in the Sandbox environment. Testing in Production requires real accounts and will incur actual charges.
There is no minimum transaction amount enforced in either environment.
Vault Transaction Issue
We have active partners successfully implementing Payment Facilitator (PF) setups with sub-merchants in both Sandbox and Production.
Before using PF with Maya Vault, merchants must:
Be fully onboarded with Maya, and
Have PF capability explicitly enabled for their account.
Please note that PF support in Maya Vault is currently applicable only to One-Time Payments.
The error code PY0101 indicates that the transaction was declined due to high-risk or suspected fraudulent activity. Reference: Payment Related Errors
Minimum Transaction Amount
There is no minimum transaction amount required across PF-supported solutions.
Ensure that all required PF metadata fields are correctly populated in your requests to avoid validation errors.
PF MID Usage Clarification
The supported solutions and currencies are tied to your Merchant ID (MID) configuration during onboarding.
If you are unsure which capabilities (e.g., PF support, currencies) are enabled, please coordinate with your Maya Relationship Manager for confirmation.
Sub-merchant Setup Flow
Sub-merchants are defined dynamically via API requests as part of the PF metadata.
Only the primary merchant (platform) MID is provisioned during onboarding with Maya.
If referring to non-PF sub-merchants, please clarify the use case so we can provide more targeted guidance.
Industry & MID Mapping
Each MID is configured based on the registered business type and mapped to the appropriate Merchant Category Code (MCC).
Incorrect MCC configuration may result in transaction declines, failed processing, or compliance-related issues.
Ensure that your declared business model and sub-merchant activities align with your configured MCC.
UAT & Production Readiness
For UAT certification and Production go-live, your assigned Maya Relationship Manager will guide you through the required steps and validation process. Reference: Maya Partner Journey
PF Field Definitions (Clarification)
As defined in the API specifications:
pf.mpc: ISO 4217 numeric currency code (e.g., 608 for PHP)
pf.mco: ISO 3166-1 alpha-3 country code (e.g., PHL for the Philippines)
Please note that while the core concepts of PF remain consistent, there are slight nuances across solutions (e.g., Checkout, Vault, Pay with Maya), so it’s important to align your implementation with the specific product you are integrating.
PY0101 – Acquirer decline due to high risk
Current Status (for reference)
successful testing completed
encountering issues