API Reference

List PaymentIntents

Returns the project's PaymentIntents, newest first. Page with `starting_after` = the last `id` of the previous page while `has_more` is `true`.

Creates a PaymentIntent for the amount you want to collect. The new intent is in status `requires_payment_method` — the normal "waiting for the buyer" state, not an error. **Which operators can be used.** By default (`automatic_operator: true`, no `allowed_operators`) every operator switched on for the key's project is eligible and Wire routes to the best one. Send `allowed_operators` only to narrow that set. **Next step.** Either create a checkout session for the intent (hosted page — recommended) or call `/v1/payment_intents/{id}/confirm` yourself. Do not do both. By default an intent expires **10 minutes** after creation (`expires_at`); an expired, unpaid intent is canceled automatically. **Errors** (besides the common ones): - `400 parameter_missing` (`amount`) — `amount` omitted. - `400 amount_too_small` (`amount`) — `amount` is ≤ 0. - `400 amount_too_large` (`amount`) — `amount` is above 1,000,000,000. - `400 currency_unsupported` — `currency` is not `MNT`. - `400 parameter_invalid` (`description`) — longer than 500 bytes. - `400 operator_unknown` (param `allowed_operators[i]`, the message names the offending value) — an `allowed_operators` entry is not an operator id available on this API, or the list has more than 10 entries. Fix: omit `allowed_operators`, or use only the operator ids shown on your dashboard's Connectors page. - `400 metadata_invalid` — over 50 keys, an empty key, a key over 40 characters or a value over 500 characters. - `403 connector_required` / `403 settlement_account_required`.

Retrieve a PaymentIntent

Returns one PaymentIntent. Poll this (or listen for the `payment_intent.succeeded` webhook) to learn whether the buyer paid. Always re-check `status` server-side before fulfilling an order.

Confirm a PaymentIntent (create the operator invoice)

Chooses an operator, creates the payment (invoice) at that operator, records a pending Charge and moves the intent from `requires_payment_method` to `requires_action`. Show the buyer the returned `next_action` (QR code, bank-app links or a redirect). Payment completes asynchronously: the intent becomes `succeeded` and a `payment_intent.succeeded` event is sent. **Skip this call when you use hosted checkout** — the hosted page confirms the intent itself. **Operator choice**, in order: the `operator` you send → automatic routing among the project's enabled operators (when `automatic_operator` is true) → the first entry of `allowed_operators`. The operator must have an active connection and be switched on for this project. **Errors** (besides the common ones): - `404 resource_missing` — no such intent in this project. - `400 payment_intent_unexpected_state` — the intent is not in `requires_payment_method` (already confirmed, paid, canceled, or a concurrent confirm won). Re-read the intent. - `400 operator_not_allowed` (`operator`) — the operator is not in `allowed_operators`; no eligible operator was found; the operator has no active connection or is not switched on for this project. - `400 operator_unknown` (`operator`) — the operator id is not known to this API. - `402` (`type: payment_method_error`) — the operator declined; `code` is the operator's reason. - `424` (`type: operator_error`) — the operator failed or timed out (`operator_timeout`). Safe to retry with the same `Idempotency-Key`. - `403 connector_required` / `403 settlement_account_required`.

Cancel a PaymentIntent

Cancels an intent that has not been paid. Allowed from `requires_payment_method`, `requires_action`, `requires_capture` and `processing`. If an operator invoice was already created, Wire voids it where the operator supports that. Sends a `payment_intent.canceled` event. Idempotent: canceling an intent that is already `canceled` returns it unchanged and sends no second event. **Errors:** `400 payment_intent_unexpected_state` — the intent already `succeeded`, or its status changed while canceling (re-read it); `404 resource_missing`. Because this is a `POST` under `/v1/payment_intents`, it can also return `403 connector_required` / `403 settlement_account_required`.

Create a checkout session (hosted payment page)

Opens a Wire-hosted payment page for a PaymentIntent and returns its `url`. Redirect the buyer there. The page lists the operators the buyer can pay with, confirms the intent, shows the QR code / bank-app links, and redirects to `success_url` / `cancel_url` when done. Create the session right after creating the intent: the intent must still be in `requires_payment_method` (not confirmed, not canceled, not expired). Do not call `/confirm` yourself for this intent. **Errors** (besides the common ones): - `400 invalid_request_error` (`payment_intent`) — `payment_intent` omitted. - `404 resource_missing` — no such PaymentIntent in this project. - `400 payment_intent_unexpected_state` (`payment_intent`) — the intent is not awaiting payment. - `400 checkout_url_invalid` (`success_url`) — `success_url` or `cancel_url` is not an absolute `http(s)` URL. - `403 connector_required` / `403 settlement_account_required`.

Retrieve a checkout session

Returns one checkout session. For the payment result read the PaymentIntent (or use webhooks) — the session only tracks the page.

List Charges

Returns the project's charges, newest first. Filter to one intent with `payment_intent`.

Retrieve a Charge

List a charge's refunds

Returns every refund of one charge. `charge` is required; this list is not paginated (`has_more` is always `false`). `400 parameter_missing` (`charge`) when `charge` is omitted.

Refund a charge

Refunds a `succeeded` charge, fully (omit `amount`) or partially. The amount is reserved on the charge immediately (it shows in the charge's `amount_refunded`), so concurrent refunds can never exceed the charge. The resulting `status` depends on the operator: `succeeded` — refunded through the operator (a `charge.refunded` event is sent); `manual_required` — the operator does not support refunds through the API, so the refund is recorded and completed by Wire operations outside the API; `pending` — the operator accepted it but has not finished; `failed` — the operator refused and the reserved amount was released. **Errors** (besides the common ones): - `400 parameter_missing` (`charge`) — `charge` omitted. - `400 parameter_invalid` (`amount`) — `amount` is ≤ 0. - `404 resource_missing` — no such charge in this project. - `400 charge_not_refundable` (`charge`) — the charge is not `succeeded`, or is already fully refunded. - `400 amount_invalid` (`amount`) — more than the remaining refundable amount. - `400 reason_too_long` (`reason`) — over 500 bytes. - `424 refund_failed` — the operator could not process the refund.

Retrieve a Refund

List Events

Returns the project's events (the same objects delivered to your webhook endpoint), newest first. Use it to catch up after downtime.

Retrieve an Event

Returns one event. A safe way to double-check a webhook: fetch the event by the `id` you received.

List webhook endpoints

Returns the project's webhook endpoint (at most one). The secret is never included.

Create a webhook endpoint

Registers the project's webhook endpoint. The response contains the signing `secret` (`whsec_…`) — **shown only once**; store it. The endpoint starts in status `pending` and receives nothing until it is verified from the dashboard: Wire sends a signed `endpoint.verification` ping and your URL must answer `2xx`. **Errors** (besides the common ones): - `409 webhook_endpoint_exists` — the project already has its one endpoint; update it instead. - `400 webhook_url_invalid` (`url`) — not an absolute `http(s)` URL, or it points at `localhost` / a private, loopback or link-local IP. - `400 enabled_events_invalid` (`enabled_events`) — an unknown event name, or more than 20 entries.

Retrieve a webhook endpoint

Update a webhook endpoint

Changes the URL, the subscribed events, or pauses/resumes delivery. Only the fields you send change. - `url` — on an endpoint that was never verified the URL is replaced at once. On a verified endpoint the new URL is **staged**: events keep going to the old URL until the new one passes verification from the dashboard. - `enabled_events` — replaces the whole list. - `status` — `disabled` pauses delivery, `enabled` resumes it. Setting `enabled` does not skip verification: an unverified endpoint still receives nothing. **Errors:** `400 webhook_url_invalid`, `400 enabled_events_invalid`, `400 parameter_invalid` (`status` not `enabled`/`disabled`), `404 resource_missing`.

Delete a webhook endpoint

Removes the endpoint; the project can then create a new one.

List operator connections

Returns the business's operator connections (shared by all its projects), newest first.

Connect an operator with your own credentials

Stores credentials for an operator under your business. Credentials are encrypted at rest and never returned. A connection created here starts `inactive`; run `/test` to activate it. To take payments the operator must also be switched on for the project and have a settlement bank account (dashboard). Only `mode: "byo"` can be created here; connections Wire provisions for you come from the dashboard's connector application. **Errors:** `400 operator_unknown` (`operator`), `400 operator_connection_exists` (`operator`) — the business already has a connection for this operator, `400 operator_connection_invalid` (`mode`) — any mode other than `byo`, `400 operator_connection_invalid` (`credentials`) — empty `credentials` or an invalid `mode`.

Retrieve an operator connection

Delete an operator connection

Test an operator connection

Checks that the operator is available and the stored credentials can be read. On success (`status: ok`) a `byo` connection becomes `active`; a connection Wire provisioned for you (`reseller`) is only checked, never switched on here — it is activated by concluding the connector agreement in the dashboard. If the operator cannot be reached the result is `status: unreachable` and the connection is left unchanged.

Preview automatic operator routing

Dry run of automatic routing: returns which operator Wire would pick for these parameters and why, without creating anything. Candidates are the business's active operator connections that are switched on for the key's project. **Errors:** `400 invalid_request_error` (`amount`) — `amount` missing or not a positive integer; `400 operator_unavailable` — no operator is eligible.

Object schemas

Every object's fields, types and required flags on one page.