Create a PaymentIntent

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`.

POST/v1/payment_intents

Authorization

bearerAuth

AuthorizationBearer <token>

Secret API key as a bearer token: Authorization: Bearer sk_live_…. Test keys (sk_test_…) are refused with 401 test_mode_unavailable. Keys are issued per project in the dashboard. Never expose a secret key in browser or mobile code.

In: header

Header Parameters

Idempotency-Key*string

Required on every POST and DELETE (missing → 400 parameter_missing; longer than 255 characters → 400 parameter_invalid). Use one stable key per logical operation, e.g. your order id plus the action. A retry with the same key and the same body returns the recorded response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body or path → 409 idempotency_key_in_use. While the first request is still running, a duplicate gets 409 idempotency_in_flight — wait a moment and retry. Successful (2xx) and declined (402) responses are recorded for 48 hours; other errors are not, so a retry after fixing a 400 runs normally. Keys are scoped to the API key's project.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount*integer

Amount to collect in MNT — whole tögrög, no fractional part (15000 = 15,000 ₮). 1 to 1,000,000,000. An operator may enforce its own minimum.

currency?string

Currency. Only MNT is supported; omit it or send MNT.

description?string

Transaction description shown to the payer (e.g. on the invoice / bank statement). Optional; at most 500 bytes (UTF-8 — Cyrillic letters take 2 bytes each).

automatic_operator?boolean

true (default): at confirm, Wire routes to the best eligible operator. false: the first entry of allowed_operators is used unless /confirm names an operator — so with false you must send allowed_operators or an explicit operator.

allowed_operators?array<string>

Optional. Restricts which operators may be used for this intent. Omit it to allow every operator switched on for your project (recommended). Values are operator ids enabled on your account, as shown on the dashboard's Connectors page. An unknown id → 400 operator_unknown with param allowed_operators[i] naming the offending value; more than 10 entries is also refused.

metadata?

Your own key/value strings (e.g. your order id), returned on every read. Up to 50 keys; keys 1–40 characters; values up to 500 characters. Violations → 400 metadata_invalid.

Response Body

`application/json`

curl -X POST "https://example.com/v1/payment_intents" \  -H "Idempotency-Key: order-1001-create" \  -H "Content-Type: application/json" \  -d '{    "amount": 15000,    "currency": "MNT",    "description": "Order #1001"  }'

{
  "id": "pi_k3vq7m2xw5nbt4rj6yhc2dpa7e",
  "object": "payment_intent",
  "amount": 15000,
  "currency": "MNT",
  "description": "Order #1001",
  "status": "requires_payment_method",
  "client_secret": "cs_n2xk5q7mw3tz4vbr6jcy2gfa7m",
  "automatic_operator": true,
  "allowed_operators": [],
  "selected_operator": null,
  "next_action": null,
  "metadata": {
    "order_id": "1001"
  },
  "livemode": true,
  "created": 1791774000,
  "expires_at": 1791774600
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "amount is required",
    "param": "amount",
    "request_id": "req_8f3a1c9e5b7d2f4a6c0e9b1d"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "test_mode_unavailable",
    "message": "test keys are not accepted by this API; use a live secret key",
    "request_id": "req_8f3a1c9e5b7d2f4a6c0e9b1d"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "connector_required",
    "message": "connect a payment operator before creating payments — see the Connectors page in your dashboard",
    "request_id": "req_8f3a1c9e5b7d2f4a6c0e9b1d"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_in_flight",
    "message": "A request with this Idempotency-Key is still being processed; retry shortly",
    "request_id": "req_8f3a1c9e5b7d2f4a6c0e9b1d"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "string",
    "param": "amount",
    "request_id": "req_8f3a1c9e5b7d2f4a6c0e9b1d",
    "doc_url": "string",
    "operator_decline_code": "string"
  }
}

Create a PaymentIntent

Authorization

Header Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

409application/json

429application/json

Example testKey

Example invalidKey

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`