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:

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}

Update internal account

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
}
'

200

{
  "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"
}

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

id · 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

200

application/json

Signed retry accepted. Returns the updated internal account.

id · 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.
• 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.

Available options: INTERNAL_FIAT, INTERNAL_CRYPTO, EMBEDDED_WALLET, RULE_BASED, BULK_SETTLEMENT

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.
• PENDING_AUTHORIZATION: The account is provisioned but waiting for the account holder to satisfy its Strong Customer Authentication challenge (scaChallenge). Only RULE_BASED accounts for customers in a region where SCA is required (the EU) enter this status. The account cannot receive payments until it is authorized with POST /internal-accounts/{id}/authorize.
• 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, PENDING_AUTHORIZATION, 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. Empty while funding is withheld. Only bank (USD_ACCOUNT, EUR_ACCOUNT, SWIFT_ACCOUNT) and network wallet types appear here.

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"

onBehalfOfCustomerId · string

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.

Example:

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

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

scaChallenge · object

The Strong Customer Authentication challenge the account holder must satisfy before a RULE_BASED account opens. Present only while the account is PENDING_AUTHORIZATION, and only for customers in a region where SCA is required (the EU). Authorize it with POST /internal-accounts/{id}/authorize. If the challenge expires, retry the create request with the same Idempotency-Key to receive a new one.

Show child attributes

strandedBalances · object[]

Funds a RULE_BASED account's sweep converted but could not deliver to the rule's destination, by currency. They are held for the account holder and can be moved to their own account in that currency with POST /internal-accounts/{id}/stranded-funds/transfer. Omitted when there are none, and for 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