> ## Documentation Index > Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a payment intent > Creates a payment intent for a given amount and currency. Supplying a `payment_method` confirms it in the same request (create-and-confirm), in which case a decline returns `402` with the intent embedded. ## OpenAPI ````yaml /openapi/payments.yaml post /payment_intents openapi: 3.0.3 info: title: Ionic Payments API version: '2026-05-01' description: | Payment intents, charges, and refunds — the money-movement core. A payment intent (`pi_…`) tracks one payment. Create it with an amount and currency, then confirm it with a payment method or one-time payment token. Each confirmation creates a Charge; after a decline, confirm the same PaymentIntent again with a different payment method. With `capture_method: automatic` (the default) a successful confirmation captures immediately; with `manual` it authorizes, and you capture later. A Charge (`ch_…`) records one confirmation attempt, and `latest_charge_id` points to the most recent one. A Refund (`rf_…`) returns captured funds from a Charge. All monetary amounts are integers in the currency's minor unit (for example cents for USD). Timestamps are Unix epoch seconds. Identifiers are opaque, prefixed strings. Authentication uses a merchant secret key (`sk_…`) as a bearer token. Read endpoints require the `payments:read` permission; write endpoints require `payments:write`. The mode of the key (test or live) scopes which resources it can see and mutate, and is reflected by each resource's `livemode` field. Confirming and retrieving an intent additionally accept a publishable key (`pk_…`) together with the intent's `client_secret`, for client-side flows; every other endpoint is secret-key only. Send an `Idempotency-Key` header on create, confirm, capture, and cancel so retries do not duplicate an operation. Errors are returned as `{ "error": { "code": "...", "message": "..." } }`. Payment-specific failures carry extra fields: a card decline returns `402` with `type: card_error`, a `decline_code`, a `decline_type`, and a `retryable` flag, and embeds the current payment intent so you can inspect its status without a second call. servers: - url: '{baseUrl}/v1' variables: baseUrl: default: https://api.ionicfi.com description: API base URL for your environment. security: - secretKey: [] tags: - name: Payment Intents description: Create, confirm, capture, and cancel attempts to collect money. - name: Charges description: Records of individual PaymentIntent confirmation attempts. - name: Refunds description: Reversals of captured funds on a charge. paths: /payment_intents: post: tags: - Payment Intents summary: Create a payment intent description: | Creates a payment intent for a given amount and currency. Supplying a `payment_method` confirms it in the same request (create-and-confirm), in which case a decline returns `402` with the intent embedded. operationId: payment_intents_create parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentIntentRequest' responses: '201': description: The created payment intent. content: application/json: schema: $ref: '#/components/schemas/PaymentIntent' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/Declined' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - payments:write components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation. schema: type: string maxLength: 255 schemas: CreatePaymentIntentRequest: type: object required: - amount - currency properties: amount: type: integer description: Amount to collect, in minor units. currency: type: string description: Three-letter ISO currency code. capture_method: type: string enum: - automatic - manual default: automatic description: >- `automatic` captures on confirmation; `manual` authorizes, then you capture later. payment_method: type: string description: >- Payment method id (`pm_…`). When present, the intent is confirmed in the same request. mandate: type: string description: Mandate id authorizing a merchant-initiated charge. initiated_by: type: string enum: - customer - merchant description: >- Who initiated the charge. `merchant` (off-session) requires a secret key. reference: type: string description: Your order number or other reference (max 256 chars). customer: type: string description: Customer id (`cus_…`) to attach. metadata: type: object additionalProperties: type: string description: >- A string key-value map for storing your own structured data. Up to 50 keys; each key at most 40 characters and each value at most 500 characters. PaymentIntent: type: object required: - amount - capture_method - client_secret - created_at - currency - customer - id - latest_charge_id - livemode - merchant_id - metadata - object - payment_method - status - updated_at properties: id: type: string description: The payment intent id (`pi_…`). object: type: string enum: - payment_intent description: Always `payment_intent`. merchant_id: type: string description: The owning merchant (`mer_…`). livemode: type: boolean description: >- Whether this intent was created with a live (`true`) or test (`false`) key. client_secret: type: string nullable: true description: >- Returned when the intent is created or confirmed; null on capture, cancel, and list responses. tokenization: allOf: - $ref: '#/components/schemas/TokenizationConfig' nullable: true description: >- Browser-safe card-fields configuration returned with `client_secret` on publishable-key requests. Null when card collection is not available. customer: type: string nullable: true description: >- The attached customer (`cus_…`). Null unless a customer was passed at creation. amount: type: integer description: The amount to collect, in minor units. Always positive. currency: type: string description: Three-letter ISO currency code. USD, EUR, and GBP are supported. capture_method: type: string enum: - automatic - manual description: >- `automatic` captures the charge on confirmation. `manual` authorizes a hold; capture it later via `POST /payment_intents/{id}/capture`. status: type: string enum: - requires_payment_method - requires_confirmation - requires_action - requires_capture - processing - succeeded - canceled description: >- One of `requires_payment_method` (collect or attach a payment method), `requires_confirmation` (ready to confirm), `processing` (payment is in progress), `requires_action` (the buyer must complete another step), `requires_capture` (authorized and awaiting manual capture), `succeeded` (payment completed), or `canceled` (payment can no longer be completed). payment_method: type: string nullable: true description: >- The attached payment method (`pm_…`). Nullable; cleared on a decline so a retry can attach a different method. latest_charge_id: type: string nullable: true description: The most recent charge produced by this intent (`ch_…`). reference: type: string description: Your order number or other reference. Max 256 characters. metadata: type: object additionalProperties: type: string description: >- A string key-value map for storing your own structured data. Up to 50 keys; each key at most 40 characters and each value at most 500 characters. created_at: type: integer description: Unix epoch seconds. updated_at: type: integer description: Unix epoch seconds, bumped on every mutation. TokenizationConfig: type: object description: Browser-safe configuration for initializing hosted card fields. required: - provider - tokenization_key properties: provider: type: string description: >- Reserved for the Ionic browser SDK. Do not inspect or configure this value. tokenization_key: type: string description: >- A browser-safe public key used to create a one-time payment token. It cannot submit a charge. Error: type: object properties: error: $ref: '#/components/schemas/ErrorDetail' PaymentError: type: object description: >- An error that embeds the current payment intent so you can inspect its status. properties: error: $ref: '#/components/schemas/ErrorDetail' payment_intent: $ref: '#/components/schemas/PaymentIntent' ErrorDetail: type: object required: - code - message properties: code: type: string message: type: string type: type: string enum: - card_error - invalid_request_error - api_error decline_code: type: string decline_type: type: string enum: - authorization - authentication - infrastructure retryable: type: boolean description: >- Whether the underlying condition may resolve on its own over time — for example available funds being deposited or a velocity window resetting. `true` does not mean the request is safe to retry immediately. doc_url: type: string responses: BadRequest: description: The request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_REQUEST message: invalid currency Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' Declined: description: The card was declined. The error embeds the current payment intent. content: application/json: schema: $ref: '#/components/schemas/PaymentError' example: error: type: card_error code: PAYMENT_DECLINED message: Your card was declined. decline_code: insufficient_funds decline_type: authorization retryable: false payment_intent: id: pi_2pXq object: payment_intent merchant_id: mer_7kRzDef livemode: false client_secret: null customer: null amount: 5000 currency: USD capture_method: automatic status: requires_payment_method payment_method: null latest_charge_id: null metadata: {} created_at: 1700000000 updated_at: 1700000000 Forbidden: description: The key lacks the required permission, or the merchant is not active. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Too many requests. Honour the `Retry-After` header before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: | The API could not return a successful response. For a mutating request, retrieve the resource before retrying because the operation may have completed. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: secretKey: type: http scheme: bearer description: 'A merchant secret key (`sk_…`) sent as `Authorization: Bearer `.' ````