mom-factura-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mom Factura Testing & QA

Mom Factura 测试与QA

Test payment integrations without processing real transactions.

Base URL:

https://api.momenu.online

无需处理真实交易即可测试支付集成。

Base URL:

https://api.momenu.online

Enable QA Mode

启用QA模式

Add header

x-env-qa: true

to use the test environment. Works from any origin.

For local development, also add

x-dev-mode: true

(localhost/127.0.0.1 only).

Content-Type: application/json
x-api-key: YOUR_API_KEY
x-env-qa: true
x-dev-mode: true

添加请求头

x-env-qa: true

即可使用测试环境，支持任意来源访问。

对于本地开发，还需添加

x-dev-mode: true

（仅适用于localhost/127.0.0.1）。

Content-Type: application/json
x-api-key: YOUR_API_KEY
x-env-qa: true
x-dev-mode: true

Simulate Payment Results

模拟支付结果

The

simulateResult

field in the MCX endpoint body triggers specific scenarios. Only active when

x-env-qa: true

Value	Behavior
`success`	Payment succeeds, returns transactionId and invoiceUrl
`insufficient_balance`	Fails: client has no balance
`timeout`	Fails: no response from provider
`rejected`	Fails: payment explicitly rejected
`invalid_number`	Fails: phone not registered

Internal test phone mapping (automatic, no action needed):

success → 244900000000
insufficient_balance → 244900000001
timeout → 244900000002
rejected → 244900000003
invalid_number → 244999999999

MCX接口请求体中的

simulateResult

字段可触发特定场景，仅当

x-env-qa: true

时生效。

取值	行为
`success`	支付成功，返回transactionId和invoiceUrl
`insufficient_balance`	支付失败：客户余额不足
`timeout`	支付失败：未收到服务商响应
`rejected`	支付失败：支付请求被明确拒绝
`invalid_number`	支付失败：手机号未注册

内部测试手机号映射（自动生效，无需手动操作）：

success → 244900000000
insufficient_balance → 244900000001
timeout → 244900000002
rejected → 244900000003
invalid_number → 244999999999

Test Examples

测试示例

Successful MCX Payment

成功的MCX支付

bash

curl -X POST https://api.momenu.online/api/payment/mcx \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-env-qa: true" \
  -d '{"paymentInfo":{"amount":1000,"phoneNumber":"244923456789"},"simulateResult":"success"}'

bash

curl -X POST https://api.momenu.online/api/payment/mcx \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-env-qa: true" \
  -d '{"paymentInfo":{"amount":1000,"phoneNumber":"244923456789"},"simulateResult":"success"}'

Insufficient Balance

余额不足场景

bash

curl -X POST https://api.momenu.online/api/payment/mcx \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-env-qa: true" \
  -d '{"paymentInfo":{"amount":5000,"phoneNumber":"244923456789"},"simulateResult":"insufficient_balance"}'

bash

curl -X POST https://api.momenu.online/api/payment/mcx \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-env-qa: true" \
  -d '{"paymentInfo":{"amount":5000,"phoneNumber":"244923456789"},"simulateResult":"insufficient_balance"}'

Amount Validation Error

金额验证错误场景

bash

curl -X POST https://api.momenu.online/api/payment/mcx \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-env-qa: true" \
  -d '{"paymentInfo":{"amount":2500,"phoneNumber":"244923456789"},"products":[{"id":"1","productName":"P","productPrice":3000,"productQuantity":1}],"simulateResult":"success"}'

Returns:

{ "success": false, "code": "AMOUNT_MISMATCH" }

bash

curl -X POST https://api.momenu.online/api/payment/mcx \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-env-qa: true" \
  -d '{"paymentInfo":{"amount":2500,"phoneNumber":"244923456789"},"products":[{"id":"1","productName":"P","productPrice":3000,"productQuantity":1}],"simulateResult":"success"}'

返回结果：

{ "success": false, "code": "AMOUNT_MISMATCH" }

E-kwanza in QA (no simulateResult support)

QA环境下的E-kwanza支付（不支持simulateResult）

bash

curl -X POST https://api.momenu.online/api/payment/ekwanza \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-env-qa: true" \
  -d '{"paymentInfo":{"amount":2000,"phoneNumber":"244923456789"}}'

bash

curl -X POST https://api.momenu.online/api/payment/ekwanza \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-env-qa: true" \
  -d '{"paymentInfo":{"amount":2000,"phoneNumber":"244923456789"}}'

Reference in QA

QA环境下的Reference支付

bash

curl -X POST https://api.momenu.online/api/payment/reference \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-env-qa: true" \
  -d '{"paymentInfo":{"amount":10000}}'

bash

curl -X POST https://api.momenu.online/api/payment/reference \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-env-qa: true" \
  -d '{"paymentInfo":{"amount":10000}}'

Test Helpers

测试辅助工具

JavaScript

javascript

const API = "https://api.momenu.online";
const headers = {
  "Content-Type": "application/json",
  "x-api-key": "YOUR_API_KEY",
  "x-env-qa": "true"
};

async function testMCX(simulateResult = "success") {
  const res = await fetch(`${API}/api/payment/mcx`, {
    method: "POST", headers,
    body: JSON.stringify({
      paymentInfo: { amount: 1000, phoneNumber: "244923456789" },
      simulateResult
    })
  });
  return res.json();
}

// Run all scenarios
for (const s of ["success","insufficient_balance","timeout","rejected","invalid_number"]) {
  testMCX(s).then(r => console.log(s, r.success ? "PASS" : "FAIL", r));
}

javascript

const API = "https://api.momenu.online";
const headers = {
  "Content-Type": "application/json",
  "x-api-key": "YOUR_API_KEY",
  "x-env-qa": "true"
};

async function testMCX(simulateResult = "success") {
  const res = await fetch(`${API}/api/payment/mcx`, {
    method: "POST", headers,
    body: JSON.stringify({
      paymentInfo: { amount: 1000, phoneNumber: "244923456789" },
      simulateResult
    })
  });
  return res.json();
}

// 运行所有场景
for (const s of ["success","insufficient_balance","timeout","rejected","invalid_number"]) {
  testMCX(s).then(r => console.log(s, r.success ? "PASS" : "FAIL", r));
}

Python

python

import requests

API = "https://api.momenu.online"
headers = {"Content-Type": "application/json", "x-api-key": "YOUR_API_KEY", "x-env-qa": "true"}

def test_mcx(simulate="success"):
    r = requests.post(f"{API}/api/payment/mcx", json={
        "paymentInfo": {"amount": 1000, "phoneNumber": "244923456789"},
        "simulateResult": simulate
    }, headers=headers)
    return r.json()

for s in ["success", "insufficient_balance", "timeout", "rejected", "invalid_number"]:
    result = test_mcx(s)
    print(f"{s}: {'PASS' if result.get('success') else 'FAIL'} - {result}")

python

import requests

API = "https://api.momenu.online"
headers = {"Content-Type": "application/json", "x-api-key": "YOUR_API_KEY", "x-env-qa": "true"}

def test_mcx(simulate="success"):
    r = requests.post(f"{API}/api/payment/mcx", json={
        "paymentInfo": {"amount": 1000, "phoneNumber": "244923456789"},
        "simulateResult": simulate
    }, headers=headers)
    return r.json()

for s in ["success", "insufficient_balance", "timeout", "rejected", "invalid_number"]:
    result = test_mcx(s)
    print(f"{s}: {'PASS' if result.get('success') else 'FAIL'} - {result}")

Common Issues

常见问题

Error	Cause	Fix
DOMAIN_NOT_ALLOWED	Origin not registered	Add `x-dev-mode: true` (localhost) or register domain
MISSING_API_KEY	Header missing	Check header is `x-api-key` (lowercase, hyphens)
AMOUNT_MISMATCH	amount != products total	Verify SUM(price*qty) == amount, or send only one
MISSING_PHONE	No phone for MCX/E-kwanza	Add `paymentInfo.phoneNumber` (not needed for Reference)
simulateResult ignored	Not in QA mode	Add header `x-env-qa: true`
simulateResult ignored	Wrong endpoint	Only works on MCX, not E-kwanza or Reference

错误码	原因	解决方法
DOMAIN_NOT_ALLOWED	来源域名未注册	添加 `x-dev-mode: true` （仅本地localhost）或注册域名
MISSING_API_KEY	缺少请求头	检查请求头是否为 `x-api-key` （全小写，连字符格式）
AMOUNT_MISMATCH	金额与商品总价不匹配	验证SUM(单价*数量)是否等于总金额，或仅传递其中一项
MISSING_PHONE	MCX/E-kwanza支付缺少手机号	添加 `paymentInfo.phoneNumber` （Reference支付无需此字段）
simulateResult未生效	未启用QA模式	添加请求头 `x-env-qa: true`
simulateResult未生效	接口不支持	仅MCX接口支持该字段，E-kwanza和Reference接口不支持

Pre-Production Checklist

上线前检查清单

Remove
```
x-env-qa: true
```
header
Remove
```
x-dev-mode: true
```
header
Remove
```
simulateResult
```
from request bodies
Register production domain in merchant panel
Store API key in environment variables (never hardcode)
Implement error handling for all error codes
Implement webhook endpoint to receive payment confirmations
Implement status endpoint fallback for E-kwanza and Reference
Verify amount validation with products
Test with real phone numbers

移除
```
x-env-qa: true
```
请求头
移除
```
x-dev-mode: true
```
请求头
从请求体中移除
```
simulateResult
```
字段
在商户面板中注册生产环境域名
将API密钥存储在环境变量中（切勿硬编码）
为所有错误码实现错误处理逻辑
实现webhook接口以接收支付确认通知
为E-kwanza和Reference支付实现状态查询接口降级方案
验证含商品信息的金额校验逻辑
使用真实手机号进行测试