Why a payment completes only on confirmed receipt
The “I've paid” button, the review queue and what your purchase flow should do while a payment is pending.
On the MaruPay payment screen, a user follows the instructions and submits the payment. It would be easy to call the payment done at that moment. We don't, and your integration shouldn't either.
Submitting isn't paying
A submitted payment is a claim. Users mistype, abandon halfway or press the button twice. If an order were credited on submission, every one of those cases would become a support ticket and a manual correction. So a MaruPay payment stays pending until receipt is actually confirmed on our side.
Exactly one request, or review
A confirmed receipt completes a payment only when it matches exactly one open payment request. When it matches none, or two requests fit equally well, it goes to the review queue instead. An operator looks at the evidence and attaches it to the right payment, and only then is payment.completed sent.
- No matching request: the receipt waits in review; nothing is sent to you.
- Two or more matching requests: held until an operator picks the right one.
- Receipt after the request expired: held for review rather than completing an expired order.
What your purchase flow should do
- Credit the order on payment.completed, and only there. The return URL tells you the user came back, not that the payment completed.
- While pending, show the user a clear waiting state. The payment screen does the same.
- Release the order on payment.expired.
- If you need certainty, read the payment's status with GET /v1/payments/{id}.
The result is slower by a few seconds in the common case and much calmer in every other case: the median time from submission to confirmed receipt across merchants is 38 seconds, and the tickets that start with “I paid but nothing happened” mostly go away.