菲律宾支付系统常见报错与排查方法

常见错误代码及含义

E100 – 交易超时
- 原因：网络连接不稳定或银行/支付网关响应慢
- 解决方案：检查网络连接，稍后重试；确认商户端服务器与支付网关通信正常
E201 – 余额不足
- 原因：用户账户资金不足以完成交易
- 解决方案：提示用户充值或更换支付方式
E202 – 超出单笔限额
- 原因：交易金额超过银行/电子钱包设定的单笔上限
- 解决方案：建议用户分多笔小额支付或联系发卡行提高限额
E301/OMP_0010_01 (GCash特有)
- "Transaction failed due to insufficient funds or exceeded limit"
- GCash钱包余额不足或达到日限额(通常为₱50,000)
BPI错误码: BPI-9999
- "General error"通用错误，需联系BPI客服获取具体信息
PayMaya错误: PMY-4001
认证失败，通常是API密钥无效或过期

OTC柜台现金支付的常见问题(如Dragonpay、7-Eleven CLiQQ等)

参考号无效/过期
每笔OTC交易有24小时有效期，超时需重新生成订单
已付款但状态未更新
通常需要15分钟至2小时处理时间；若超过4小时未更新应联系支付提供商并提供收据照片作为证明

3.金额不匹配
确保客户支付的金额精确到小数点后两位(PHP)，任何差异都会导致失败

PCI DSS合规性相关报错(适用于在线信用卡处理)

1.3DS验证失败(Mastercard SecureCode/VBV验证)
可能因持卡人输入OTP错误多次被锁定

2.AVS地址校验不匹配(特别影响国际卡在菲使用)
建议关闭AVS校验或在系统中添加"忽略AVS"选项

API集成类问题排查步骤:

1️⃣ test environment:

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

--header 'Authorization: Bearer YOUR_API_KEY' \

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

--data-raw '{

 "amount": "1000",

 "currency": "PHP",

 ...

}'

2️⃣ 生产环境检查清单:

✅ SSL证书有效且符合PCI标准(TLS ≥1.2)
✅ IP白名单中已添加您的服务器IP
✅ Webhook端点可公开访问且返回200状态码
✅ PHP环境下allow_url_fopen=On(如适用)

Bangko Sentral ng Pilipinas(BSP)监管要求注意事项:

⚠️所有失败的金融交易必须保留完整日志至少5年
⚠️重复出现同一用户的验证失败可能触发AMLC反洗钱审查
⚠️维护期导致的失败:BSP规定每周日凌晨03:00-05:00为强制结算窗口时段

如需进一步协助，建议提供：
🔹完整错误代码+子代码
🔹发生时间戳(包含时区GMT+8)
🔹是否涉及跨币种结算

菲律宾支付系统深度排查指南（续）

银行转账类交易特有错误

InstaPay/PESONet报错分类
- IP-102 (InstaPay)
  "Beneficiary account not found"
  Solution:
  - 核对接收方账号+银行代码组合
  - 注意部分银行要求输入12位账户号（如BPI），即使客户通常使用10位
- PN-209 (PESONet)
  "Transaction exceeds cutoff time"
  各银行清算截止时间不同：
```
timeline

    title PESONet当日到账截止时间示例

    2023-01-01 : BDO: 14:30 

    2023-01-01 : Metrobank: 15:00

    2023-01-01 : Landbank: 16:00
```
重复交易检测
菲律宾金融系统对相同金额的连续交易会触发风控：
- InstaPay：5分钟内相同收款方的₱10,000+交易自动挂起审核
- PESONet：同批次中出现±₱0.50差异可规避重复检测

GCash/电子钱包高级排错

企业账户特有错误
```
错误码：G-XMP_3004_62  

含义："Monthly corporate wallet limit reached"
```
企业GCash账户默认月限额为₱500,000，需提前申请提额需提交:
- SEC注册证书
- BIR2303税务登记

生物识别验证失败
当出现AUTH_BIOMETRIC_FAILURE时：

# GCash官方建议的重试逻辑(伪代码)



    if error == AUTH_BIOMETRIC_FAILURE:

        wait(minutes=5) 

        if retry_count <2:

            trigger_SMS_OTP_fallback()

        else.

            lock_account_for(24h)



    适用于vivo/Y系列手机用户需特别注意光线条件    

    ```

QR Ph标准支付问题

动态二维码失效
菲律宾央行规定QR Ph动态码必须包含以下要素才有效：

field	示例值	OBR必填
CRC	SHA256("MERCHANT_ID+TXID")	✓
validUntil	ISO8601格式(马尼拉时区)	✓

消费者端常见扫描失败原因

# POS终端配置检查清单：



+ [ ] QR生成像素密度≥300dpi  

+ [ ] PNG格式而非JPEG  

! [ ] PSP Merchant ID已通过BSP认证（非测试MID）

Bangko Sentral监管沙盒注意事项

在测试创新支付方案时：

1️⃣ 模拟环境特殊参数::

Headers中必须包含:

X-BSP-Sandbox: true  

X-Test-Case-ID: {预批准的测试场景编号}

2️⃣ 压力测试限制::
⚠️禁止在周五下午4点后运行批量测试（与周结算冲突）

如需实时诊断复杂案例，建议按此流程上报：

A[收集原始请求] --> B{是否含敏感数据?}    

B -->|是| C[用OpenSSL加密]     

B -->|否| D[直接附加日志]     

C & D --> E[压缩为ZIP并密码保护]      

E --> F[通过BSP SecureUpload传送]

持续监控建议工具组合：Splunk + BSP提供的FTS监视器（免费版支持每秒5笔交易的实时分析）。

菲律宾支付系统专家级排错手册（续）

跨境支付特殊场景处理

SWIFT汇款特有错误

BSP-REMIT-004：中间行手续费扣除问题
impunity：收款方实际到账金额比发送金额少15-50
prescription::

# 计算最优汇款路径的算法逻辑

def calculate_optimal_route(sender_bank, receiver_bank):

    if sender_bank in ['BPI', 'BDO'] and receiver_bank in ['Chinabank', 'RCBC']:

        return '使用境内中转网络代替SWIFT'

    else.

        return f"明确告知用户将扣除{max(15, amount*0.01)}美元手续费"

加密货币兑换通道限制
根据BSP Circular No.1108规定：
- ₱500,000以上交易需完成额外KYC步骤
- 常见错误CRYPTO_KYC_TIER2_REQUIRED触发条件：

交易行为	风控阈值
单日累计买入	≥₱200,000
同一卖家连续交易	≥3次/小时

POS终端硬件故障诊断

Ingenico/Landbank设备专用代码表

# Linux系统下读取日志示例（需root权限）

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

常见硬件错误对应措施：

LED状态码	含义	应急方案
🔴🟡交替闪烁(2次)	SIM卡未检测到	拔出重插+拨打*#06#检查ICCID
🟢持续快闪	EMV芯片读取失败	[酒精棉片清洁芯片]→[尝试磁条刷卡]→[手动输入卡号]

热敏打印机通信协议冲突
当同时连接蓝牙和USB时出现的PRINTER_BUSY错误：

sequenceDiagram

    Terminal->>Printer: USB指令打印收据A

    Mobile App->>Printer: Bluetooth指令打印促销内容B

    Printer-->>Terminal: BUSY_ERROR (0x7F)

    正确流程应通过AT命令锁定接口:

    AT+CLAIM=USB

BSP实时结算系统(RTGS)运维窗口

强制维护时段增强监控建议
每周日03:00-05:00 GMT+8期间建议部署：

#!/bin/bash

# RTGS维护期心跳检测脚本样例



while maintenance_window_active; do

  

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

-H "Authorization: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

灾难恢复协议触发条件

以下事件会自动启动BCP预案：
✅ InstaPay连续30分钟失败率>15%
✅ PESONet批量文件处理延迟≥90分钟
✅ QR Ph主证书过期（每两年更新一次）

AI驱动的智能排查工具推荐

菲律宾本土开发的专用诊断方案：

1.GCash Einstein(仅限企业商户)功能包括：
•预测性限额管理（基于历史交易模式）
•语音IVR自动生成工单（支持他加禄语混合英语）

// API响应示例（AI分析结果）

{

"error_code": "G-XMP_3004_62",

"suggested_action": {

"immediate": ["切换至备用结算渠道"],

"long_term": ["提交企业验证材料以提升限额"]

},

confidence_score:92%

}

如需进一步调试复杂案例，可通过以下任一方式联系BSP技术支援组：

📞紧急热线：(02)8708-7087 (24/7可用)
✉️加密邮箱：[email protected] (PGP密钥ID:BSP2023-SOC)

菲律宾支付系统常见报错与排查方法