Payment intents

A payment intent is your request to collect a fiat-denominated amount from a customer. It owns the hosted checkout session, the processor invoice that collects the payment (for live payments, an invoice in the platform’s Bitcart account) and the full state history. Invoices and payment links create payment intents under the hood. Payment intents can be created once your account is activated.

POST/v1/payment-intentslive · after account activation

Creating

Field	Required	Notes
store_id	yes	A store in your organization
amount	yes	Decimal string with at most the currency’s minor digits: "59.90"
currency	yes	EUR, USD, BRL or GBP (the settlement reference)
allowed_networks	no	Leave it out for live payments: they offer every asset the platform accepts, and the field is refused with allowed_networks_unsupported. (Watch-only processing only: a subset of enabled networks with an active wallet for the store)
allowed_methods	no	["crypto"] (default; fiat methods are not available)
merchant_order_id	no	Your reference (≤ 200 chars); searchable
description	no	Shown to the customer (≤ 500 chars)
customer.email / customer.reference	no	Data-minimised: only what you need for reconciliation
metadata	no	Up to 20 string key/values for your own use
return_url / cancel_url	no	Where the checkout sends the customer afterwards
expires_in_seconds	no	300–86 400, default 3 600

The response includes id, status (created), livemode, expires_at, checkout_session_id, checkout_url and processor. For live payments, processor describes the invoice in the platform’s Bitcart account (name: "bitcart", custodial: true, its status, the payment methods once the checkout has opened it, and whether the received amount was credited to your balance); quote, payment_instructions and totals belong to watch-only processing and stay null.

Amounts are validated strictly: no signs, no exponents, no excess decimals — nothing is silently rounded.

Reading

GET /v1/payment-intents/{id} returns the intent with:

• processor — for live payments, the Bitcart invoice: status, exception status, payment methods, the paid asset and amount, transaction hashes and whether the amount was credited to your balance.
• quote, payment_instructions and totals — for watch-only processing only: the locked quote (see Quotes), the address and exact amount to pay, and the expected, received and confirmed amounts.
• required_confirmations, detected_at, confirmed_at, resolution.
• fulfillable — true only when the expected amount is final on-chain (confirmed, overpaid, or resolved as accepted).

Fulfil only when fulfillable

Do not deliver goods because a transfer was seen. detected and confirming can still be replaced, reorganised or double-spent. Wait for fulfillable: true, and re-check with GET /v1/payment-intents/{id} before any irreversible action triggered by a webhook.

GET /v1/payment-intents/{id}/timeline returns the append-only list of state transitions with the reason, actor and evidence (transfer ids, confirmation counts, quote id, approvals). Transfers themselves are available under GET /v1/transactions?payment_intent_id=….

Cancelling

POST /v1/payment-intents/{id}/cancel cancels an intent before any transfer has been observed. After a transfer is seen the API returns conflict_error: money may already be on its way and the intent must follow the state machine.

Resolving review states

Some outcomes need a human decision: underpaid, overpaid, late_payment, manual_review. Record yours with POST /v1/payment-intents/{id}/resolve:

{ "resolution": "accepted_partial", "note": "Customer confirmed by email; shipping the partial order." }

resolution	Use when
accepted	You accept the payment as is
accepted_partial	You accept an underpayment
accepted_overpayment	You accept an overpayment (and handle the excess with the customer)
refunded_offchain	You returned the funds from your own wallet
rejected	You will not honour the payment

note (≥ 10 characters) is stored in the audit trail. Resolution never edits or deletes chain evidence — the original observations and transitions remain intact.

Webhooks for intents

payment_intent.created, invoice.awaiting_payment, payment.detected, payment.confirming, payment.confirmed, payment.expired, payment.review_required, payment.reorged, payment.resolved, payment.canceled. See Webhooks.