> ## Documentation Index > Fetch the complete documentation index at: https://documentation.suby.fi/llms.txt > Use this file to discover all available pages before exploring further. # Save a payment method to a customer > Attach a tokenized card to a customer for later **off-session** (MIT) charges. Only the card family produces a reusable token, so `type` is restricted to CARD / APPLE_PAY / GOOGLE_PAY. May return `REQUIRES_ACTION` with a 3DS challenge URL. No Payment is created — pure attachment. ## OpenAPI ````yaml /v3-beta/api-reference/openapi.yaml post /v3/setup-intents openapi: 3.1.0 info: title: Suby.fi Merchant API version: 3.0.0-beta description: > The **v3** public merchant API for Suby.fi. RESTful (plural, resource-oriented endpoints under the `/v3` prefix). Authenticate every request with your secret API key in the `X-Suby-Api-Key` header. - `sk_live_…` keys operate in **production** (real funds). - `sk_sandbox_…` keys operate in a fully simulated **sandbox** (test cards, Base Sepolia crypto, no real money). The environment is derived from the key prefix. All monetary amounts are **integer cents** (except `priceCents` on some read shapes, which is a string) — token amounts are strings in the smallest unit (sats / lamports / wei). Fees are basis points. contact: email: dev@suby.fi url: https://suby.fi servers: - url: https://api.beta.suby.fi description: Production + sandbox (environment selected by API key prefix) security: - ApiKeyAuth: [] tags: - name: Products description: Manage your product catalog (one-time and recurring). - name: Checkout description: >- Hosted checkout — signed session tokens (`cs_…`) plus branding and appearance settings. - name: Payments description: >- Create, capture, void, and retrieve one-time & off-session payments (card, APM, and crypto). - name: Subscriptions description: Start and cancel recurring subscriptions. - name: Customers description: First-class customer records with billing address. - name: Payment Methods description: >- Save a payment method to a customer and manage saved instruments for off-session charges. - name: Webhook Endpoints description: Register outbound webhook destinations and rotate signing secrets. - name: Analytics description: Org-wide revenue analytics. - name: Health description: Unauthenticated liveness probe. paths: /v3/setup-intents: post: tags: - Payment Methods summary: Save a payment method to a customer description: > Attach a tokenized card to a customer for later **off-session** (MIT) charges. Only the card family produces a reusable token, so `type` is restricted to CARD / APPLE_PAY / GOOGLE_PAY. May return `REQUIRES_ACTION` with a 3DS challenge URL. No Payment is created — pure attachment. operationId: createSetupIntent parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - customerId - paymentMethod properties: customerId: type: string example: cus_abc123 description: The customer to attach the instrument to. Required. paymentMethod: type: object required: - type - tokenizedInstrument properties: type: type: string enum: - CARD - APPLE_PAY - GOOGLE_PAY description: >- Card family only — the sole instruments that yield a reusable off-session token. tokenizedInstrument: type: string minLength: 4 maxLength: 200 description: Fresh token from the client-side SDK. Required. isPreferred: type: boolean default: false description: Mark as the default instrument for this customer. threedsSessionData: type: object additionalProperties: true description: >- Optional proactive-3DS browser fingerprint — authenticates the card up front so later off-session debits are SCA-exempt MITs. Omit to save without 3DS. responses: '201': description: Setup intent created (status `SUCCEEDED` or `REQUIRES_ACTION`) content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: object properties: setupIntent: $ref: '#/components/schemas/SetupIntent' paymentMethod: $ref: '#/components/schemas/PaymentMethod' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional key (≤255 chars, e.g. a UUID v4) that makes this POST safe to retry: the first request executes and its response is cached for 24h; a retry with the SAME key replays that response instead of re-executing (no duplicate payment/subscription). A reused key with a different request → `422 IDEMPOTENCY_KEY_CONFLICT`; a retry while the first is still in flight → `409`. See the Idempotency guide. schema: type: string maxLength: 255 example: 5f3b9c2e-1a4d-4f2b-9c31-7e2a1b6d8c04 schemas: SuccessEnvelope: type: object required: - success - data properties: success: type: boolean example: true message: type: string data: description: Endpoint-specific payload. SetupIntent: type: object properties: id: type: string description: Synthetic id (no DB row). status: type: string enum: - SUCCEEDED - REQUIRES_ACTION - FAILED customerId: type: string paymentMethodId: type: string nullable: true threeDsChallengeUrl: type: string nullable: true createdAt: type: integer description: Epoch milliseconds. PaymentMethod: type: object description: Saved customer payment method (`CustomerPaymentMethodPublic`). properties: id: type: string example: pi_abc123 customerId: type: string type: $ref: '#/components/schemas/PaymentMethodType' brand: type: string nullable: true last4: type: string nullable: true expiryMonth: type: integer nullable: true expiryYear: type: integer nullable: true isPreferred: type: boolean revokedAt: type: string format: date-time nullable: true createdAt: type: string format: date-time PaymentMethodType: type: string enum: - CARD - APPLE_PAY - GOOGLE_PAY - KLARNA - IDEAL - BANCONTACT - TWINT - BLIK - AFFIRM - MULTIBANCO - PAYPAL - SEPA_DIRECT_DEBIT - ACH_DIRECT_DEBIT - CRYPTO Error: type: object required: - success - error properties: success: type: boolean example: false error: type: string description: Machine-readable error code. example: NOT_FOUND message: type: string example: Resource not found data: description: Optional error detail. ValidationErrorEnvelope: allOf: - $ref: '#/components/schemas/Error' - type: object properties: data: type: object properties: fieldErrors: type: array items: type: object properties: field: type: string message: type: string responses: Unauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: UNAUTHORIZED message: Invalid or missing API key NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: NOT_FOUND message: Resource not found ValidationError: description: Request failed schema validation content: application/json: schema: $ref: '#/components/schemas/ValidationErrorEnvelope' example: success: false error: VALIDATION_ERROR message: Validation failed data: fieldErrors: - field: method message: method is a required field securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Suby-Api-Key description: Secret API key. `sk_live_…` (production) or `sk_sandbox_…` (sandbox). ````