Transaction lifecycle

A purchase is asynchronous: Aura accepts it at once, then waits for the network to confirm the credit. Every purchase reaches a final state by its resolve_by time.

States

State	What it means	Your balance	Final?
pending	Accepted and sent to the network. Waiting for its confirmation.	The price is held.	No
successful	The network confirmed the bundle was credited to the number.	Charged.	Yes, unless reversed
failed	The bundle was not credited. failure.code says why.	Not charged. The hold is released.	Yes
reversed	The network reversed a credit after confirming it. Rare.	Refunded.	Yes

New states will not be added in v1.

Pending and resolve_by

Most purchases leave pending quickly, but a network can be slow to confirm. Every purchase carries resolve_by, the latest time it will reach a final state. If the network has not confirmed by then, Aura ends the purchase as failed with network_timeout and releases the hold.

So you never need your own timeout for a pending purchase. Wait for the webhook, and if none arrives by resolve_by, look the purchase up: it will be final.

A network’s current confirmation times are in its recent_delivery field. See Networks and bundles.

Why a purchase fails

failure.code	Meaning	Worth retrying?
network_rejected	The network refused the purchase.	Yes, later, with a new reference.
number_not_eligible	The network will not credit this bundle to this number.	No. Offer another bundle.
bundle_unavailable	The bundle was withdrawn after you bought it.	With another bundle, using a new reference.
network_timeout	The network did not confirm by resolve_by.	Yes, with a new reference.
internal_error	Aura could not complete the purchase.	Yes, with a new reference.

A failed purchase is final, so a retry is a new purchase and needs a new reference. New failure codes may be added in v1; treat an unknown code as not worth retrying automatically.

Reversals

Very occasionally a network reverses a credit it already confirmed. Aura then moves the purchase to reversed, refunds the price to your balance, and sends purchase.reversed. Decide in advance what your product does for the customer in that case, for example re-crediting them with a new purchase.