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

# Create a payment intent (v2)

> Create a provider-agnostic payment intent using a flat action shape.

Supported matrix:
- source: Grid account funding leg
- destination: synced external account for the internally selected provider
- rails: `SWIFT` destination rail

Action fields are top-level and stable across modes:
- `deposit`: funding instructions (address or bank fields)
- `sign_prebuilt_tx`: transaction to sign and broadcast
- `next_action`: optional follow-up hint for multi-step flows



## OpenAPI

````yaml https://grid.squads.xyz/api-docs/openapi.json post /api/grid/v1/accounts/{address}/payment-intents
openapi: 3.1.0
info:
  title: Grid v1 API
  description: Grid v1 REST API for Solana-based smart account system
  contact:
    name: Grid API Support
    url: https://squads.so
    email: support@squads.so
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://grid.squads.xyz
    description: Production server
security:
  - bearer_auth: []
tags:
  - name: accounts
    description: Smart account management operations
  - name: spending-limits
    description: Spending limit management
  - name: standing-orders
    description: Standing order operations
  - name: transactions
    description: Transaction management
  - name: trade
    description: Trade operations and management
  - name: payments
    description: Payment intent operations
  - name: passkeys
    description: Passkey management
  - name: kyc
    description: Know Your Customer operations
  - name: external-accounts
    description: External bank account management
  - name: virtual-accounts
    description: Virtual account management
  - name: auth
    description: Authentication operations
  - name: proposals
    description: Proposal management for multi-sig operations
  - name: compliance
    description: Compliance entity management and KYB/KYC operations
paths:
  /api/grid/v1/accounts/{address}/payment-intents:
    post:
      tags:
        - payments
      summary: Create a payment intent (v2)
      description: >-
        Create a provider-agnostic payment intent using a flat action shape.


        Supported matrix:

        - source: Grid account funding leg

        - destination: synced external account for the internally selected
        provider

        - rails: `SWIFT` destination rail


        Action fields are top-level and stable across modes:

        - `deposit`: funding instructions (address or bank fields)

        - `sign_prebuilt_tx`: transaction to sign and broadcast

        - `next_action`: optional follow-up hint for multi-step flows
      operationId: handler
      parameters:
        - name: address
          in: path
          description: Smart account address
          required: true
          schema:
            type: string
        - name: x-grid-environment
          in: header
          description: Environment (sandbox, production)
          required: true
          schema:
            type: string
        - name: x-idempotency-key
          in: header
          description: >-
            Idempotency key forwarded to the provider (auto-generated when
            omitted)
          required: false
          schema:
            type:
              - string
              - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentIntentV2RequestPayload'
        required: true
      responses:
        '201':
          description: Payment intent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentIntentV2Response'
        '400':
          description: >-
            Invalid request (for example: amount format, unsupported destination
            rail, missing provider mappings, or provider validation errors)
        '403':
          description: Enterprise scope required
        '404':
          description: Smart account or destination external account not found
        '503':
          description: Provider unavailable or not configured for the selected environment
      security:
        - bearer_auth: []
components:
  schemas:
    CreatePaymentIntentV2RequestPayload:
      type: object
      required:
        - amount
        - source
        - destination
      properties:
        amount:
          type: string
          description: >-
            Integer amount in source currency smallest units (for example, 1
            USDC = `1000000` when exponent is 6).
          example: '100000000'
        client_reference_id:
          type:
            - string
            - 'null'
          description: Optional caller-defined reference for reconciliation.
          example: invoice-2026-001
        destination:
          $ref: '#/components/schemas/DestinationPayload'
          description: Destination leg details.
        document_ids:
          type: array
          items:
            type: string
          description: >-
            Optional provider document identifiers (for example, for third-party
            payouts requiring supporting docs).
          example:
            - doc_abc123
          nullable: true
        fees:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FeePayload'
              description: >-
                Optional fee controls; forwarded to providers that support fee
                fields.
        memo:
          type:
            - string
            - 'null'
          description: Free-form memo/reference.
          example: 'Invoice #2026-001'
        mode:
          $ref: '#/components/schemas/IntentMode'
          description: Intent mode. Defaults to `destination_address`.
        payment_reason:
          type:
            - string
            - 'null'
          description: Provider payment reason enum string. Forwarded when supported.
          example: PAYMENT_FOR_GOODS_AND_SERVICES
        remarks:
          type:
            - string
            - 'null'
          description: >-
            Provider remarks forwarded to providers that support a dedicated
            remarks field.
          example: Payable for March settlement
        source:
          $ref: '#/components/schemas/SourcePayload'
          description: Source leg details.
    CreatePaymentIntentV2Response:
      type: object
      required:
        - id
        - object
        - provider
        - mode
        - status
        - source
        - destination
        - source_amount
        - created_at
        - updated_at
      properties:
        created_at:
          type: string
          description: RFC3339 creation timestamp.
          example: '2026-03-05T08:14:01Z'
        deposit:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/DepositActionPayload'
              description: >-
                Flat deposit action. Present when caller needs to transfer funds
                using returned instructions.
        destination:
          $ref: '#/components/schemas/PartyPayload'
          description: Normalized destination party details.
        destination_amount:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/AmountPayload'
              description: Destination amount breakdown when returned by provider.
        id:
          type: string
          description: Payment intent identifier.
          example: pi_tfr_9w7d3m2a
        mode:
          $ref: '#/components/schemas/IntentMode'
          description: Requested intent mode.
        next_action:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/NextActionPayload'
              description: >-
                Optional hint for additional follow-up action in future
                multi-step flows.
        object:
          type: string
          description: Resource type.
          example: payment_intent
        provider:
          type: string
          description: Provider that executed the request.
          example: infinite
        provider_fields:
          type: object
          description: Provider-specific raw attributes for advanced integrations.
        sign_prebuilt_tx:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/SignPrebuiltTxPayload'
              description: >-
                Flat signing action. Present when caller must sign and broadcast
                a prepared transaction.
        source:
          $ref: '#/components/schemas/PartyPayload'
          description: Normalized source party details.
        source_amount:
          $ref: '#/components/schemas/AmountPayload'
          description: Source amount breakdown.
        status:
          type: string
          description: Provider-backed payment intent status.
          example: pending
        updated_at:
          type: string
          description: RFC3339 update timestamp.
          example: '2026-03-05T08:14:01Z'
    DestinationPayload:
      type: object
      required:
        - currency
        - payment_rail
        - external_account_id
      properties:
        currency:
          type: string
          description: Destination currency ticker.
          example: USD
        external_account_id:
          type: string
          description: >-
            Grid external account UUID. The handler resolves and maps this to
            the provider external account ID.
          example: 6f4f23d5-5ca8-4c62-92f8-9d730f89adf4
        payment_rail:
          type: string
          description: Destination payment rail.
          example: SWIFT
        reference:
          type:
            - string
            - 'null'
          description: Provider-facing destination reference (for example SWIFT reference).
          example: 'Invoice #2026-001'
    FeePayload:
      type: object
      properties:
        developer_fee_fixed:
          type:
            - integer
            - 'null'
          format: int64
          description: Fixed fee in smallest units.
          example: 10000
          minimum: 0
        developer_fee_percent:
          type:
            - number
            - 'null'
          format: double
          description: Percentage fee represented as a decimal fraction.
          example: 0.015
    IntentMode:
      type: string
      enum:
        - destination_address
    SourcePayload:
      type: object
      required:
        - currency
        - payment_rail
      properties:
        account_id:
          type:
            - string
            - 'null'
          description: >-
            Optional provider account identifier when the provider requires an
            explicit source account.
          example: ewa_abc123
        currency:
          type: string
          description: Source currency ticker.
          example: USDC
        payment_rail:
          type: string
          description: Source payment rail/network.
          example: SOLANA
    DepositActionPayload:
      type: object
      required:
        - deposit_type
        - payment_rail
        - amount
      properties:
        account_id:
          type:
            - string
            - 'null'
          description: Provider account ID to credit, when applicable.
          example: eba_abc123
        account_number:
          type:
            - string
            - 'null'
          description: Beneficiary account number.
          example: '1234567890'
        amount:
          $ref: '#/components/schemas/AmountPayload'
          description: Required deposit amount.
        bank_address_line:
          type:
            - string
            - 'null'
          description: Beneficiary bank address line.
          example: 270 PARK AVENUE, NEW YORK, NY
        bank_name:
          type:
            - string
            - 'null'
          description: Beneficiary bank name.
          example: JPMORGAN CHASE BANK
        beneficiary_name:
          type:
            - string
            - 'null'
          description: Beneficiary legal name.
          example: Acme Corp
        clabe:
          type:
            - string
            - 'null'
          description: CLABE for supported MX rails.
          example: '002010077777777771'
        deposit_type:
          type: string
          description: Deposit instruction type.
          example: fiat
        iban:
          type:
            - string
            - 'null'
          description: IBAN for IBAN-supported destinations.
          example: GB33BUKB20201555555555
        memo:
          type:
            - string
            - 'null'
          description: Deposit memo/tag/reference for blockchain or fiat rails.
          example: Payment reference
        payment_rail:
          type: string
          description: Deposit rail.
          example: SWIFT
        reference:
          type:
            - string
            - 'null'
          description: Provider/reference field for payout reconciliation.
          example: 'Invoice #2026-001'
        routing_number:
          type:
            - string
            - 'null'
          description: Routing number for rails that require it.
          example: '021000021'
        swift_bic:
          type:
            - string
            - 'null'
          description: SWIFT/BIC code.
          example: CHASUS33
        to_address:
          type:
            - string
            - 'null'
          description: Deposit destination address for blockchain rails.
          example: 8B57MCi1FX7ydB5SJUbWT5FWUwoHT88JsEfSFwNx32CV
    PartyPayload:
      type: object
      required:
        - currency
        - payment_rail
      properties:
        account_id:
          type:
            - string
            - 'null'
          description: Provider account ID when available.
          example: ewa_abc123
        address:
          type:
            - string
            - 'null'
          description: On-chain destination/source address when available.
          example: 8B57MCi1FX7ydB5SJUbWT5FWUwoHT88JsEfSFwNx32CV
        currency:
          type: string
          description: Party currency.
          example: USDC
        external_account_id:
          type:
            - string
            - 'null'
          description: External account ID when available.
          example: eba_abc123
        payment_rail:
          type: string
          description: Party payment rail.
          example: SOLANA
    AmountPayload:
      type: object
      required:
        - currency
        - exponent
        - value
        - display_value
      properties:
        currency:
          type: string
          description: Currency ticker.
          example: USDC
        display_value:
          type: string
          description: Human-readable decimal amount.
          example: '1.000000'
        exponent:
          type: integer
          format: int32
          description: Decimal exponent used for display conversion.
          example: 6
          minimum: 0
        value:
          type: string
          description: Integer amount in smallest units.
          example: '1000000'
    NextActionPayload:
      type: object
      required:
        - action_type
      properties:
        action_type:
          type: string
          description: Action discriminator.
          example: await_funding
    SignPrebuiltTxPayload:
      type: object
      required:
        - encoding
        - transaction
      properties:
        encoding:
          type: string
          description: Transaction encoding.
          example: base64
        transaction:
          type: string
          description: Serialized transaction payload.
          example: >-
            AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAED...
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: Your Grid API key from the Grid Dashboard

````