Skip to main content

Payment failures

APIO automatically attempts to charge active subscriptions on the date calculated by the Payday configuration.

If a payment attempt fails, APIO applies configurable retry and suspension rules to balance successful recovery with a good customer experience.

Initial Charge Attempt​

For each active subscription:

  • APIO attempts to charge the subscription on the scheduled payday
  • The payment processor is selected according to the subscription configuration (Currently only Webpay Oneclick)
  • The result of the attempt determines the next action

If the payment is successful, the subscription continues normally until the next billing cycle.

Retry Strategy​

When a payment attempt fails, APIO does not retry immediately by default.

Instead, APIO supports configurable retry strategies, including:

  • Grace periods between retries
    Define the number of days to wait before attempting the next charge

  • Maximum retry attempts
    Limit how many times APIO will attempt to recover a failed payment

This prevents excessive or aggressive charging attempts that could negatively impact customers.

Retry Delay Between Charges​

You can configure a delay in days between retry attempts.

Example:

  • Payday: March 15
  • First charge attempt fails
  • Retry delay: 3 days
  • Next attempt: March 18

This behavior is useful when:

  • Customers need time to resolve balance issues
  • Bank or card failures are temporary
  • You want to avoid immediate repeated failures

Subscription Suspension​

If a payment fails repeatedly and exceeds the configured retry limits, the subscription transitions to a suspended state.

When a subscription is suspended:

  • No further automatic charge attempts are made
  • The subscription remains inactive but not canceled
  • Manual intervention or customer action is required to resume billing

Suspension helps prevent infinite retry loops and protects both merchants and customers from unnecessary charges.

Resuming a Suspended Subscription​

A suspended subscription can be resumed by:

  • Successfully processing a manual payment

Once resumed, APIO recalculates the next payday according to the billing cycle rules.

Best Practices​

  • Configure reasonable retry delays between attempts
  • Notify customers after failed payment attempts
  • Use suspension to avoid continuous failed charges
  • Provide a clear path for customers to recover suspended subscriptions

APIO’s payment failure handling ensures reliable billing while maintaining a respectful and predictable retry process.