Plan
Commercial template for price, cadence, and entitlement rules.
Developer preview
Architecture overview for customer-action billing.
This page is a developer preview of MonetLayer object relationships, verification rules, and webhook direction. It does not expose a public production API hostname.
Related reading: product lifecycle, settlement proof, reconciliation, and usage-based billing.
API contract preview — not a public production endpoint
Example base URL placeholder
https://api.example.monetlayer.dev
Use this only as a contract sketch for early-access discussion. Do not treat it as a live public endpoint.
Quickstart preview
A coherent object flow around one collection.
- 01
Create plan
- 02
Create subscription
- 03
Open invoice
- 04
Create payment attempt
- 05
Receive customer-action requirement
- 06
Verify settlement
- 07
Receive webhook
01Plan
02Subscription
03Invoice
04PaymentAttempt
05CustomerActionRequest
06SettlementEvidence
07Entitlement
08WebhookEvent
09WebhookDelivery
Conceptual billing object
{
"invoice_id": "inv_preview",
"amount": {
"raw": "100000",
"decimals": 6,
"formatted": "0.100000",
"currency": "USDC"
},
"collection_method": "customer_initiated",
"payment_status": "requires_action",
"network": "base-sepolia"
}Subscription
Customer binding to a plan across billing periods.
Invoice
Amount-due record for a collection period.
PaymentAttempt
Collection attempt with explicit action and verification state.
CustomerActionRequest
Requirement for customer wallet confirmation.
SettlementEvidence
Verified onchain receipt evidence bound to billing state.
Entitlement
Access state activated after reconciliation.
WebhookEvent
Durable merchant-facing state-change event.
WebhookDelivery
Delivery attempt history for a webhook event.
Example response
Requires-action invoice shape with integer-safe amounts.
{
"invoiceId": "inv_preview_example",
"status": "requires_action",
"collectionMethod": "customer_initiated",
"network": "base-sepolia",
"amount": {
"raw": "100000",
"decimals": 6,
"formatted": "0.100000",
"currency": "USDC"
}
}Execution boundary
Payment execution is separate from billing truth.
A provider can submit or observe payment movement. MonetLayer records the billing lifecycle, verifies settlement evidence, reconciles invoice state, activates entitlement, and delivers merchant webhooks.
Billing truth
01
MonetLayer billing coreLifecycle, reconcile, entitle
Payment execution
01
Payment execution providerSubmit or observe movement
Customer-action lifecycle
01
invoice.open02
payment.requires_action03
transaction.submitted04
receipt.verified05
invoice.paid06
entitlement.active07
webhook.deliveredWebhook events
Label contract maturity honestly.
invoice.opened
Current contract direction
payment_attempt.requires_action
Current contract direction
settlement.confirmed
Current contract direction
invoice.paid
Current contract direction
entitlement.activated
Current contract direction
webhook.delivery_succeeded
Proposed contract
webhook.delivery_failed
Proposed contract
Idempotency
Duplicate webhook processing and historical replay against the same payment evidence must not create conflicting billing state. Exact request headers such as Idempotency-Key are not published here unless verified in the public contract.
Environment details
Network: Base Sepolia. Chain ID: 84532. Billing asset: USDC. Collection model: Customer initiated. Signature: Required for each demonstrated collection. Product status: Early access / testnet.
Provider support status
Provider availability is stated narrowly.
| Provider | Current status |
|---|---|
| Mock | Local and staging testing |
| Direct Base | Customer-initiated Base Sepolia |
| StablecoinX Harness | Blocked pending documentation and access |