Payment fields (Payment schema)

The Payment schema from GET /orders/info/{identifier} returns ~25 fields. Many have obvious names, but others need context. This page clarifies them.

Identification

• identifier (UUID4) — unique payment ID assigned by B4bit Pay. Use it as a foreign key in your system.
• reference (string) — your own internal ID (the one you passed when creating the order). Used for correlation.
• merchant_device_id (int) and merchant_device (string) — ID and name of the device that charged the payment.

State

• status — enum of 11 values (NR, PE, AC, IA, CO, CA, EX, OC, FA, DE, CM). See payment states.
• created_at, edited_at — ISO 8601 UTC timestamps.
• expired_time — when the order expires if not paid (ISO 8601).

Amounts

Caution

All monetary amounts (fiat_amount, received_amount, etc.) in the Payment schema are expressed in USDC, not in the merchant’s fiat currency. The fiat currency the merchant selected when creating the order is reflected in the fiat field, but the numeric values are always the USDC equivalent.

• fiat_amount — amount in USDC equivalent to the expected_output_amount you passed when creating the order (B4bit converts using the rate locked at creation time).
• crypto_amount — total crypto amount required to settle the order.
• unconfirmed_amount — seen in mempool, without blockchain confirmations.
• confirmed_amount — with ≥1 blockchain confirmation.
• received_amount — received amount, also in USDC (confirmed sum converted at the rate).
• percentage — % of crypto_amount already received. Useful for a progress bar in the customer UI.

Currency / network

• currency_id — B4bit Pay granular symbol (for example USDC_POLYGON_NXTB). In the webhook it is called currency, without _id.
• fiat — order’s fiat currency (MXN, EUR, etc.). In the webhook it is called fiat_currency.
• language — gateway language (default ES).

Blockchain

• address — destination address where the customer sends the crypto.
• tag_memo — required TAG / MEMO on XRP / XLM / ALGO. If null, the currency does not require it.
• rbf (boolean) — “Replace By Fee”. Only true on BTC. Indicates that a pending transaction could be replaced by another with a higher fee. Assume the payment is not stable while rbf=true.

Safety flags

• safe (boolean) — the most important field after status. true indicates the payment has enough confirmations to be considered stable. Use it as the signal to release the product/service.
• good_fee (boolean) — indicates whether the incoming transaction’s network fee is adequate. If false, confirmation may take longer.
• balance_based (string) — internal field related to transactions consuming pre-loaded balance. Irrelevant for standard merchants.

Redirect URLs (only on the create response, not on info)

• web_url — URL of the hosted gateway (for Redirect Gateway).
• url_ok, url_ko, url_standby — redirects configured by the merchant.

Notes and metadata

• notes — product/service description.
• internal_data — free-form field you can use for your own metadata (up to 1024 chars).

Transactions

• transactions — array of objects with each detected blockchain transaction:
  • confirmed (boolean)
  • currency
  • amount
  • tx_hash (read-only)
  • block (block number where it was confirmed)
  • created_at

Tip

If a payment ends in OC (Out of Condition) but there are multiple transactions, review each one in transactions to understand whether the customer paid in parts or whether one transaction never confirmed.

The critical fields in short

If you are only going to persist 4 fields, persist:

• identifier — for future lookups.
• status — current state.
• safe — signal of “I can release”.
• edited_at — for deduplicating webhooks and ordering changes.