Miracle Docs

Get current balance — Returns the calling account’s current balance grouped by scope and currency. Each balance has 6 buckets (available, pending, reserved, payable, collateral, operational) representing the lifecycle of funds. Use the optional `scopeLevel` / `scopeEntityId` query params to narrow to a specific entity (e.g. one merchant when called from a tenant-level key).
List balance entries — Cursor-paginated list of balance entries (the immutable ledger of every credit and debit that affects the caller’s balance). Ordered by `occurredAt` descending (newest first). Filter by scope, currency, bucket, entry type, status, or a time range.
Create checkout session — Creates a hosted-payment-page (HPP) / widget checkout session. Requires a secret-key (sk_*) authenticated caller. The `Idempotency-Key` header is REQUIRED and is used for request deduplication (not the optional body field of the same name). The response includes a one-time `clientSecret` (cs_secret_*) the merchant must hand to the buyer so the HPP/widget can authenticate against `GET /v1/checkout-sessions/current`.
Get checkout session by ID — Returns details for a single checkout session. Requires a secret-key (sk_*) authenticated caller with the `payment-experience:checkout:view` permission. Does NOT return the `clientSecret` — that field is only returned in the create response. Soft-deleted sessions are not returned.
Get current checkout session (HPP) — Returns the checkout session referenced by the calling `clientSecret` Bearer token. Used by the hosted-payment-page (HPP) and widget SDKs at render time so they can display line items, totals, and available payment methods. Authentication is clientSecret-based — the session ID is derived from the token, NOT passed in the URL. Returns 403 when the caller is not authenticated with a clientSecret.
Get financial statement by ID — Returns the full details of a single financial statement, including aggregated volumes, fee breakdown, rolling reserve, recurrent fees, and net amounts. Returns 404 if the statement does not exist or is not visible to the caller.
List financial statements — Returns a paginated list of financial statements visible to the caller. Filters: `merchantId`, `terminalId`, `currency`, `status`, `periodFrom`, `periodTo`. Cursor-based pagination — default page size 20, maximum 100.
Activate merchant withdrawal method — Operator action that moves a method to "active" immediately, skipping any remaining cooling period. Use for trusted merchants or after manual verification of the provided details.
Create merchant withdrawal method — Creates a new saved withdrawal method for a merchant. Validates `methodType` against the platform catalog and `details` against the catalog entry’s field schema. New methods enter a cooling period (status "cooling") and become usable only after `activatesAt`.
Get merchant withdrawal method by ID — Returns the full details of a saved withdrawal method, including its catalog type, details, status, and cooling-period timestamp. Returns 404 if the method does not exist or is not visible to the caller.
List merchant withdrawal methods — Returns a paginated list of saved withdrawal methods visible to the caller. Filters: `merchantId`, `methodType`, `status`, `livemode`. Cursor-based pagination — default page size 20, maximum 100.
Soft delete merchant withdrawal method — Marks a saved withdrawal method as deleted. The record is preserved for audit (soft delete) but cannot be used for new withdrawals. Does not affect withdrawals already in flight that reference this method.
Suspend merchant withdrawal method — Operator action that moves a method to "suspended", blocking new withdrawals until the operator reactivates it. Existing approved withdrawals continue to execute. Use when suspicious activity is detected or the merchant requests a temporary block.
Update merchant withdrawal method — Updates a saved withdrawal method. Only `label` and `details` may be changed — `methodType` and `merchantId` are immutable. Changing `details` resets the method to "cooling" and starts a new cooling period for fraud protection.
List available payment methods — Returns payment methods available to the caller for the current checkout context. Two auth flows are supported: (1) client_secret — the session derives currency, merchant, and country; query params are ignored. (2) publishable_key — the `currency` query parameter is REQUIRED and the merchant is taken from the API key owner. Use this endpoint to render payment method selection in HPP or SDK flows.
Cancel payment — Cancels a payment that has not yet been captured. Valid for payments in `processing`, `requires_action`, or `requires_capture` status — cancellation voids the authorization without creating a refund. Returns 409 if the payment is already captured or in a terminal state.
Capture payment — Captures a payment in `requires_capture` status. Only valid for payments created with `captureMethod: "manual"` that are currently in the `requires_capture` status. Captures the full authorized amount — partial captures are not currently supported. Returns 409 if the payment is not in `requires_capture` status.
Complete 3DS action — Finalizes a 3DS challenge. Called after the buyer completes the challenge and the ACS redirects back to the merchant returnUrl with result parameters. Send either 3DS2 `redirectResult`/`cres` or 3DS1 `md`+`paRes`. Only valid for payments currently in `requires_action` status; returns 409 otherwise.
Create payment — Creates a new H2H payment. The `paymentMethod` field is required — merchants must know the payment instrument upfront (card token, bank transfer, wallet, etc.). Card payments require a vault `token` obtained from the tokenization API. Pass an `Idempotency-Key` header to safely retry without double-charging. Auto-capture is the default; set `captureMethod: "manual"` for separate authorize + capture flows.
Get payment by ID — Returns details for a single payment, including current lifecycle status, 3DS result (if applicable), and the latest provider response. Soft-deleted payments are not returned.
List payments — Returns a paginated list of payments visible to the caller. Merchant-scoped API keys are auto-restricted to their own merchant. Filters: `merchantId`, `status`, `livemode`. Uses cursor-based pagination — pass `cursor` from a previous response to fetch the next page. Default page size is 20, maximum 100.
Create refund for payment — Creates a refund against an existing captured payment. The `paymentId` is taken from the URL path. Omit `amount` to refund the full remaining capturable amount, or specify a partial `amount` for a partial refund. Multiple partial refunds are supported until the captured amount is exhausted. Pass an `Idempotency-Key` header to safely retry without double-refunding.
Get refund by ID — Returns details for a single refund, including its current lifecycle status and link back to the originating payment. Soft-deleted refunds are not returned.
List refunds for payment — Returns all refunds for the specified payment, most recent first. Uses cursor-based pagination — pass `cursor` from a previous response to fetch the next page. Default page size is 20, maximum 100. Returns an empty list if the payment has no refunds.
Generate settlement for merchant + period — Generates a new settlement for a merchant over a single-currency period. Aggregates payment, refund, chargeback, and fee data. To create an adjustment settlement that revises a previously finalized settlement, supply `linkedSettlementId`, `adjustmentDirection`, `adjustmentAmount`, and `adjustmentReason`.
Finalize draft settlement — Finalizes the settlement, marking all linked financial statements as paid. This is an irreversible action. Once finalized, the settlement document and its fee breakdown become the official financial record for the period.
Get settlement by ID — Returns the full details of a single settlement, including aggregated volumes, fee breakdown, rolling reserve, adjustments, and net amount paid to the merchant. Returns 404 if the settlement does not exist or is not visible to the caller.
List settlements — Returns a paginated list of settlements visible to the caller. Filters: `merchantId`, `currency`, `status`, `periodFrom`, `periodTo`. Cursor-based pagination — default page size 20, maximum 100.
Get webhook delivery record — Returns a single delivery record by ID. Ownership is verified — the record must belong to a webhook endpoint owned by the caller scope. Returns 404 when the record does not exist or is outside the caller scope.
List webhook delivery records — Returns delivery records for webhook endpoints owned by the caller. Merchant callers see only records for their own endpoints. Filters: `endpoint_id`, `event_type`, `status`, `created_after`, `created_before`. Cursor-based pagination via `cursor` + `limit` (default 20, max 100).
Create webhook endpoint — Creates a new webhook endpoint bound to the caller owner scope (merchant, tenant, or platform). The HMAC signing secret is returned ONCE in this response — store it securely. Subscribed `events` must exist in the catalog and be visible to the caller. URL must use HTTPS.
Delete webhook endpoint — Soft-deletes a webhook endpoint — deliveries stop immediately. The record is preserved for audit (deletedAt is set). Issue a new endpoint if you need to resume deliveries.
Get webhook endpoint — Returns a single webhook endpoint by ID. Ownership is verified against the caller scope. The signing secret is never returned on read — use POST .../rotate-secret to generate a new one.
List webhook endpoints — Returns webhook endpoints owned by the caller scope. Merchant callers see only their own endpoints; tenant/platform callers see endpoints at their owner level. Signing secrets are never included in list responses.
List available webhook event types — Returns the catalog of event types the caller may subscribe to. Results are filtered by the caller owner level (merchant, tenant, or platform) — lower-privilege callers see a narrower catalog. Use this list to discover valid values for the `events` field when creating or updating a webhook endpoint.
Rotate webhook endpoint signing secret — Generates a new HMAC-SHA256 signing secret for the specified endpoint. The new secret is returned ONCE in this response — store it securely. The previous secret is replaced immediately.
Update webhook endpoint — Updates mutable fields of a webhook endpoint (url, events, description, status). Only fields included in the body are changed. Events, if provided, REPLACE the previous subscription set — no partial merge. Use `status: "disabled"` to pause deliveries without deleting the endpoint.
Get withdrawal method catalog entry by type — Returns a single catalog entry by its machine-readable `type` key (e.g. "sepa_bank_transfer"). Use this when validating a saved method or when showing details of a specific method type.
List withdrawal method catalog entries — Returns the platform-wide catalog of supported withdrawal method types. Each entry defines the machine-readable `type` key, a human-readable label, and a JSON schema describing the required `details` fields. Use this catalog to render the "add withdrawal method" form in merchant portals.
Approve withdrawal — Operator action that moves a pending withdrawal to `approved`. The balance guard is enforced at approval time — the amount is reserved on the entity’s payable bucket atomically. Operators may supply a `fundingAccountId` or `withdrawalChannelId` to override routing.
Cancel withdrawal — Cancels a withdrawal initiated by the requesting entity. Allowed from `pending` or `approved` states. If the withdrawal was approved (funds reserved), cancellation reverses the payable entries and restores the available balance.
Mark withdrawal as completed — Closes an executing withdrawal with success. A `comment` (typically the bank wire reference) is mandatory for auditability. Creates the final ledger entries: debit the payable bucket and credit the funding account.
Create withdrawal request — Creates a new withdrawal request for the caller’s entity. The fee is calculated at creation time by the billing engine. Pass an `Idempotency-Key` header to deduplicate retries — the same key returns the original withdrawal. The new request starts in `pending` status and must be approved by an operator before execution.
Start withdrawal execution — Marks an approved withdrawal as `executing`, recording the operator who started the manual withdrawal execution. Provides mutual exclusion — a second operator cannot start execution on the same withdrawal. Use `/complete` or `/fail` to close the execution.
Mark withdrawal as failed — Closes an executing withdrawal with failure. A `comment` explaining the failure is mandatory. Reverses the payable entries — debit payable, credit available — so the requester can retry.
Get withdrawal by ID — Returns the full details of a single withdrawal request including status, fee, destination, and audit timestamps. Returns 404 if the withdrawal does not exist or is not visible to the caller.
List withdrawals — Returns a paginated list of withdrawals visible to the caller. Filters: `entityType`, `entityId`, `status`, `currency`, `livemode`. Uses cursor-based pagination — pass `cursor` from a previous response to fetch the next page. Default page size is 20, maximum 100.
Reject withdrawal — Operator action that rejects a pending withdrawal. A `rejectionReason` is mandatory — it is stored on the withdrawal and surfaced back to the requesting entity. Rejected withdrawals cannot be re-approved; the requester must create a new one.

Merchant API Reference