Simulate funding an internal account

Simulate receiving funds into an internal account in the sandbox environment. This is useful for testing scenarios where you need to add funds to a customer’s or platform’s internal account without going through a real bank transfer or following payment instructions. This endpoint is only for the sandbox environment and will fail for production platforms/keys.

POST /sandbox/internal-accounts/{accountId}/fund

cURL

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/sandbox/internal-accounts/{accountId}/fund \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 100000
}
'

200

{
  "id": "InternalAccount:12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
  "type": "INTERNAL_FIAT",
  "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": [
    {
      "accountOrWalletInfo": {
        "accountType": "USD_ACCOUNT",
        "accountNumber": "1234567890",
        "routingNumber": "021000021",
        "bankName": "Chase Bank",
        "bankAccountType": "CHECKING",
        "intermediaryBankName": "JPMorgan Chase Bank",
        "intermediaryRoutingNumber": "021000021",
        "fiToFiInformation": "/BNF/Invoice 4471"
      },
      "instructionsNotes": "Please ensure the reference code is included in the payment memo/description field",
      "isPlatformAccount": true
    }
  ],
  "createdAt": "2025-10-03T12:30:00Z",
  "updatedAt": "2025-10-03T12:30:00Z",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "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
      }
    },
    "purposeOfPayment": "SELF",
    "description": "Rent sweep",
    "remittanceInformation": "Unit 4B March",
    "platformFeeOverride": {
      "platformFixedFee": {
        "amount": 50,
        "currency": "USD"
      },
      "platformVariableFeeBps": 30
    }
  },
  "privateEnabled": true,
  "cardCapabilities": {
    "supportsSpendLimits": true,
    "supportsTransactionCountLimit": true,
    "supports3dSecurePassword": false,
    "supportsPanReveal": true
  }
}

Authorizations

Authorization · string · header · required

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

Path Parameters

accountId · string · required

The ID of the internal account to fund

Body

application/json

amount · integer<int64> · required

Amount to add in the smallest unit of the account's currency (e.g., cents for USD/EUR, satoshis for BTC)

Required range: x <= 100000000000

Example:

100000

Response

200

application/json

Internal account funded successfully

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.

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 the first funding source. They can change if the platform's card routing changes and do not describe cards already issued using the account. When a create request supplies several funding sources, the first entry 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