cURL

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "privateEnabled": true
}
'

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 internalAccount = await client.customers.updateInternalAccount(
  'InternalAccount:019542f5-b3e7-1d02-0000-000000000002',
  { InternalAccountUpdateRequest: {} },
);

console.log(internalAccount.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.customers.CustomerUpdateInternalAccountParams
import com.lightspark.grid.models.customers.InternalAccountUpdateRequest
import com.lightspark.grid.models.sandbox.internalaccounts.InternalAccount

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: CustomerUpdateInternalAccountParams = CustomerUpdateInternalAccountParams.builder()
        .id("InternalAccount:019542f5-b3e7-1d02-0000-000000000002")
        .internalAccountUpdateRequest(InternalAccountUpdateRequest.builder().build())
        .build()
    val internalAccount: InternalAccount = client.customers().updateInternalAccount(params)
}

{
  "id": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "type": "EMBEDDED_WALLET",
  "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": [],
  "privateEnabled": true,
  "createdAt": "2026-04-08T15:30:00Z",
  "updatedAt": "2026-04-08T15:35:02Z"
}

{
  "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"encoding\":\"PAYLOAD_ENCODING_HEXADECIMAL\",\"hashFunction\":\"HASH_FUNCTION_NO_OP\",\"payload\":\"9f3b...\",\"signWith\":\"sp1q...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2\"}",
  "requestId": "Request:019542f5-b3e7-1d02-0000-000000000010",
  "expiresAt": "2026-04-08T15:35:00Z"
}

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "code": "TRANSACTION_NOT_FOUND",
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "code": "GRID_SWITCH_ERROR",
  "message": "<string>",
  "details": {}
}

Internal Accounts

Update internal account

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:

Call PATCH /internal-accounts/{id} with the request body { "privateEnabled": true } and no signature headers. Grid returns 202 with payloadToSign, requestId, and expiresAt.
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}

cURL

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "privateEnabled": true
}
'

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 internalAccount = await client.customers.updateInternalAccount(
  'InternalAccount:019542f5-b3e7-1d02-0000-000000000002',
  { InternalAccountUpdateRequest: {} },
);

console.log(internalAccount.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.customers.CustomerUpdateInternalAccountParams
import com.lightspark.grid.models.customers.InternalAccountUpdateRequest
import com.lightspark.grid.models.sandbox.internalaccounts.InternalAccount

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: CustomerUpdateInternalAccountParams = CustomerUpdateInternalAccountParams.builder()
        .id("InternalAccount:019542f5-b3e7-1d02-0000-000000000002")
        .internalAccountUpdateRequest(InternalAccountUpdateRequest.builder().build())
        .build()
    val internalAccount: InternalAccount = client.customers().updateInternalAccount(params)
}

{
  "id": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "type": "EMBEDDED_WALLET",
  "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": [],
  "privateEnabled": true,
  "createdAt": "2026-04-08T15:30:00Z",
  "updatedAt": "2026-04-08T15:35:02Z"
}

{
  "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"encoding\":\"PAYLOAD_ENCODING_HEXADECIMAL\",\"hashFunction\":\"HASH_FUNCTION_NO_OP\",\"payload\":\"9f3b...\",\"signWith\":\"sp1q...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2\"}",
  "requestId": "Request:019542f5-b3e7-1d02-0000-000000000010",
  "expiresAt": "2026-04-08T15:35:00Z"
}

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "code": "TRANSACTION_NOT_FOUND",
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "code": "GRID_SWITCH_ERROR",
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Headers

Grid-Wallet-Signature

string

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-Id

string

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.

Path Parameters

string

required

The id of the internal account to update.

Body

application/json

Partial request body for PATCH /internal-accounts/{id}. At least one update field must be provided. On step 1 of the signed-retry flow Grid binds the submitted update fields into payloadToSign; on step 2 the client echoes the same fields back and Grid applies the update to the internal account.

privateEnabled

boolean

Whether wallet privacy should be enabled for the Embedded Wallet.

Example:

true

Response

Signed retry accepted. Returns the updated internal account.

string

required

The ID of the internal account

Example:

"InternalAccount:12dcbd6-dced-4ec4-b756-3c3a9ea3d123"

type

enum<string>

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.

Available options:

INTERNAL_FIAT,

INTERNAL_CRYPTO,

EMBEDDED_WALLET,

RULE_BASED

status

enum<string>

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.

Available options:

PENDING,

ACTIVE,

CLOSED,

FROZEN,

FAILED

Example:

"ACTIVE"

balance

object

required

The balance available to spend, excluding pending and held funds

Show child attributes

totalBalance

object

required

The total balance, including pending and held funds

Show child attributes

fundingPaymentInstructions

object[]

required

Payment instructions for funding the account

Show child attributes

createdAt

string<date-time>

required

Timestamp when the internal account was created

Example:

"2025-10-03T12:30:00Z"

updatedAt

string<date-time>

required

Timestamp when the internal account was last updated

Example:

"2025-10-03T12:30:00Z"

customerId

string

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

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

label

string

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

Maximum string length: 255

Example:

"invoice-4417"

sweepRule

Sweep Rule · object

The routing rule attached to this account. Null for accounts that carry no rule, which is every account other than a RULE_BASED one.

Show child attributes

privateEnabled

boolean

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

Example:

true

cardCapabilities

object

Actions supported for a card issued now with this account as its funding source. They can change if the platform's card routing changes and do not describe cards already issued using the account. The funding source a create request supplies selects the issuer and therefore the resulting card's capabilities; read this field from that account. Absent when this account cannot fund a card.

Show child attributes

Using the API

API documentation

Update internal account

Authorizations

Headers

Path Parameters

Body

Response