A timeout is not a failure

说明与用途

在 MTN MoMo 集成中，超时被视为 UNKNOWN 并重试，直到获得最终响应，避免错误失败和财务损失。

问题

When MTN Mobile Money’s API does not return a callback, developers mistakenly treat a timeout as a failed transaction, leading to incorrect ledger entries and financial loss.

结果

By treating timeouts as UNKNOWN and implementing idempotent callbacks, the gateway avoids false failure marking, reduces financial risk, and improves reconciliation reliability.

工作流

• 1. Register a providerCallbackHost with MTN API user. 2. Send payment request with X-Callback-Url header. 3. If MTN does not call back, treat the request as UNKNOWN, not FAILED. 4. Reconciler polls MTN for status until a terminal state is returned. 5. If status remains UNKNOWN beyond configured window, escalates to human review. 6. Record final status only after conclusive response.
• 7. Ensure callback endpoint is idempotent to handle retries.
• 8. Map MTN response codes to internal status, prioritizing status over reason field.

证据

Registering it does not cause MTN to call you. It only constrains where a supplied X-Callback-Url is permitted to point.

来源

MTN retries a delivery you already answered. The third submission's callback arrived twice…

来源

A payment was accepted — 202, CREATED → SUBMITTED. MTN then answered every status query with status: FAILED, reason: INTERNAL_PROCESSING_ERROR.

来源