Developers
The integration surface, as it is being designed
This describes the intended shape of the API. It is pre-release design, not production documentation — no endpoint described here is callable, no sandbox is open, and no credentials are being issued.
State of the work
- API available
- No. No endpoint is callable.
- Sandbox
- Not open. No credentials are being issued.
- Documentation
- This is pre-release design, not production reference.
- Examples published
- None, deliberately — see below.
No request or response examples are published on this site. Sample payloads read as documentation of something that exists, and the shape of these resources will change during design — publishing them now would mean either misleading a reader or promising an interface that has not been reviewed by a security assessor.
Resource families
The intended structure of the API, at the level of what each family is responsible for.
Vault
Create, read and destroy stored payment method references.
Detokenisation, if it exists at all, is scoped and justified per use rather than offered as a convenience.
Payments
Create a payment, then authorise, capture, void or refund it.
Every mutation carries an idempotency key. Retrieval returns the processor's actual outcome, not an inferred one.
Customers & payment methods
Customer references, tokenised payment methods and consent metadata.
Includes the credential-on-file metadata that determines whether a later merchant-initiated transaction is permitted.
Orchestration
Routing policies, processor connections, health state and failover rules.
Configuration, expressed as data that can be reviewed — not conditionals inside a checkout.
Webhooks
Signed delivery of payment lifecycle and reconciliation events.
Signature verification is mandatory on the receiving end; an unverified webhook is an unauthenticated instruction.
Event model
Payment events are designed to be unambiguous about what has actually happened, because the alternative shows up as a reconciliation discrepancy months later.
Every event carries
- Event identifier
- Merchant identifier
- Correlation identifier spanning the whole operation
- Idempotency key or reference
- Timestamp
- Status
- Originating provider
- Sanitised reason codes
- A signature the receiver is expected to verify
Stages are distinguished, not merged
attempted → accepted → authorized → captured → settled
↳ refunded · disputed · failed
Provider acceptance is never treated as settlement confirmation. Collapsing those two is the most expensive shortcut available in payments, because the books balance right up until the money does not arrive.
Identifier design
- Own identity
- Merchants, customers, payments, tokens, processor connections, settlements and disputes each carry a Mirage Gateway identifier. A processor's identifier is never the internal identity of anything.
- Explicit mapping
- External provider identifiers are mapped explicitly. This is what makes changing processor a migration instead of a data loss event.
- No matching on email or name
- Where a durable source identifier exists, it is used. Reconciling merchants or customers by name is how two records become one by accident.
- No card data anywhere near this
- Not in the event bus, not in analytics, not in logs, not in support tooling, not in any consuming product's database.