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

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.sandbox.internalAccounts.fund(
  'InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123',
  { amount: 100000 },
);

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.sandbox.internalaccounts.InternalAccount
import com.lightspark.grid.models.sandbox.internalaccounts.InternalAccountFundParams

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

    val params: InternalAccountFundParams = InternalAccountFundParams.builder()
        .accountId("InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123")
        .amount(100000L)
        .build()
    val internalAccount: InternalAccount = client.sandbox().internalAccounts().fund(params)
}

200

{
  "id": "InternalAccount:12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
  "balance": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "fundingPaymentInstructions": [
    {
      "accountOrWalletInfo": {
        "accountType": "USD_ACCOUNT",
        "accountNumber": "<string>",
        "routingNumber": "021000021",
        "paymentRails": [],
        "reference": "UMA-Q12345-REF"
      },
      "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"
}

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

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

{
  "status": 403,
  "message": "<string>",
  "details": {}
}

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

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

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"

balance · object · required

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"