Invoice payments

Invoice payments use 0Base when the payable object is an invoice rather than a shopping cart. The invoice record should keep customer, due date, amount, currency, payment object, notification, and ledger evidence in one closeable chain.

0Base availability is account-gated. Build against capabilities, merchant status, environment mode, and settlement settings instead of assuming that every payment method, asset, network, cadence, or refund path is enabled for every merchant.

0Base product docs and API details

These pages are public product guidance for merchant and platform developers. 0Base endpoint-level API pages are not published for partners yet; use this product documentation to understand the workflow, records, and launch boundaries.

End-to-end picture

This flow is intentionally shown as product infrastructure: Invoice issued -> Create invoice object -> Customer pays -> Intent status -> Ledger row -> Invoice closed. The merchant application can make the customer experience simple, but the backend should keep each step visible enough for retries, support, and finance closeout.

Production contract

Boundary	What to build	Why it matters
Invoice identity	Store invoice number, customer email/reference, due date, amount, and currency before creating the payment object.	The invoice is the business document.
Payment object	Create invoice or payment link/intent object tied to the invoice reference.	Creates a payment lifecycle.
Due date and expiry	Keep due date separate from checkout expiry.	A payable invoice may need refreshed payment sessions.
ERP sync	Update accounting only from trusted status and ledger records.	Avoids closing invoices from page views.
Collections recovery	Define reminders, voids, failed payment handling, and late payment policy.	B2B payments need traceable exceptions.

Status and state handling

State	What it means	Developer action
Open	Invoice is payable but not paid.	Show payment route.
Payment pending	Payment exists but not final.	Keep invoice open.
Paid	Payment terminal success and ledger evidence exist according to policy.	Close invoice.
Void/failed	Invoice no longer payable or payment failed.	Recover or reissue.

Status handling should be strict even when the customer UI is friendly. Store raw 0Base statuses, map them to customer-safe labels at the edge, and keep the merchant order state separate from the payment object state. That separation lets you change customer copy without corrupting reconciliation.

Example implementation record

This is an application-side record shape for invoice payments. Keep exact request and response fields aligned with your enabled account contract when 0Base API access is released for your partner account; the point of this record is to keep product, support, and finance joined in your system.

{
  "invoice_number": "INV-2026-1042",
  "invoice_id": "inv_live_123",
  "payment_intent_id": "pi_live_456",
  "customer_email": "finance@example.com",
  "amount": "1500.00",
  "currency": "EUR",
  "due_at": "2026-07-15T00:00:00Z",
  "invoice_state": "payment_pending"
}

Operational scenario

B2B invoice collection is less about speed and more about records. A finance team needs to know which invoice was issued, which payment object attempted collection, which event marked status, and which ledger row closed the period.

In practice, production 0Base integrations make the happy path fast while keeping exceptions predictable: retries return the same object, delayed notifications can be repaired, expired sessions do not become mystery payments, and finance exports can be traced back to the original merchant order.

Before and after

Before 0Base	With 0Base
Invoices included static wallet instructions.	Invoices link to 0Base payment objects with statuses.
Due date and payment expiry were confused.	Due date belongs to invoice; expiry belongs to payment session.
Accounting marked paid from customer reply.	Accounting marks paid from trusted status/ledger evidence.
Late payment recovery was manual.	Late payment policy uses invoice id, intent id, and event history.

Evidence to keep

Evidence	What to store
Invoice record	Invoice id/number, customer, due date, amount, currency.
Payment record	Invoice object id, payment intent id, status, expiry if applicable.
Notification record	Events delivered to merchant/ERP and processing result.
Ledger record	Settlement id, amount/asset, status, report period.
Collections record	Reminder, void, reissue, or support note with ids.

This evidence is what makes the integration supportable at institutional scale. A developer should not need private operational knowledge to answer basic questions such as what the customer saw, which object owns the state, which event announced the change, and which ledger or report row closed the money movement.

Failure modes and recovery

Failure mode	Recovery
Customer pays void invoice	Keep closed and route to support/refund policy.
Payment session expires before invoice due date	Create fresh payment object without changing invoice amount.
ERP webhook fails	Replay notification and dedupe event id.
Partial payment detected	Keep invoice open until policy resolves.

Recovery should be idempotent and explainable. When the system is uncertain, preserve the current raw status, read the latest object state, attach a support reference, and avoid changing fulfillment or finance state until a trusted terminal condition is present.

API adjacency

API area	Use it for
`POST /invoices`	Create invoice-style object.
`POST /payment_intents`	Create payment intent for invoice flow.
`GET /webhooks/deliveries`	Recover ERP notification delivery.
`GET /reports/settlement`	Close invoice settlement.

For endpoint-level implementation, use the API reference as the source of truth for fields, enums, authentication, idempotency behavior, pagination, and response examples.

Why this matters for merchants and customers

Invoice payments need records that finance teams can close. 0Base gives invoice flows payment objects, notifications, and ledger joins instead of static wallet instructions embedded in PDFs or emails.

At scale, the value of 0Base is not only that a payment can be created. The value is that the payment can be explained later: what the customer saw, which account capabilities allowed it, which backend state changed, which notification delivered it, and which ledger or report row closed it.

Worked API path

The example below shows the implementation shape for this page. Use merchant-specific capabilities, account settings, and API responses in production; the ids and values here are illustrative.

curl -X POST https://base-api-sandbox.0bit.app/v1/invoices \
  -H "Authorization: Bearer $OBIT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ord_100045:base:v1" \
  -d '
{
    "amount": "1500.00",
    "currency": "EUR",
    "cryptoCurrency": "USDT",
    "clientReference": "INV-2026-1042",
    "customerEmail": "finance@example.com",
    "title": "Invoice INV-2026-1042",
    "dueAt": "2026-07-15T00:00:00Z"
}'

Example response shape:

{
  "invoice_id": "inv_test_123",
  "status": "open",
  "amount": "1500.00",
  "currency": "EUR",
  "crypto_currency": "USDT",
  "invoice_url": "https://checkout.0bit.app/i/inv_test_123"
}

Implementation checkpoints:

Store your merchant reference before calling 0Base.
Attach the returned object id to the same business record.
Record the request id, idempotency key, raw status, and environment.
Use webhook and report reads to repair delayed or missed state changes.

Data join map

This join map is the reason 0Base is infrastructure rather than a payment button. A merchant can change checkout UX, support tooling, or finance exports without losing the chain from customer action to backend state and settlement evidence.

Operator runbook

Signal	Check first	Action
Customer reports payment not updating	Look up merchant order id, 0Base object id, raw status, and latest webhook delivery.	Read current object state before changing fulfillment.
Webhook delivery failed	Check delivery id, event id, attempts, last error, and handler logs.	Fix the handler, replay once, and dedupe by event id.
Finance cannot match a row	Compare client reference, intent id, settlement id, report period, and export row.	Move the item to reconciliation queue instead of closing by amount/date.

The runbook should be available to support and finance teams before launch. A developer integration is not complete if only engineering can explain the state of a customer payment.

Developer checklist

Keep invoice due date separate from checkout expiry.
Use invoice number as client reference where appropriate.
Do not email payment state from the browser alone.
Sync ERP from signed events or reports.
Record void/reissue decisions.
Test late and partial payment scenarios.