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

# Retrieve a setup intent



## OpenAPI

````yaml /openapi/setup_intents.yaml get /setup_intents/{id}
openapi: 3.0.3
info:
  title: Ionic Setup Intents API
  version: '2026-06-27'
  description: >
    Setup intents for saving a payment method without charging.


    A setup intent (`seti_…`) guides the process of vaulting a card for future

    use without collecting any payment. You create it with a currency and an

    optional customer, then confirm it with a single-use payment token from the

    client. On success the intent moves to `succeeded` and a reusable payment

    method (`pm_…`) is created and linked. If vaulting fails the intent returns

    to `requires_confirmation` so the flow can be retried with a fresh token.

    Canceling from `requires_confirmation` moves it to `canceled`.


    Timestamps are Unix epoch seconds. Identifiers are opaque, prefixed strings:

    setup intents are `seti_…`.


    Authentication uses a merchant secret key (`sk_…`) as a bearer token. Read

    endpoints require the `setup_intents:read` permission; write endpoints
    require

    `setup_intents:write`. The mode of the key (test or live) scopes which
    intents

    it can see and mutate, reflected by each resource's `livemode` field. All

    endpoints are secret-key only; there are no publishable-key or client-secret

    flows for this resource.


    Errors are returned as `{ "error": { "code": "...", "message": "..." } }`.
servers:
  - url: '{baseUrl}/v1'
    variables:
      baseUrl:
        default: https://api.ionicfi.com
        description: API base URL for your environment.
security:
  - secretKey: []
tags:
  - name: Setup Intents
    description: Save a payment method for future use without charging.
paths:
  /setup_intents/{id}:
    parameters:
      - $ref: '#/components/parameters/SetupIntentId'
    get:
      tags:
        - Setup Intents
      summary: Retrieve a setup intent
      operationId: setup_intents_retrieve
      responses:
        '200':
          description: The setup intent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupIntent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/SetupIntentNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - secretKey:
            - setup_intents:read
components:
  parameters:
    SetupIntentId:
      name: id
      in: path
      required: true
      description: The setup intent id (`seti_…`).
      schema:
        type: string
  schemas:
    SetupIntent:
      type: object
      required:
        - created_at
        - currency
        - customer
        - id
        - livemode
        - merchant_id
        - metadata
        - object
        - payment_method
        - status
        - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the setup intent (`seti_…`).
        object:
          type: string
          enum:
            - setup_intent
        merchant_id:
          type: string
        livemode:
          type: boolean
        customer:
          type: string
          nullable: true
          description: >-
            The customer this intent is attached to (`cus_…`), or null if not
            customer-scoped.
        currency:
          type: string
          description: Three-letter ISO currency code.
        status:
          type: string
          enum:
            - requires_confirmation
            - processing
            - succeeded
            - canceled
          description: >
            `requires_confirmation` — initial state; awaiting a client-side
            token.

            `processing` — vault operation is in progress.

            `succeeded` — card vaulted and payment method created.

            `canceled` — intent was canceled before completion.
        payment_method:
          type: string
          nullable: true
          description: >-
            The reusable payment method created when the card was vaulted
            (`pm_…`). Null until `succeeded`.
        metadata:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: integer
          description: Unix epoch seconds.
        updated_at:
          type: integer
          description: Unix epoch seconds.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable, machine-readable error code.
            message:
              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: currency is required
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key lacks the required permission, or the merchant is not active.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    SetupIntentNotFound:
      description: No setup intent with that id is visible to this key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: SETUP_INTENT_NOT_FOUND
              message: setup intent not found
    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 <key>`.'

````