> ## 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. # End a care chat > Close a chat the cardholder has finished with or navigated away from. The conversation stops accepting messages; sending one afterwards is refused with `CARE_CHAT_ENDED`, and the cardholder starts a new chat by sending another message. No session token is required, even on a verified chat. Ending a chat touches no account data, and requiring a live session would mean a partner whose cardholder walked away could not close the chat without texting them another code first. The chat only has to belong to the calling platform. Closing a chat that is already closed is not an error: that is the state the caller asked for. Requires a token with the `VIEW` permission. ## OpenAPI ````yaml /openapi.yaml delete /care/chats/{chatId} 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: Contact Verification description: >- Endpoints for verifying a customer's email and phone via one-time codes. Required only for customers whose payment provider mandates contact verification (e.g. EU customers); other providers return 409. - name: Strong Customer Authentication description: >- Endpoints for authorizing money-movement operations that require Strong Customer Authentication. Relevant only for customers in a region where SCA is required (e.g. EU); customers outside SCA-regulated regions never see an SCA challenge and these endpoints return 409. - 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: Periodic Statements description: > Build, deliver, and evidence a Regulation E periodic statement for a customer's internal account. A statement period is a calendar month in US Central time (`America/Chicago`). A statement is issued for each customer's own USD internal account and covers their whole balance. Money received through a rule-based account appears on its owner's statement; rule-based, bulk settlement and platform-owned accounts have no statement of their own. **1. The statement — `GET /internal-accounts/{id}/balance-changes?startDate=&endDate=`** One row per change to the balance, in the order the money moved, with the opening and closing balances for the window in the same response. Page until `hasMore` is false, then assert this identity across every page before you render anything: ``` openingBalance + Σ(data[].amount) == closingBalance ``` If it does not hold, do not send the statement; contact support instead. `startDate` and `endDate` bound a half-open window `[startDate, endDate)`: for a monthly statement, pass the first instant of the month and the first instant of the following month, both in US Central time (for August 2026, `2026-08-01T00:00:00-05:00` and `2026-09-01T00:00:00-05:00`). Grid records a statement as fetched only for a window that is exactly one such month. **2. The receipt — `POST /internal-accounts/{id}/confirm-statement`** Once a month, after you have pulled and issued a period's statement, send a receipt with the `statementMonth` it covers. Grid stores it as the delivery record for that account and period. Sending it again is harmless: the first receipt's time is kept. **Timing** A window whose card settlement has not closed is refused with `409 NOT_YET_AVAILABLE` rather than answered with figures that could still change; retry once it has settled. - name: External Accounts description: >- External account management endpoints for creating and managing external bank accounts - name: Same-Currency Transfers description: >- Deprecated endpoints for transferring funds between internal and external accounts with the same currency. Use the quote endpoints under Cross-Currency Transfers instead, which now serve same-currency transfers as well. - name: Cross-Currency Transfers description: >- Endpoints for creating and confirming quotes for transfers, both same-currency and cross-currency - 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: >- Experimental 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 a card's funding source, and list card transactions. - name: Stablecoins description: >- Stablecoin issuance endpoints. Link provider accounts, register provider-created stablecoins, create direct mint/burn issuer operations, and track operation status. - name: Embedded Care description: | A support chat between the cardholder and Lightspark's care agent, driven from the partner's own app. The platform calls with its ordinary Grid credential, but the person typing is the cardholder rather than the caller, so reaching that cardholder's account takes a second proof: an SMS code they send into the chat, after which the partner carries a session token in the `X-Ls-Care-Session` header. **The surface is two routes, and verification happens inside the conversation.** 1. **Open the chat.** `POST /care/chats/{chatId}/messages` with an empty `message`, addressed to the cardholder as `Customer:`. Returns the chat's id and the agent's opening line in `reply`, which is what a chat window renders before anybody has typed. Sends no SMS, needs no `Idempotency-Key` and consumes none, and is safe to call again: a widget that reloaded gets the same chat back, this time without a `reply`. 2. **Send the cardholder's first message.** The same route with their text and an `Idempotency-Key` header. One turn runs synchronously and the agent's answer comes back in `reply`. On a chat that cannot yet reach the account this call also texts the cardholder a code, and the agent's `reply` asks for it. 3. **The cardholder sends the code as an ordinary message.** When it is correct, the response to that turn carries `sessionToken` and `expiresAt`. Send that token as the `X-Ls-Care-Session` header on every message from then on. A code that does not match is answered in `reply`, and the cardholder can simply send it again. 4. **Close the chat** with `DELETE /care/chats/{chatId}` when the cardholder is done. Every response also carries `chatEnded`, and the agent can end the chat itself: when `chatEnded` is true, the closing line is in `reply` and the chat takes no further messages, so stop sending to it. An opening addressed to that `CareChat:` answers `409 CARE_CHAT_ENDED`; address the cardholder as `Customer:` to open a new chat. **Render `redactedCustomerMessage` if present, then `reply` if present.** That one rule covers an opening, a resume and a turn. **A cardholder whose code never arrived asks the agent for another one.** The agent sends a new code to the number on file and says so in its `reply`. There is no separate route for it. **The verification fields are optional hints.** `verificationRequired` and `codeLength` let an app show a dedicated one-time-code input of the right length, marked as a one-time code so iOS and Android offer to fill it from the SMS. A partner can ignore them, since the agent asks for the code in its reply and says where it went, and the app still sends the code as an ordinary message. Step 1 is optional. A message addressed to a `Customer:` id opens that cardholder's chat if they have none, so a partner whose cardholder has just typed something spends one call rather than two. A cardholder who has not verified yet is never a `401`, because the first message from every new cardholder is unverified and a `401` there would be indistinguishable from a bad credential. On these endpoints a `401` means the platform's Grid credential is wrong, the session token presented is malformed, or a replay lacks the session token its original request required. **Verification expires, and a lost session is recoverable in the chat.** A chat reaches the cardholder's account only while its verification is newer than the session lifetime, fifteen minutes in the default deployment, which is also how long a session token lives. Past that window a message gets a fresh code, and the agent asks the cardholder to send it back inside the conversation, which hands the partner the next session token. A new message sent with no `X-Ls-Care-Session` header, or with a token past its expiry, on a chat whose verification is still current is treated the same way: the verification is cancelled before the turn runs, a new code is sent, and the agent asks for it. So a client that lost its token, or held one too long, simply keeps sending messages. Only a token that is malformed, or that was minted for another platform, chat or cardholder, is refused. Two things an integration has to get right: - **Render `redactedCustomerMessage`, never your own copy of what was typed.** Grid masks card numbers and other sensitive digit strings in it. A UI that renders its own copy of the input instead puts a card number the cardholder pasted back on their screen unmasked, and into your logs. - **The session token is returned once and is never re-readable.** No endpoint hands it back, it cannot be revoked, and it is short-lived by design. Hold it for the life of the cardholder's session. It arrives on the message response to the turn in which the cardholder sent their code, and on no other. Losing it costs the cardholder a new code, never access to the chat. Some things are absent by construction, so no integration can come to depend on them: nothing returns a transcript or an earlier turn's reply (retrying under the original `Idempotency-Key` is how an answer that was produced but not delivered is recovered; a replay requires the same session token its original request required and never carries a `sessionToken`, so a lost token is recovered by sending the cardholder's next message as a new message, which verifies them again), nothing sets a verification state, and nothing changes the number a code is sent to. Errors from these endpoints carry `code` and `reason` only (see the `CareError` schema), unlike the `Error4xx` schemas used elsewhere in this specification. paths: /care/chats/{chatId}: parameters: - name: chatId in: path description: >- The chat to close, as returned in `chatId` by `POST /care/chats/{chatId}/messages`. required: true schema: type: string example: CareChat:019542f5-b3e7-1d02-0000-000000000030 delete: tags: - Embedded Care summary: End a care chat description: > Close a chat the cardholder has finished with or navigated away from. The conversation stops accepting messages; sending one afterwards is refused with `CARE_CHAT_ENDED`, and the cardholder starts a new chat by sending another message. No session token is required, even on a verified chat. Ending a chat touches no account data, and requiring a live session would mean a partner whose cardholder walked away could not close the chat without texting them another code first. The chat only has to belong to the calling platform. Closing a chat that is already closed is not an error: that is the state the caller asked for. Requires a token with the `VIEW` permission. operationId: endCareChat responses: '204': description: The chat is closed. No content. '401': description: '`UNAUTHORIZED`: the platform''s Grid credential is missing or wrong.' content: application/json: schema: $ref: '#/components/schemas/CareError' '403': description: >- `FORBIDDEN`: the token lacks the `VIEW` permission, or embedded care is not enabled for this platform. content: application/json: schema: $ref: '#/components/schemas/CareError' '404': description: >- `NOT_FOUND`: no such chat for this platform. A chat that belongs to another platform, one that never existed, and a malformed chat id are one answer. content: application/json: schema: $ref: '#/components/schemas/CareError' '429': description: >- `RATE_LIMITED`: the platform is calling this endpoint too often. Back off for the interval in the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/CareError' '500': description: Internal service error. content: application/json: schema: $ref: '#/components/schemas/CareError' '503': description: >- `SERVICE_UNAVAILABLE` when embedded care is not available in this deployment, or the support agent is temporarily turned off. content: application/json: schema: $ref: '#/components/schemas/CareError' security: - BasicAuth: [] components: schemas: CareError: type: object description: > The error body returned by every endpoint under **Embedded Care**. It carries `code` and `reason`, and nothing else. This differs from the `Error4xx` / `Error5xx` schemas the rest of this specification uses, which declare `status` and `message`: the care endpoints do not send those two fields. Read the HTTP status from the response line and the human-readable text from `reason`. Branch on `code`, never on `reason`: the text is written for a human reading a log and may be reworded at any time. required: - code - reason properties: code: $ref: '#/components/schemas/CareErrorCode' reason: type: string description: >- Human-readable explanation, for a log or a support ticket. Not for branching, and not always safe to show a cardholder verbatim. The exception is `CARE_MESSAGE_REJECTED`, whose `reason` is written to be shown. example: The care session token is not valid. CareErrorCode: type: string description: > Machine-readable error code. Each endpoint's response descriptions say which of these it can send at which status. | Error Code | HTTP | Description | |------------|------|-------------| | `INVALID_INPUT` | 400 | The request body or headers are malformed: an unknown field, a body that is not a JSON object, a missing or over-long `Idempotency-Key` on a message that carries text, a `chatId` path id beginning `Customer:` that is not well formed, or a chat that cannot be verified at all. | | `CARE_MESSAGE_REJECTED` | 400 | The cardholder's message was refused, for example because it is too long, and no turn ran. `reason` carries the sentence to show them. | | `UNAUTHORIZED` | 401 | The platform's Grid credential is missing or wrong. On this surface a `401` never means the cardholder is unverified; that is signalled in a `200` body. | | `CARE_SESSION_EXPIRED` | 401 | The `X-Ls-Care-Session` token presented is malformed, or not a care session token at all; or a replay under an `Idempotency-Key` lacks the valid session token its original request required, in which case nothing from the record is returned. For a new message, a missing or expired token is never this error: the message verifies the cardholder again inside a `200` instead. Rarely, also returned when a verification lands on the chat at the same moment a message without a live token takes it away; send the message again. | | `FORBIDDEN` | 403 | The token lacks a permission the endpoint requires, or embedded care is not enabled for this platform. | | `CARE_SESSION_PLATFORM_MISMATCH` | 403 | The session token was minted for a different platform. Stop; retrying will not help. | | `NOT_FOUND` | 404 | No such chat for this platform. A chat belonging to another platform, a chat that never existed, a malformed chat id, and an `X-Ls-Care-Session` token minted for a different chat or a different cardholder are one answer. | | `CUSTOMER_NOT_FOUND` | 404 | No such cardholder for this platform. | | `CONFLICT` | 409 | The `Idempotency-Key` was already used for a different message or a different chat (use a new key), or the chat has no cardholder bound to it. | | `CARE_CHAT_ENDED` | 409 | The chat has ended, whether the agent ended it or it was closed, and it accepts no further messages or openings; a replay of a turn that completed or is still running is still answered. Open a new one by sending an empty message to the cardholder as `Customer:`. | | `CARE_NOT_CONFIGURED_FOR_PLATFORM` | 422 | The platform is entitled to embedded care but has no care programme configured. | | `CARE_BUDGET_EXCEEDED` | 429 | This chat has reached its limit. Opening a new chat for the cardholder does not clear it. | | `RATE_LIMITED` | 429 | The platform is calling this endpoint too often. Back off for the interval in the `Retry-After` response header. | | `INTERNAL_ERROR` | 500 | Unexpected server error. | | `CARE_TURN_FAILED` | 502 | The agent could not answer. Transient; the same `Idempotency-Key` may be sent again. | | `CARE_VERIFICATION_UNAVAILABLE` | 502 | The verification code could not be sent or checked right now. Distinct from a wrong code: the problem is temporary and not the cardholder's, so retry rather than asking them again. | | `SERVICE_UNAVAILABLE` | 503 | Embedded care is not available in this deployment, or the support agent is temporarily turned off. | | `CARE_TURN_TIMEOUT` | 504 | The turn is still running. Retry with the same `Idempotency-Key` to collect the answer. | enum: - INVALID_INPUT - CARE_MESSAGE_REJECTED - UNAUTHORIZED - CARE_SESSION_EXPIRED - FORBIDDEN - CARE_SESSION_PLATFORM_MISMATCH - NOT_FOUND - CUSTOMER_NOT_FOUND - CONFLICT - CARE_CHAT_ENDED - CARE_NOT_CONFIGURED_FOR_PLATFORM - CARE_BUDGET_EXCEEDED - RATE_LIMITED - INTERNAL_ERROR - CARE_TURN_FAILED - CARE_VERIFICATION_UNAVAILABLE - SERVICE_UNAVAILABLE - CARE_TURN_TIMEOUT example: CARE_SESSION_EXPIRED 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/redeem`. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.