Payment states

The 11 states

Code	Name	Description	Terminal
NR	Not Ready	Order created without input_currency assigned.	No
PE	Pending	Waiting for the customer to pay.	No
AC	Awaiting Completion	Payment received, waiting for blockchain confirmation. Check safe.	No
IA	Insufficient Amount	Received amount lower than expected.	Yes
CO	Completed	Payment successful, confirmed on-chain. Release the product.	Yes
CM	Completed by Merchant	Completed manually by the merchant.	Yes
CA	Cancelled	Expired after more than 24h without payment.	Yes
EX	Expired	No receipt within 15 or 60 minutes depending on the network.	Yes
OC	Out of Condition	Price moved unfavorably; received amount does not cover the expected value.	Yes
FA	Failed	Transaction unconfirmed or rejected.	Yes
DE	Deleted	Order deleted.	Yes

The safe field

When an order is in AC, the boolean safe field indicates whether the payment has one blockchain confirmation and it is safe to release the product/service.

• safe: false → still in mempool / 0 confirmations. Do not release.
• safe: true → payment is stable, release it.

State diagram

stateDiagram-v2
    [*] --> NR: orden creada sin input_currency
    [*] --> PE: orden creada con input_currency
    NR --> PE: cliente elige moneda
    PE --> AC: se detecta pago en mempool
    PE --> EX: timeout sin recepción (15/60 min)
    PE --> CA: expiración >24h
    AC --> CO: confirmación blockchain
    AC --> OC: importe menor que esperado
    AC --> IA: importe insuficiente
    AC --> FA: fallo de confirmación
    CO --> [*]
    CA --> [*]
    EX --> [*]
    OC --> [*]
    IA --> [*]
    FA --> [*]
    DE --> [*]
    CM --> [*]

Mapping to typical merchant states

B4bit Pay exposes 11 granular states, but most merchants only need ≤4. Recommended mapping:

B4bit Pay state	Merchant state
NR · PE · AC(safe=false)	Pending
CO · AC(safe=true) · CM	Processing (or Paid)
CA · EX	Cancelled
FA · OC · IA	Failed
DE	Deleted

Timeouts

• EX (Expired): triggers after 15 or 60 minutes without receipt, depending on the currency and network.
• CA (Cancelled): after 24 hours without payment.

Tip

To know when a payment expires, check the expired_time field on the Payment schema (ISO 8601 format).

Which states trigger a webhook

Every state change emits a webhook, except IA (insufficient amount), which is sometimes coalesced with the next change. If you need to react to IA, poll GET /orders/info/{identifier} or assume the next webhook carries the final state.

See webhook and webhook-ordering.