LIlightsparkdev
Internal Accounts

Update internal account

Changed on

Update mutable fields on an internal account. Today this supports updating the wallet privacy setting for an Embedded Wallet internal account.

Updating wallet privacy is a two-step signed-retry flow:

  1. Call PATCH /internal-accounts/{id} with the request body { "privateEnabled": true } and no signature headers. Grid returns 202 with payloadToSign, requestId, and expiresAt.

  2. Use the session API keypair of a verified authentication credential on the same internal account to build an API-key stamp over payloadToSign, then retry with that full stamp as the Grid-Wallet-Signature header and the requestId echoed back as the Request-Id header. The retry body must carry the same update fields submitted in step 1. The signed retry returns 200 with the updated internal account.

patch/internal-accounts/{id}

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}
  • Auth
    HTTP basic

Headers

Grid-Wallet-Signaturestring

Full API-key stamp built over the prior payloadToSign with the session API keypair of a verified authentication credential on the target internal account. Required on the signed retry; ignored on the initial call.

Request-Idstring

The requestId returned in a prior 202 response, echoed back on the signed retry so the server can correlate it with the issued challenge. Required on the signed retry; must be paired with Grid-Wallet-Signature.

Request body

privateEnabledboolean

Whether wallet privacy should be enabled for the Embedded Wallet.

Example request

{
  "privateEnabled": true
}

Response

Signed retry accepted. Returns the updated internal account.

idstring required

The ID of the internal account

customerIdstring

The ID of the customer associated with the internal account. If this field is empty, the internal account belongs to the platform.

type'INTERNAL_FIAT' | 'INTERNAL_CRYPTO' | 'EMBEDDED_WALLET' | 'RULE_BASED' | 'BULK_SETTLEMENT' required

Classification of an internal account.

  • INTERNAL_FIAT: A Grid-managed fiat holding account (for example, the USD holding account used as the source for Payouts flows).
  • INTERNAL_CRYPTO: A Grid-managed crypto holding account denominated in a stablecoin such as USDC.
  • EMBEDDED_WALLET: A self-custodial Embedded Wallet provisioned for the customer. Outbound transfers require a session signature produced by the customer's device — see the Embedded Wallets guide.
  • RULE_BASED: An additional account number for an existing account holder, with a routing rule attached, so incoming payments can be attributed to a specific payer and swept automatically. Created with POST /internal-accounts.
  • BULK_SETTLEMENT: An account for receiving bulk payments (for example, a single settlement from a payment processor) that the platform then pays out to its customers. Only a platform can hold one, and funds in it can move only to the platform's customers.
status'PENDING' | 'ACTIVE' | 'CLOSED' | 'FROZEN' | 'FAILED' required

Status of a Grid internal account. The status determines whether the account can send or receive payments.

  • PENDING: The account is under review and is being provisioned. The account cannot send or receive payments until provisioning completes.
  • ACTIVE: The account is ready to send and receive payments.
  • CLOSED: The account cannot send or receive payments. A customer can initiate the closing of an internal account, after which the account transitions to this status.
  • FROZEN: The account cannot send or receive payments. Grid may freeze an account in response to compliance or fraud signals; payments are blocked while the account remains frozen.
  • FAILED: The account could not be provisioned. Grid was unable to create the underlying account, so it cannot send or receive payments and requires remediation.
onBehalfOfCustomerIdstring

The customer whose payments this platform-owned account receives. Only set by regulated financial institutions. Omitted for accounts that name no such customer, which includes every account owned by a customer.

labelstring

The platform-supplied label recorded when the account was created. Null for accounts that carry none.

privateEnabledboolean

Whether wallet privacy is enabled for the Embedded Wallet. Only present for EMBEDDED_WALLET internal accounts.

createdAtstring date-time required

Timestamp when the internal account was created

updatedAtstring date-time required

Timestamp when the internal account was last updated

Example response

{
  "id": "InternalAccount:12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "status": "ACTIVE",
  "balance": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "totalBalance": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "fundingPaymentInstructions": [
    {
      "instructionsNotes": "Please ensure the reference code is included in the payment memo/description field",
      "isPlatformAccount": true,
      "accountOrWalletInfo": {
        "accountType": "USD_ACCOUNT",
        "accountNumber": "1234567890",
        "routingNumber": "021000021",
        "bankName": "Chase Bank",
        "intermediaryBankName": "JPMorgan Chase Bank",
        "intermediaryRoutingNumber": "021000021",
        "fiToFiInformation": "/BNF/Invoice 4471",
        "bankAccountType": "CHECKING"
      }
    }
  ],
  "onBehalfOfCustomerId": "Customer:019542f5-b3e7-1d02-0000-000000000002",
  "label": "invoice-4417",
  "sweepRule": {
    "destination": {
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "paymentRail": "ACH"
    },
    "minimumAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "maximumAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "description": "Rent sweep",
    "remittanceInformation": "Unit 4B March",
    "platformFeeOverride": {
      "platformFixedFee": {
        "amount": 50,
        "currency": "USD"
      },
      "platformVariableFeeBps": 30
    }
  },
  "privateEnabled": true,
  "cardCapabilities": {
    "supportsVelocityLimits": true,
    "supportsPanReveal": true,
    "supportsDigitalWalletTokenization": true
  },
  "createdAt": "2025-10-03T12:30:00Z",
  "updatedAt": "2025-10-03T12:30:00Z"
}

Changes

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 5fbda612feb8Revision changes
    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • info

      added the required property / to the response with the status