Timing Requirements
This is the most important operational requirement for partner wallets. Read it before you build the hold logic.
The Rule
Your wallet holds must stay valid for longer than 22.5 minutes. Pagamio recommends 30 minutes or more.
If your holds expire sooner, a purchase whose outcome is briefly unknown can end with a capture against a hold that no longer exists. That purchase cannot be settled automatically, and it must be resolved by hand by Pagamio operations.
Why
Most purchases finish in seconds: Pagamio buys the product, then captures or releases your hold straight away. Occasionally the product provider does not answer, and Pagamio cannot yet tell whether the customer received the product. In that case Pagamio does not guess. It treats the purchase as pending and reads the outcome back from its own records, repeatedly, for a window of up to 20 minutes (the indeterminate-cutoff). It never re-sends the purchase, because that could deliver the product twice.
Only once the outcome is known does Pagamio capture (product delivered) or release (product not delivered). That decision can come as late as the end of the window, and the wallet call still has to succeed after it.
The Arithmetic
The hold must outlast every step that can happen before the final wallet call:
| Component | Default | Notes |
|---|---|---|
| Wait for the product provider to answer | 1 minute | Core read timeout (60 seconds). |
| Pending window for an unknown outcome | 20 minutes | indeterminate-cutoff. |
| First two capture retries | 1 minute 30 seconds | Retry delays of 30 seconds, then 1 minute. |
| Minimum hold lifetime | 22 minutes 30 seconds | The hold TTL must be strictly greater than this. |
hold TTL > core read timeout + indeterminate cutoff + first two retry delays
hold TTL > 1 min + 20 min + 1.5 min = 22.5 min
Pagamio checks this at start-up for every configured partner and refuses to enable a partner whose declared hold lifetime does not exceed the total. The standard contract assumes a 30-minute hold unless you declare otherwise.
What Happens If The Window Runs Out
When a purchase is still unresolved at the end of the window, Pagamio marks it escalated with a timeout reason. The customer is told "We could not confirm the purchase. Please check your history later.", and Pagamio operations resolve the leg manually as either captured or released, in agreement with the provider's record. The pending window is also capped at your declared hold lifetime minus 2 minutes, so a short hold shortens the window rather than being outlived.
Special Timings
If your platform cannot keep holds valid for 22.5 minutes, you can request special timings. Pagamio can shorten the pending window for your partner code; the wallet call schedule is unchanged.
- A shorter window is applied as a per-partner override. It can only shorten the default, never lengthen it.
- Requests are subject to Pagamio approval. The trade-off is that a shorter window gives fewer chances for a slow provider to answer, so more purchases end up escalated for manual resolution.
- Keep the same rule with your new window: hold TTL > 1 minute + new window + 1.5 minutes.
For example, holds that last 10 minutes could support a pending window of 5 minutes (1 + 5 + 1.5 = 7.5 minutes, below 10). Ask your Pagamio contact and include your hold lifetime, your reasoning and your expected daily volume.
Checklist
- Hold lifetime is 30 minutes or more (and never below 22.5 minutes).
- The hold is not released by any of your own jobs while a purchase may still be pending (for example, an auto-release on inactivity shorter than the lifetime above).
- Capture and release are idempotent by reference.
- Your wallet API is available for at least the hold lifetime after each hold (so retried captures succeed).
Last updated: September 2026