> ## Documentation Index > Fetch the complete documentation index at: https://docs.lightspark.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a card > Retrieve a card by its system-generated id. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/grid/openapi.documented.yml get /cards/{id} openapi: 3.1.0 info: title: Grid API description: > API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/. version: '2025-10-13' contact: name: Lightspark Support email: support@lightspark.com license: name: Proprietary url: https://lightspark.com/terms servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server security: - BasicAuth: [] - AgentAuth: [] tags: - name: Platform Configuration description: >- Platform configuration endpoints for managing global settings. You can also configure these settings in the Grid dashboard. - name: Customers description: >- Customer management endpoints for creating and updating customer information - name: KYC/KYB Verifications description: >- Endpoints for Know Your Customer (KYC) and Know Your Business (KYB) verification, including managing beneficial owners and triggering verification for customers. - name: Documents description: >- Endpoints for uploading and managing verification documents for customers and beneficial owners. Supports KYC and KYB document requirements. - name: Internal Accounts description: >- Internal account management endpoints for creating and managing internal accounts - name: External Accounts description: >- External account management endpoints for creating and managing external bank accounts - name: Same-Currency Transfers description: >- Endpoints for transferring funds between internal and external accounts with the same currency - name: Cross-Currency Transfers description: Endpoints for creating and confirming quotes for cross-currency transfers - name: Transactions description: Endpoints for retrieving transaction information - name: Webhooks description: Webhook endpoints and configuration for receiving notifications - name: Invitations description: Endpoints for creating, claiming and managing UMA invitations - name: Sandbox description: Endpoints to trigger test cases in sandbox - name: API Tokens description: Endpoints to programmatically manage API tokens - name: Exchange Rates description: >- Endpoints for retrieving cached foreign exchange rates. Rates are cached for approximately 5 minutes and include platform-specific fees. - name: Discoveries description: >- Endpoints for discovering available payment rails, banks, and providers for a given country and currency corridor. - name: Embedded Wallet Auth description: >- Endpoints for registering and verifying end-user authentication credentials (email OTP, OAuth, passkey) used to sign Embedded Wallet actions. - name: Agent Management description: >- Endpoints for creating and managing agents (experimental), called by the partner's backend using platform credentials. Covers the full agent lifecycle: creation, policy configuration, pausing, deletion, the device code installation flow, and approving or rejecting transactions initiated by agents. - name: Agent Operations description: >- Endpoints called by the agent itself using its own credentials (obtained via device code redemption). Scoped to the agent's associated customer — all requests automatically operate on behalf of that customer and are subject to the agent's policy. When an action requires approval, the resulting transaction enters a pending state and must be approved by the platform via `POST /transactions/{transactionId}/approve`. - name: Cards description: >- Card management endpoints. Issue debit cards against an internal account, freeze / unfreeze, close, manage card funding sources, and list card transactions. paths: /cards/{id}: parameters: - name: id in: path description: System-generated unique card identifier required: true schema: type: string get: tags: - Cards summary: Get a card description: Retrieve a card by its system-generated id. operationId: getCardById responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Card' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '404': description: Card not found content: application/json: schema: $ref: '#/components/schemas/Error404' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' '501': description: >- Not implemented in this environment. Cards are not enabled for every Grid deployment; environments without a configured card issuer return `501 NOT_IMPLEMENTED`. content: application/json: schema: $ref: '#/components/schemas/Error501' security: - BasicAuth: [] x-codeSamples: - lang: JavaScript source: |- import LightsparkGrid from '@lightsparkdev/grid'; const client = new LightsparkGrid({ username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted }); const card = await client.cards.retrieve('id'); console.log(card.id); - lang: Python source: |- import os from grid import LightsparkGrid client = LightsparkGrid( username=os.environ.get("GRID_CLIENT_ID"), # This is the default and can be omitted password=os.environ.get("GRID_CLIENT_SECRET"), # This is the default and can be omitted ) card = client.cards.retrieve( "id", ) print(card.id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stainless-sdks/grid-go\"\n\t\"github.com/stainless-sdks/grid-go/option\"\n)\n\nfunc main() {\n\tclient := grid.NewClient(\n\t\toption.WithUsername(\"My Username\"),\n\t\toption.WithPassword(\"My Password\"),\n\t)\n\tcard, err := client.Cards.Get(context.TODO(), \"id\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", card.ID)\n}\n" - lang: Kotlin source: |- package com.lightspark.grid.example import com.lightspark.grid.client.LightsparkGridClient import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient import com.lightspark.grid.models.cards.Card import com.lightspark.grid.models.cards.CardRetrieveParams fun main() { val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv() val card: Card = client.cards().retrieve("id") } - lang: Ruby source: >- require "grid" lightspark_grid = Grid::Client.new(username: "My Username", password: "My Password") card = lightspark_grid.cards.retrieve("id") puts(card) - lang: PHP source: |- cards->retrieve('id'); var_dump($card); } catch (APIException $e) { echo $e->getMessage(); } - lang: C# source: |- using System; using Grid; using Grid.Models.Cards; LightsparkGridClient client = new(); CardRetrieveParams parameters = new() { ID = "id" }; var card = await client.Cards.Retrieve(parameters); Console.WriteLine(card); - lang: CLI source: |- grid cards retrieve \ --username 'My Username' \ --password 'My Password' \ --id id components: schemas: Card: type: object required: - id - cardholderId - state - form - fundingSources - createdAt - updatedAt properties: id: type: string description: System-generated unique card identifier readOnly: true example: Card:019542f5-b3e7-1d02-0000-000000000010 cardholderId: type: string description: The id of the `Customer` who holds this card. example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCardId: type: string description: >- Platform-specific card identifier. Optional on create — system-generated if omitted, mirroring `platformCustomerId` semantics. example: card-emp-aary-001 state: $ref: '#/components/schemas/CardState' stateReason: anyOf: - $ref: '#/components/schemas/CardStateReason' - type: 'null' description: >- Reason associated with the current `state`. Populated when the card is `CLOSED` or when provisioning was rejected; otherwise null. brand: $ref: '#/components/schemas/CardBrand' form: $ref: '#/components/schemas/CardForm' last4: type: string description: Last four digits of the card PAN. example: '4242' expMonth: type: integer minimum: 1 maximum: 12 description: Card expiration month (1–12). example: 12 expYear: type: integer description: Card expiration year (four digits). example: 2029 panEmbedUrl: type: string format: uri description: >- URL of the card issuer's iframe that securely displays the PAN, CVV, and expiry to the cardholder. The full PAN and CVV never cross Grid's servers — render this URL in an iframe in your client to reveal card details. example: https://embed.lithic.com/iframe/...?t=... fundingSources: type: array description: >- Internal account ids bound to this card as funding sources, in priority order — the first entry is tried first by Authorization Decisioning. Every card has at least one funding source. items: type: string example: - InternalAccount:019542f5-b3e7-1d02-0000-000000000002 - InternalAccount:019542f5-b3e7-1d02-0000-000000000003 currency: type: string description: >- Currency the card transacts in (ISO 4217 for fiat, tickers for crypto). Derived from the funding sources at issue time — all funding sources bound to a card must be denominated in the same card-eligible currency. example: USD readOnly: true issuerRef: type: string description: >- Opaque identifier for the card on the underlying issuer. Useful for cross-referencing in issuer dashboards; not used for any Grid request routing. example: lithic_card_4f8d3a2b1c readOnly: true createdAt: type: string format: date-time description: Creation timestamp readOnly: true example: '2026-05-08T14:10:00Z' updatedAt: type: string format: date-time description: Last update timestamp readOnly: true example: '2026-05-08T14:11:00Z' Error401: type: object required: - message - status - code properties: status: type: integer enum: - 401 description: HTTP status code code: type: string description: > | Error Code | Description | |------------|-------------| | UNAUTHORIZED | Issue with API credentials | | INVALID_SIGNATURE | Signature header is invalid | | WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied | | WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) | | WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received | | WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential | | REQUEST_ID_MISSING | The `Request-Id` header is required on the signed retry but was not supplied (paired with `Grid-Wallet-Signature`) | enum: - UNAUTHORIZED - INVALID_SIGNATURE - WALLET_SIGNATURE_MISSING - WALLET_SIGNATURE_MALFORMED - WALLET_SIGNATURE_BODY_MISMATCH - WALLET_SIGNATURE_INVALID - REQUEST_ID_MISSING message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error404: type: object required: - message - status - code properties: status: type: integer enum: - 404 description: HTTP status code code: type: string description: > | Error Code | Description | |------------|-------------| | TRANSACTION_NOT_FOUND | Transaction not found | | INVITATION_NOT_FOUND | Invitation not found | | USER_NOT_FOUND | Customer not found | | QUOTE_NOT_FOUND | Quote not found | | LOOKUP_REQUEST_NOT_FOUND | Lookup request not found | | TOKEN_NOT_FOUND | Token not found | | BULK_UPLOAD_JOB_NOT_FOUND | Bulk upload job not found | | REFERENCE_NOT_FOUND | Reference not found | | UMA_NOT_FOUND | The UMA address is well-formed but no receiver exists at the counterparty VASP | enum: - TRANSACTION_NOT_FOUND - INVITATION_NOT_FOUND - USER_NOT_FOUND - QUOTE_NOT_FOUND - LOOKUP_REQUEST_NOT_FOUND - TOKEN_NOT_FOUND - BULK_UPLOAD_JOB_NOT_FOUND - REFERENCE_NOT_FOUND - UMA_NOT_FOUND message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error500: type: object required: - message - status - code properties: status: type: integer enum: - 500 description: HTTP status code code: type: string description: | | Error Code | Description | |------------|-------------| | GRID_SWITCH_ERROR | Grid switch error | | INTERNAL_ERROR | Internal server or UMA error | enum: - GRID_SWITCH_ERROR - INTERNAL_ERROR message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error501: type: object required: - message - status - code properties: status: type: integer enum: - 501 description: HTTP status code code: type: string description: > | Error Code | Description | |------------|-------------| | UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY | Unrecognized mandatory payee data key | | NOT_IMPLEMENTED | Feature not implemented | enum: - UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY - NOT_IMPLEMENTED message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true CardState: type: string enum: - PENDING_KYC - PENDING_ISSUE - ACTIVE - FROZEN - CLOSED description: > Lifecycle state of a card. | State | Description | |-------|-------------| | `PENDING_KYC` | The cardholder has not yet completed KYC. Cards in this state cannot transact. | | `PENDING_ISSUE` | The card has been requested and is being provisioned with the issuer. | | `ACTIVE` | The card is live and can authorize transactions. | | `FROZEN` | The card is temporarily disabled by the platform. New authorizations are declined with `CARD_PAUSED`. Existing settlements and refunds continue to reconcile. | | `CLOSED` | The card is permanently closed. Terminal, irreversible state. | CardStateReason: type: string enum: - ISSUER_REJECTED - CLOSED_BY_PLATFORM - CLOSED_BY_GRID description: > Reason a card reached a terminal or non-active state. Present on `CLOSED` cards, and on cards that fail provisioning before reaching `ACTIVE`. | Reason | Description | |--------|-------------| | `ISSUER_REJECTED` | The card issuer rejected provisioning during `PENDING_ISSUE`. | | `CLOSED_BY_PLATFORM` | The card was closed via `PATCH /cards/{id}` (`state: CLOSED`) by the platform. | | `CLOSED_BY_GRID` | The card was closed by Grid (e.g. compliance or risk action). | CardBrand: type: string enum: - VISA - MASTERCARD description: | Card network brand. Read-only — determined by Grid when the card is provisioned with the issuer. CardForm: type: string enum: - VIRTUAL description: | Physical form factor of the card. Only `VIRTUAL` is supported in v1; `PHYSICAL` will be added in a later release. securitySchemes: BasicAuth: type: http scheme: basic description: >- API token authentication using format `:` AgentAuth: type: http scheme: bearer description: >- Bearer token authentication for agent-scoped endpoints. The token is the `accessToken` returned when redeeming a device code via `POST /agents/device-codes/{code}/redeem`. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy. ````