> ## Documentation Index
> Fetch the complete documentation index at: https://darwin.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add payment method

> Start hosted card or bank enrollment for an immutable payment request from a thread. Check GET /v2/account/payment-method-setups/{setupId} for verified completion before using a saved method. This setup does not charge or settle the request. Standalone enrollment without a request is not available yet.

This account operation requires a user-authorized `human:actions` OAuth grant. It has no personal AI ID in its public path. Enrollment is bound to an immutable payment request and requires explicit save consent. The hosted provider collects card or bank details; this API never accepts them. A verified method can be listed under Account → Personal, but enrollment itself does not charge or settle the request.

A standalone setup without a thread request is not available yet. This integration remains release-gated until account ownership migration and live provider verification are complete.


## OpenAPI

````yaml openapi-target-accounts.json POST /v2/account/payment-method-setups
openapi: 3.1.0
info:
  title: Darwin target accounts
  version: 1.0.0
  description: >-
    Manage saved payment methods and authentication credentials for your Darwin
    account. Older AI-scoped routes remain as compatibility aliases.
servers:
  - url: https://api.darwin.so/api
    description: Darwin API after cutover
security: []
paths:
  /v2/account/payment-method-setups:
    post:
      tags:
        - Account
      summary: Add payment method
      description: >-
        Start hosted card or bank enrollment for an immutable payment request
        from a thread. Check GET /v2/account/payment-method-setups/{setupId} for
        verified completion before using a saved method. This setup does not
        charge or settle the request. Standalone enrollment without a request is
        not available yet.
      operationId: start_account_payment_method_setup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request:
                  type: string
                  minLength: 1
                  maxLength: 200
                  pattern: ^[A-Za-z0-9_-]+$
                  description: An immutable payment request from an account-owned thread.
                method:
                  type: string
                  enum:
                    - card
                    - bank
                  description: Funding method to enroll through the hosted provider.
                consent:
                  type: string
                  const: save_payment_method
                  description: Explicit permission to save the verified method.
                idempotencyKey:
                  type: string
                  minLength: 1
                  maxLength: 200
                  pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
              required:
                - request
                - method
                - consent
                - idempotencyKey
              additionalProperties: false
      responses:
        '200':
          description: Authorized account metadata only.
          content:
            application/json:
              schema:
                type: object
                properties:
                  setup:
                    type: string
                    minLength: 1
                    maxLength: 200
                    pattern: ^[A-Za-z0-9_-]+$
                  status:
                    type: string
                    enum:
                      - prepared
                      - dispatching
                      - awaiting_user
                      - processing
                      - verified
                      - failed
                      - expired
                      - cancelled
                  revision:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  expiresAt:
                    type: string
                    format: date-time
                    pattern: >-
                      ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                  url:
                    type: string
                    format: uri
                  paymentMethodId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    pattern: ^[A-Za-z0-9_-]+$
                required:
                  - setup
                  - status
                  - revision
                  - expiresAt
                additionalProperties: false
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
        '400':
          description: Invalid or unsupported input.
        '401':
          description: Authentication required.
        '403':
          description: >-
            Missing scope, owner/admin role, or AI grant. Writes require a user
            API key.
        '404':
          description: AI or account is not available to this principal.
        '409':
          description: Connection is no longer available; reconnect before selecting it.
        '429':
          description: >-
            Read allowance exceeded. Wait before retrying; changing the AI or
            MCP tool does not reset the budget.
          headers:
            Retry-After:
              description: Minimum seconds before retrying.
              schema:
                type: integer
                minimum: 1
        '503':
          description: >-
            Account thread integration or required credential custody is
            unavailable.
      security:
        - bearer: []
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.