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

# Order an international prepaid card

> Order an international non-reloadable prepaid card (USD). **Not for merchants that bill later.** Ad platforms (Google, Meta, Reddit and the like), AI and inference providers, subscriptions, and any merchant that keeps a card on file and charges it after use need the reloadable card (`POST /create-reloadable-card`). This card has a fixed balance and cannot be topped up, so those merchants decline it or fail the later charges. Ask what the card is for before ordering one.

The order is queued and fulfilled by an admin — after fulfillment, card details become available via `GET /get-card-data` with `card_type=Non-Reloadable International`.

The x402 payment covers the on-card amount plus a 3.8% fee, or a lower rate while a limited-time fee promotion is running (it can be 0%). The 402 challenge always carries the exact total. Minimum \$100, maximum \$1,000 on-card amount. The \$1,000 maximum is the amount loaded on the card and does not change with the fee rate. Submit a whole dollar amount.

Placing the order accepts the card issuer's terms on behalf of the account holder: the [Cardholder Agreement](https://laso.finance/intl-card-cardholder-agreement.pdf), the [E-Communications Disclosure](https://laso.finance/intl-card-e-communications-disclosure.pdf), and the [Privacy Notice](https://laso.finance/intl-card-privacy-notice.pdf). 

If you need to cancel a queued order before it is fulfilled, use `POST /cancel-intl-order`.



## OpenAPI

````yaml /api-reference/openapi.json get /order-intl-card
openapi: 3.1.0
info:
  title: Laso Finance x402 API
  version: 1.0.0
  x-docs-revision: 247ccb45e4cd
  x-docs-manifest: https://laso.finance/.well-known/docs-version.json
  termsOfService: https://laso.finance/agent-terms.md
  contact:
    email: agents+support@laso.finance
  x-guidance: >-
    Laso Finance is a payment-gated (x402) API that lets an AI agent spend USDC
    on real-world financial products: prepaid cards (U.S. and international),
    gift cards, push-to-card transfers to USD/EUR/GBP debit cards, and
    Venmo/PayPal payouts.


    Payment: every paid route is an x402 v2 endpoint. Call it with no payment
    header to receive a 402 challenge listing the accepted networks, then replay
    with a signed USDC payment. Both Base (eip155:8453) and Solana
    (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) are accepted on every paid route;
    the caller picks either chain.


    Identity: `GET /auth` is free and identity-only. Prove wallet ownership with
    a `SIGN-IN-WITH-X` (CAIP-122) header to receive a Firebase id_token, then
    send that token as a Bearer credential to the authenticated read routes
    (`get-card-data`, `get-account-balance`, `get-kyc-status`, etc.). Paid
    routes also return fresh auth credentials in their response, so a payment is
    never required just to obtain a token.


    Recommended flow: (1) `GET /auth` to establish identity, (2) call a paid
    route (e.g. `GET /get-card`) to purchase a product, paying USDC on Base or
    Solana, (3) poll the authenticated read routes with the returned Bearer
    token to fetch the resulting card/transfer details. Reloadable card setup:
    the account holder links the card issuer once. Check `GET
    /get-card-issuer-status`; if it is `not_started`, call `POST
    /start-card-issuer-link` so the card issuer sends the account holder a
    one-time code, have the HUMAN read it from their own inbox and enter it in
    your interface (never read their email yourself), then `POST
    /verify-card-issuer-link` with the code and `consent_accepted: true`.
    Linking requires Laso identity verification (`kyc_required` returns a
    `kyc_url` for the human). Then fund with `GET /fund-card-balance` and create
    cards with `POST /create-reloadable-card`. Full machine-readable
    instructions live at https://laso.finance/SKILL.md.
  description: >-
    Payment-gated API for Laso Finance. All paywalled routes use the x402
    protocol — the caller includes a USDC payment header on Base (eip155:8453)
    or Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) and the server verifies
    payment before processing. Free routes require no payment header. The same
    402 also carries an MPP (Machine Payments Protocol) challenge in
    WWW-Authenticate; an MPP client pays with USDC on Base by replaying with
    `Authorization: Payment ...`, and routes, prices, and responses are
    identical.


    ## Getting started


    To set up a wallet for making x402 payments, choose a provider:


    - **Locus** (default): https://paywithlocus.com/SKILL.md

    - **Sponge**: https://wallet.paysponge.com/skill.md — automatic x402 service
    discovery

    - **Ampersend**: https://www.ampersend.ai/getting-started.md — self-custody
    on Base or Solana with dual-approval spending limits. Laso Finance is a
    default skill, so no manual endpoint registration is needed.


    ## How x402 works


    1. Call a paywalled endpoint without a payment header → receive a `402
    Payment Required` response containing payment details (price, recipient
    address, network).

    2. Construct an x402 payment header using the details from the 402 response.

    3. Replay the request with the payment header → the server verifies payment
    and processes the request.


    ## Authentication flow


    `GET /auth` is free: callers prove wallet ownership by sending a
    `SIGN-IN-WITH-X` header (CAIP-122 wallet signature). Paywalled routes
    (`/get-card`, `/order-gift-card`, `/get-push-to-card`, `/order-intl-card`)
    also return fresh auth credentials in their responses, so a payment is never
    required just to obtain a token.


    Most routes return auth credentials (`id_token`, `refresh_token`,
    `expires_in`). Use the `id_token` as a Bearer token to call authenticated
    Laso Finance endpoints like `/get-card-data`. When the `id_token` expires,
    use `POST /auth` with `grant_type: refresh_token` to get a new one.


    ## Important notes


    The `/get-card` USA prepaid card endpoint is U.S. only — issued in USD,
    usable at U.S.-based merchants only, and physical goods must ship to a U.S.
    address. For non-U.S. merchants or non-USD currencies, use `GET
    /order-intl-card` instead (international prepaid card, admin-fulfilled
    within 24 hours). Agents act for a principal (a person 18+ or a business
    entity) under the [Agent Terms](https://laso.finance/agent-terms.md): every
    action is treated as the principal's own, and cards may be used for the
    principal's personal or business purchases.


    ## Rate limits


    Every response carries the request budget so you can pace yourself without
    probing for a limit:


    | Header | Meaning |

    | --- | --- |

    | `RateLimit-Limit` | Requests permitted per window |

    | `RateLimit-Remaining` | Requests still available |

    | `RateLimit-Reset` | Seconds until the window rolls over |

    | `RateLimit-Policy` | The policy these numbers describe, as
    `limit;w=seconds` |


    The same values are repeated as `X-RateLimit-*` for clients that only parse
    that spelling.


    Most routes advertise the service-wide ceiling. `POST /signup` enforces its
    own per-IP budget on top of it and overwrites these headers with its own
    numbers. `POST /refresh-card-data` is limited per card rather than per
    caller, so its headers keep the service-wide values and the per-card budget
    is reported only on rejection.


    Every rejection is a `429` carrying `Retry-After` in seconds and a matching
    `retry_after_seconds` field in the body, computed from the limit that
    actually rejected the request. Wait that long and retry once. Do not retry
    in a tight loop.


    ## API versioning


    Every response carries the contract version in an `X-Laso-Api-Version`
    header, and `GET /version` returns the same value as `api_version` alongside
    the policy below in machine-readable form. It is distinct from
    `X-Laso-Docs-Version`, which tracks the prose and moves whenever the
    documentation changes.


    | Change | What happens to `api_version` |

    | --- | --- |

    | New route, new optional request field, new response field | Unchanged.
    Tolerate unknown response fields. |

    | Breaking change | Ships under a new `api_version`. |


    A route being retired is marked `deprecated` in this description and answers
    with a `Deprecation: true` response header, plus a `Link` header with
    `rel="successor-version"` pointing at its replacement. Once a removal date
    is set it is published in a `Sunset` header (RFC 9745 / RFC 8594). There is
    no blanket notice period: the `Sunset` date on each deprecated route is the
    commitment.


    For step-by-step instructions, read https://laso.finance/SKILL.md
servers:
  - url: https://laso.finance
    description: Production
security: []
paths:
  /order-intl-card:
    get:
      summary: Order an international prepaid card
      description: >-
        Order an international non-reloadable prepaid card (USD). **Not for
        merchants that bill later.** Ad platforms (Google, Meta, Reddit and the
        like), AI and inference providers, subscriptions, and any merchant that
        keeps a card on file and charges it after use need the reloadable card
        (`POST /create-reloadable-card`). This card has a fixed balance and
        cannot be topped up, so those merchants decline it or fail the later
        charges. Ask what the card is for before ordering one.


        The order is queued and fulfilled by an admin — after fulfillment, card
        details become available via `GET /get-card-data` with
        `card_type=Non-Reloadable International`.


        The x402 payment covers the on-card amount plus a 3.8% fee, or a lower
        rate while a limited-time fee promotion is running (it can be 0%). The
        402 challenge always carries the exact total. Minimum \$100, maximum
        \$1,000 on-card amount. The \$1,000 maximum is the amount loaded on the
        card and does not change with the fee rate. Submit a whole dollar
        amount.


        Placing the order accepts the card issuer's terms on behalf of the
        account holder: the [Cardholder
        Agreement](https://laso.finance/intl-card-cardholder-agreement.pdf), the
        [E-Communications
        Disclosure](https://laso.finance/intl-card-e-communications-disclosure.pdf),
        and the [Privacy
        Notice](https://laso.finance/intl-card-privacy-notice.pdf). 


        If you need to cancel a queued order before it is fulfilled, use `POST
        /cancel-intl-order`.
      operationId: orderIntlCard
      parameters:
        - name: amount
          in: query
          required: true
          description: >-
            On-card USD amount (min \$100, max \$1,000 regardless of the fee
            rate). Must be a whole dollar amount: the issuer only issues
            whole-dollar cards. The x402 payment is this amount plus a 3.8% fee,
            or less during a fee promotion.
          schema:
            type: number
            minimum: 100
            maximum: 1000
      responses:
        '200':
          description: International card order queued
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth:
                    $ref: '#/components/schemas/AuthCredentials'
                  callable_base_url:
                    type: string
                  user_id:
                    type: string
                  intl_card_order:
                    type: object
                    properties:
                      card_id:
                        type: string
                        description: >-
                          Id of the queued order. Pass it as `card_id` to `GET
                          /get-card-data` to poll for the card details, or to
                          `POST /cancel-intl-order` while the order is still
                          queued.
                        example: '1706400000000'
                      on_card_usd_amount:
                        type: number
                      charged_usd_amount:
                        type: number
                      status:
                        type: string
                        example: queued
                      timestamp:
                        type: number
                  message:
                    type: string
          headers:
            X-Laso-Api-Version:
              $ref: '#/components/headers/X-Laso-Api-Version'
        '400':
          description: Invalid amount
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Amount must be at least $100. Received: $50'
          headers:
            X-Laso-Api-Version:
              $ref: '#/components/headers/X-Laso-Api-Version'
        '402':
          description: >-
            Payment required. No valid x402 payment header was included. The
            payment details (price, recipient address, network) are
            base64-encoded in the `PAYMENT-REQUIRED` response header and echoed
            as JSON in the response body. x402 client libraries handle this
            automatically. A **second** 402 on the paid retry means something
            different: the payment was refused, either at verification (most
            often an underfunded wallet) or at on-chain settlement. That
            response body is not empty and carries no `accepts` — it is the x402
            settlement-failure shape `{"success": false, "errorReason": "...",
            "errorMessage": "..."}`, plus `x_laso_guidance` when a concrete next
            step applies. Distinguish the two by body: a challenge carries
            `accepts`, a failure carries `success: false`. The usual cause is an
            underfunded wallet, and the usual cause of that is the fee being
            charged **on top of** `amount` on routes that add one (a wallet
            holding exactly \$2,000 cannot send a \$2,000 bank payment;
            `/get-card` adds no fee, so it costs exactly `amount`). Nothing is
            charged for a failed settlement, so retrying with a smaller amount
            is safe.
          content:
            application/json:
              schema:
                type: object
                example: {}
          headers:
            X-Laso-Api-Version:
              $ref: '#/components/headers/X-Laso-Api-Version'
        '403':
          description: >-
            Account is frozen. The response includes a `frozen_message` field
            explaining why.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FrozenError'
              example:
                error: Account is frozen
                frozen_message: >-
                  Your account is frozen pending a compliance review. Contact
                  support@laso.finance.
          headers:
            X-Laso-Api-Version:
              $ref: '#/components/headers/X-Laso-Api-Version'
        '500':
          description: Order failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Failed to order international card. Please contact support.
          headers:
            X-Laso-Api-Version:
              $ref: '#/components/headers/X-Laso-Api-Version'
components:
  schemas:
    AuthCredentials:
      type: object
      properties:
        id_token:
          type: string
          description: ID token — use as Bearer token for Laso Finance APIs
        refresh_token:
          type: string
          description: >-
            Use with POST /auth (grant_type=refresh_token) to get a new id_token
            when it expires
        expires_in:
          type: string
          description: Token lifetime in seconds
    Error:
      type: object
      properties:
        error:
          type: string
    FrozenError:
      type: object
      properties:
        error:
          type: string
          example: Account is frozen
        frozen_message:
          type: string
          description: Human-readable explanation of why the account is frozen
  headers:
    X-Laso-Api-Version:
      description: >-
        The version of the API contract that produced this response, the same
        value `GET /version` returns as `api_version`. It moves only on a
        breaking change, so an agent can pin against it and tolerate unknown
        response fields without rechecking the docs. Distinct from
        `X-Laso-Docs-Version`, which tracks the prose. Present on every response
        once the service has read its version beacon; absent, rather than a
        placeholder, during the cold-start window before that read completes.
      schema:
        type: string
        example: 1.0.0

````

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