Worked timeout choice
A transfer request with operation ID P-10 times out after the provider may have accepted it. The safe flow is to query P-10 or await a verified event, then compare the provider state with the ledger. Starting P-11 as a blind retry can send money twice. By contrast, a validation error that rejects malformed input before processing can be corrected under the provider’s request-key rule while retaining the customer intent link. These examples are general. Use the provider’s exact error contract to decide whether it guarantees a request was never accepted.
Choose a safe next action
A validation error needs corrected input. An authentication error needs credential repair. A decline is usually final for that attempt. A rate limit can be retried only after the provider’s stated window. An unknown timeout needs a status lookup first.
Checks to run
- Separate validation failure, authentication failure, decline, rate limit, timeout, and unknown result.
- Retry only when the provider documents that behavior and the operation is idempotent.
- For an unknown result, check provider status and ledger state before showing a final outcome.
State before retry
If the provider clearly rejects a request before accepting it, a corrected request can follow the provider’s documented key rule. If the result is unknown, query the original operation. If the provider accepted it and later declined, follow the documented decline path. These cases need different customer messages.
Build the mapping from each provider’s current public docs and test it in a sandbox. Do not infer that every 500 status is safe to retry; a server may fail after committing the money move.
Route a timeout safely
Suppose a transfer call for reference R-01 times out after five seconds. Put R-01 in pending, call the provider’s status endpoint with that reference, and show the customer that the result is still being checked. If the provider confirms success, close R-01 once. If it confirms failure, release the reservation once. If it remains unknown, keep R-01 pending and set an escalation time. Do not issue R-02 for the same intent. Paystack offers transfer verification by reference, and its error guide explains why an HTTP response alone is not the payment state.
Separate request identity from provider acceptance
A validation failure can keep the same customer intent while a corrected provider request uses the key required by that provider. Do not reuse an idempotency key with changed parameters when the provider rejects that use. A rate-limit response also needs a known acceptance state before retry: waiting for a backoff window alone does not prove that no payment was created. For P-10, save the original reference and query its status until a final result or an owned escalation. If a provider lookup returns not found, check its documented consistency and retry rules before treating that as final failure. Keep the map scoped to one API version.
Primary sources
Next step
Map the timeout code from one payment provider to a status lookup and a plain customer message. Read the related guide. For a review of your own system, request a security review.