Common Error Reporting and Troubleshooting in Philippine Payment Systems

Common Error Codes and Meanings

1. E100 - Transaction timeout

   • Reason: unstable internet connection or slow response from bank/payment gateway
   • Solution: Check the network connection and retry later; confirm that the communication between the merchant server and the payment gateway is normal.

2. E201 - Insufficient balance

   • Reason: Insufficient funds in the user's account to complete the transaction
   • Solution: Prompt the user to top up or change the payment method

3. E202 - Exceeding Single Limit

   • Reason: Transaction amount exceeds the single transaction limit set by the bank/e-wallet
   • Solution: Advise users to make multiple small payments or contact the card issuer to increase the limit.

4. E301/OMP_0010_01 (GCash-specific)

   • "Transaction failed due to insufficient funds or exceeded limit"
   • GCash wallet balance is insufficient or reaches the daily limit (usually ₱50,000)

5. BPI Error Code: BPI-9999

   • "General error", contact BPI customer service for specific information.

6. PayMaya Error: PMY-4001
   Authentication failure, usually invalid or expired API key

Frequently asked questions about cash payments at OTC counters (e.g. Dragonpay, 7-Eleven CLiQQ, etc.)

1. Invalid/expired reference number
   Each OTC transaction has a 24-hour validity period, after which the order has to be regenerated.

2. Payment made but status not updated
   Typically takes 15 minutes to 2 hours to process; if not updated in more than 4 hours contact the payment provider and provide a photo of the receipt as proof

3.Amount mismatch
Ensure that the amount paid by the customer is accurate to two decimal places (PHP), any discrepancy will result in failure

PCI DSS Compliance Related Errors (for online credit card processing)

1.3DS authentication failed(Mastercard SecureCode/VBV Verification)
May be locked multiple times due to cardholders entering OTP incorrectly

2.AVS address checksum mismatch(particularly affecting the use of international cards in the Philippines)
It is recommended to disable AVS checksums or add the "Ignore AVS" option to the system.

Troubleshooting Steps for API Integration Classes.

1️⃣ test environment:

curl --location --request POST 'https://api.sandbox.paymentprovider.ph/v3/payments' \

--header 'Authorisation: Bearer YOUR_API_KEY' \

--header 'Content-Type: application/json' \

--data-raw '{

 "amount": "1000",

 "currency": "PHP",

 ...

}'

2️⃣ Production environment checklist:

• ✅ SSL certificates valid and PCI compliant (TLS ≥1.2)
• ✅ Your server IP has been added to the IP whitelist
• ✅ Webhook endpoint is publicly accessible and returns a 200 status code
• ✅ PHP environmentallow_url_fopen=On(if applicable)

Bangko Sentral ng Pilipinas (BSP) Regulatory Requirements Notes.

⚠️ A full log of all failed financial transactions must be kept for at least 5 years
⚠️ Repeated authentication failures for the same user may trigger AMLC AML review
⚠️ Failure due to maintenance period: BSP mandates a mandatory settlement window of 03:00-05:00am every Sunday morning.

If further assistance is required, it is recommended that it be provided:
🔹 Full Error Code + Subcode
🔹 Occurrence timestamp (includes time zone GMT+8)
🔹 Whether cross-currency settlement is involved

Guidelines for in-depth troubleshooting of payment systems in the Philippines (continued)

Errors specific to bank transfer type transactions

1. InstaPay/PESONet Error Classification

   • IP-102 (InstaPay)
     "Beneficiary account not found"
     Solution:

     • Verify recipient account number + bank code combination
     • Note that some banks require a 12-digit account number to be entered (e.g. BPI), even if the customer normally uses a 10-digit

   • PN-209 (PESONet)
     "Transaction exceeds cutoff time"
     Clearing deadlines vary by bank:

     timeline
     
         title Example of PESONet's same day arrival cut-off time
     
         2023-01-01 : bdo: 14:30 
     
         2023-01-01 : Metrobank: 15:00
     
         2023-01-01 : Landbank: 16:00
     
     

2. Repeat transaction detection
   The Philippine financial system triggers windfall controls for consecutive transactions of the same amount:

   • InstaPay: ₱10,000+ transactions from the same payee in 5 minutes automatically pending review
   • PESONet: ±₱0.50 difference in the same batch can circumvent repeat testing

GCash/e-wallet advanced troubleshooting

1. Errors specific to enterprise accounts

   Error code: G-XMP_3004_62  
   
   Meaning: "Monthly corporate wallet limit reached"
   
   

   The default monthly limit for Corporate GCash account is ₱500,000, advance application for withdrawal is required by submitting.

   • SEC Certificate of Registration
   • BIR2303 Tax registration

2. Biometric verification failed
   When theauth_biomedical_factoryTime:

   # GCash official suggested retry logic (pseudo code)
   
   
   
       if error == AUTH_BIOMETRIC_FAILURE.
   
           wait(minutes=5) 
   
           if retry_count <2.
   
               trigger_SMS_OTP_fallback()
   
           else.
   
               lock_account_for(24h)
   
   
   
       Applicable to vivo/Y series mobile phone users need to pay special attention to the light conditions    
   
       ```
   
   
   
   

QR Ph Standard Payment Issues

1. Dynamic QR code failure
   The Central Bank of the Philippines requires that QR Ph dynamic codes must contain the following elements to be valid:

2. Common reasons for scanning failures on the consumer side

# POS terminal configuration checklist:



+ [ ] QR generates pixel density ≥ 300 dpi  

+ [ ] PNG format instead of JPEG  

! [ ] PSP Merchant ID certified by BSP (not a test MID)  

Bangko Sentral Regulatory Sandbox Considerations

When testing innovative payment solutions:

1️⃣ Simulation of environment-specific parameters::

Headers must contain.

X-BSP-Sandbox: true  

X-Test-Case-ID: {pre-approved test case number}

2️⃣ Stress Test Limitations::
⚠️ prohibits running bulk tests after 4pm on Friday (conflicts with weekly billing)

If real-time diagnosis of complex cases is required, it is recommended that this process be reported:

A [collect original request] --> B {does it contain sensitive data?}    

B --> |Yes| C [encrypted with OpenSSL]     

B --> |No| D [Direct Attach Log]     

C & D --> E [compressed to ZIP and password protected]      

E --> F [transmitted via BSP SecureUpload]

Ongoing monitoring suggested tool combination: FTS Monitor from Splunk + BSP (free version supports real-time analysis of 5 transactions per second).

Expert-level troubleshooting manual for Philippine payment systems (continued)

Cross-border payment special scenario processing

1. SWIFT-specific errors

   • BSP-REMIT-004: Deduction of intermediary bank charges
     impunity: The amount actually received by the payee is less than the amount sent15-50
     prescription::

     # Algorithmic logic for computing optimal remittance paths
     
     def calculate_optimal_route(sender_bank, receiver_bank).
     
         if sender_bank in ['BPI', 'BDO'] and receiver_bank in ['Chinabank', 'RCBC']:: if sender_bank in ['BPI', 'BDO'] and receiver_bank in ['Chinabank', 'RCBC'].
     
             return 'Use an in-country transit network instead of SWIFT'
     
         else.
     
             return f "Explicitly inform the user that a {max(15, amount*0.01)} USD handling fee will be deducted"
     
     

2. Cryptocurrency exchange channel restrictions
   In accordance with BSP Circular No. 1108:

   • Additional KYC steps to be completed for ₱500,000+ transactions
   • common errorCRYPTO_KYC_TIER2_REQUIREDTrigger Condition:

POS terminal hardware troubleshooting

1. Ingenico/Landbank Equipment Specific Code List

Example of reading logs under # Linux system (requires root privileges)

sudo cat /var/log/payment-terminal/$(date +%Y-%m-%d).log | grep "E_" 

Common hardware error countermeasures:

2. Thermal printer communication protocol conflict
   Appears when connecting Bluetooth and USB at the same timePRINTER_BUSYError:

   sequenceDiagram
   
       Terminal->>Printer: USB command to print receipt A
   
       Mobile App->>Printer: Bluetooth command to print promotional content B
   
       Printer-->>Terminal: BUSY_ERROR (0x7F)
   
       The correct process should lock the interface with the AT command:.
   
       AT+CLAIM=USB 
   
   

BSP Real Time Gross Settlement System (RTGS) Operations and Maintenance Window

1. Enhanced Monitoring Recommendations for Mandatory Maintenance Periods
   Deployment is recommended every Sunday during 03:00-05:00 GMT+8:

#!/bin/bash

# RTGS Maintenance Period Heartbeat Detection Script Sample



while maintenance_window_active; do

  

curl -X POST "https://bsp-monitor.ph/api/v1/ping" \

-H "Authorisation:Bearer $(cat /etc/bsp/api.key)" \ 

--data-raw '{"component": "RTGS", "region": "MANILA"}'



if [ $? ! =0 ]; then    

escalate_to_oncall_engineer --priority=P0   

fi  



sleep300  

done >> /var/log/rtgs_monitor.log  

2. Disaster recovery protocol trigger conditions

The following events automatically activate the BCP profile:
✅ InstaPay Failure Rate for 30 consecutive minutes >15%
✅ PESONet batch file processing delay ≥ 90 minutes
✅ QR Ph master certificate expired (renewed every 2 years)

AI-driven intelligent troubleshooting tool recommendations

A dedicated diagnostic programme developed locally in the Philippines:

1.GCash Einstein(Business Merchants Only) Features include:
-Predictive limit management (based on historical transaction patterns)
-Voice IVR auto-generated work orders (support Tagalog mixed English)

// Example API response (AI analysis results)

{

"error_code": "G-XMP_3004_62".

"suggested_action": {

"immediate": ["Switch to alternate clearing channel"],

"long_term": ["Submission of Business Validation Materials for Limit Increase"]

},

confidence_score:92%

}

For further debugging of complex cases, the BSP Technical Support Group can be contacted in any of the following ways:

📞Emergency Hotline: (02) 8708-7087 (24/7 available)
✉️ encrypted mailbox:[email protected] (PGP Key ID: BSP2023-SOC)