Handle pending payments and asynchronous payment methods

Last updated: July 10, 2026

Handle pending payments and asynchronous payment methods

Some payment methods are not confirmed immediately. While the payment provider is still processing the transaction, the payment status is pending.

How to detect a pending payment

  • Use the public PaymentStatus value pending.

  • Do not treat created as a pending payment.

  • You can observe pending in both webhooks and the public API.

Recommended event flow

  1. User starts checkout - you receive order.created.

  2. User confirms the payment method - you receive payment.pending.

  3. Then one of the following happens:

    • Success: payment.succeeded -> order.paid -> item.add

    • Failure: payment.declined, payment.expired, or payment.voided

    • Post-payment issues: payment.dispute or payment.chargeback

How to track the final result

Webhooks are the primary integration channel. In normal operation, your backend does not need to poll for status changes.

If you suspect that a webhook was missed, or if item.add does not arrive within 10-20 minutes, reconcile the order with GET /s2s/orders/{order_id}.

Webhook delivery is independent of the user's checkout session and is retried for up to about 32 hours.

Checkout behavior during pending state

When a payment enters pending, checkout displays a dedicated processing state. Depending on the payment method, the player sees either:

  • a waiting screen with a processing message, or

  • payment-method-specific instructions such as QR code or step-by-step completion guidance.

The checkout automatically transitions when the provider returns the final result.

Because checkout already handles the pending state, games usually do not need to render a separate in-checkout pending UI.

What to do when the player returns to the game

A player can leave the checkout page and return to the game while the payment is still processing. The payment continues on our side even if the checkout tab is closed.

Recommended game logic:

  1. When the player returns to the game, temporarily block the screen for up to 5 seconds.

  2. Check whether the item.add webhook has already arrived.

  3. If item.add has arrived, unlock the screen and grant/show the purchased items.

  4. If item.add has not arrived yet, unlock the screen. The payment may still complete later.

Testing pending flows

Sandbox currently supports test cards only and does not provide a built-in way to simulate an asynchronous delay.

For real-world testing, some payment methods can naturally remain pending while the player is completing the method-specific step. For example, a QR-based flow such as LINE Pay can remain pending while the QR code is displayed and not yet completed.

How long pending payments usually take

Completion time depends on the payment method.

Credit Cards / Apple Pay / Google Pay

  • Median: 3 seconds

  • P90: 4 seconds

  • P95: 6 seconds

  • P99: 37 seconds

Other payment methods

  • Median: 20 seconds

  • P90: 63 seconds

  • P95: 91 seconds

  • P99: 4.4 minutes

Expiration time also varies by payment method.

Can a player start another payment while one is pending?

A player cannot initiate another payment from the same checkout URL while there is already a payment in the pending state.

However, the player can still make another payment by opening a new checkout link, which means creating a new order.

Summary

  • Use pending as the server-side signal for delayed confirmation.

  • Do not infer pending from created.

  • Rely on webhooks, especially payment.pending and item.add, to drive fulfillment.

  • Expect timing and expiration behavior to vary by payment method.