Authorize a rule-based account's SCA challenge

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/authorize \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "000000",
  "passkeyAssertion": {},
  "origin": "https://app.example.com",
  "endUserIpAddress": "203.0.113.42"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    code: '000000',
    passkeyAssertion: {},
    origin: 'https://app.example.com',
    endUserIpAddress: '203.0.113.42'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/authorize', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"code\": \"000000\",\n  \"passkeyAssertion\": {},\n  \"origin\": \"https://app.example.com\",\n  \"endUserIpAddress\": \"203.0.113.42\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/authorize")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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",
        "intermediaryBankName": "JPMorgan Chase Bank",
        "intermediaryRoutingNumber": "021000021",
        "fiToFiInformation": "/BNF/Invoice 4471",
        "bankAccountType": "CHECKING"
      },
      "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",
  "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
      }
    },
    "purposeOfPayment": "SELF",
    "description": "Rent sweep",
    "remittanceInformation": "Unit 4B March",
    "platformFeeOverride": {
      "platformFixedFee": {
        "amount": 50,
        "currency": "USD"
      },
      "platformVariableFeeBps": 30
    }
  },
  "scaChallenge": {
    "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
    "expiresAt": "2025-10-03T12:05:00Z",
    "factor": "SMS_OTP",
    "availableFactors": [
      "SMS_OTP"
    ],
    "purpose": "PAYOUT",
    "passkeyAssertionOptions": {},
    "passkeyAllowedOrigins": [
      "https://app.example.com"
    ]
  },
  "strandedBalances": [
    {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    }
  ],
  "privateEnabled": true,
  "cardCapabilities": {
    "supportsVelocityLimits": true,
    "supports3dSecurePassword": false,
    "supportsPanReveal": true,
    "supportsDigitalWalletTokenization": true
  }
}

{
  "code": "INVALID_INPUT",
  "reason": "<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."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "ACCOUNT_LOCKED",
  "reason": "<string>",
  "details": {
    "suspended": true,
    "lockedUntil": "2023-11-07T05:31:56Z",
    "failedAttempts": 123
  }
}

{
  "code": "RATE_LIMITED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Internal Accounts

Authorize a rule-based account's SCA challenge

Satisfy the Strong Customer Authentication challenge carried by a RULE_BASED internal account in PENDING status by submitting an ScaAuthorization proof. The challenge authorizes the account’s sweep instruction once; later sweeps need no further authorization.

On success the account is returned ACTIVE with its fundingPaymentInstructions, and an INTERNAL_ACCOUNT.STATUS_UPDATED webhook is sent. As with all SCA, check the returned account: if it is still PENDING it carries the next scaChallenge to authorize.

This endpoint is only meaningful for customers in a region where SCA is required (e.g. EU). For other customers, and for accounts with no pending challenge, this returns 409.

In sandbox, the SMS code is always 123456.

POST

internal-accounts

{id}

authorize

Authorize a rule-based account's SCA challenge

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/authorize \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "000000",
  "passkeyAssertion": {},
  "origin": "https://app.example.com",
  "endUserIpAddress": "203.0.113.42"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    code: '000000',
    passkeyAssertion: {},
    origin: 'https://app.example.com',
    endUserIpAddress: '203.0.113.42'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/authorize', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"code\": \"000000\",\n  \"passkeyAssertion\": {},\n  \"origin\": \"https://app.example.com\",\n  \"endUserIpAddress\": \"203.0.113.42\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id}/authorize")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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",
        "intermediaryBankName": "JPMorgan Chase Bank",
        "intermediaryRoutingNumber": "021000021",
        "fiToFiInformation": "/BNF/Invoice 4471",
        "bankAccountType": "CHECKING"
      },
      "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",
  "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
      }
    },
    "purposeOfPayment": "SELF",
    "description": "Rent sweep",
    "remittanceInformation": "Unit 4B March",
    "platformFeeOverride": {
      "platformFixedFee": {
        "amount": 50,
        "currency": "USD"
      },
      "platformVariableFeeBps": 30
    }
  },
  "scaChallenge": {
    "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
    "expiresAt": "2025-10-03T12:05:00Z",
    "factor": "SMS_OTP",
    "availableFactors": [
      "SMS_OTP"
    ],
    "purpose": "PAYOUT",
    "passkeyAssertionOptions": {},
    "passkeyAllowedOrigins": [
      "https://app.example.com"
    ]
  },
  "strandedBalances": [
    {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    }
  ],
  "privateEnabled": true,
  "cardCapabilities": {
    "supportsVelocityLimits": true,
    "supports3dSecurePassword": false,
    "supportsPanReveal": true,
    "supportsDigitalWalletTokenization": true
  }
}

{
  "code": "INVALID_INPUT",
  "reason": "<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."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "ACCOUNT_LOCKED",
  "reason": "<string>",
  "details": {
    "suspended": true,
    "lockedUntil": "2023-11-07T05:31:56Z",
    "failedAttempts": 123
  }
}

{
  "code": "RATE_LIMITED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

The ID of the rule-based internal account whose SCA challenge is being authorized.

Body

application/json

Proof that satisfies an ScaChallenge. Provide exactly one of code (for SMS_OTP / TOTP) or passkeyAssertion (for PASSKEY). When supplying a passkeyAssertion, origin is required — the WebAuthn assertion is bound to the origin it was produced against, and a passkey confirmation is rejected without it.

code

string | null

The one-time code the customer received by SMS, or read from their authenticator app. In sandbox, the code is always 000000.

Example:

"000000"

passkeyAssertion

object | null

Opaque WebAuthn assertion produced by the device from the challenge's passkeyAssertionOptions. Required when satisfying a PASSKEY challenge.

origin

string | null

The WebAuthn origin the passkeyAssertion was produced against. Required alongside passkeyAssertion; omit it for the code path. When the challenge lists passkeyAllowedOrigins (enrollment / login challenges), it must be one of those. A per-transaction passkey challenge carries passkeyAssertionOptions but may omit passkeyAllowedOrigins; in that case supply the origin your app invoked the WebAuthn API from, which must match the relying party in passkeyAssertionOptions.

Example:

"https://app.example.com"

endUserIpAddress

string | null

The IP address of the end user's device authorizing this operation, forwarded to the SCA provider where it feeds risk assessment and any transaction-risk exemption. Supply the customer's address, not your server's. Optional: the provider records it for money-movement authorizations, and ignores it for beneficiary trust changes.

Example:

"203.0.113.42"

Response

Challenge authorized; the updated account is returned.

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.
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. 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 and waiting for that 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

Using the API

API documentation

Authorize a rule-based account's SCA challenge

Authorizations

Path Parameters

Body

Response