Create a payout run

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/payout-runs \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "rows": [
    {
      "clientRowId": "contractor-0042",
      "lockedCurrencyAmount": 125000,
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "description": "October invoice"
    }
  ],
  "scheduledAt": "2026-11-05T02:00:00Z",
  "allOrNothing": false
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source: {
      accountId: 'InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965',
      customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001'
    },
    rows: [
      {
        clientRowId: 'contractor-0042',
        lockedCurrencyAmount: 125000,
        destination: {
          destinationType: 'EXTERNAL_ACCOUNT',
          externalAccountId: 'ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123'
        },
        description: 'October invoice'
      }
    ],
    scheduledAt: '2026-11-05T02:00:00Z',
    allOrNothing: false
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/payout-runs', 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  \"source\": {\n    \"accountId\": \"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965\",\n    \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\"\n  },\n  \"rows\": [\n    {\n      \"clientRowId\": \"contractor-0042\",\n      \"lockedCurrencyAmount\": 125000,\n      \"destination\": {\n        \"destinationType\": \"EXTERNAL_ACCOUNT\",\n        \"externalAccountId\": \"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\"\n      },\n      \"description\": \"October invoice\"\n    }\n  ],\n  \"scheduledAt\": \"2026-11-05T02:00:00Z\",\n  \"allOrNothing\": false\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/payout-runs")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

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

{
  "id": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
  "status": "VALIDATING",
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "allOrNothing": false,
  "rowCounts": {
    "total": 1000,
    "pending": 0,
    "pendingClaim": 12,
    "processing": 0,
    "completed": 980,
    "failed": 8,
    "skipped": 0
  },
  "createdAt": "2026-11-04T22:00:00Z",
  "updatedAt": "2026-11-05T02:14:00Z",
  "rejectedRows": [
    {
      "id": "PayoutRunRow:019542f5-b3e7-1d02-0000-000000000002",
      "payoutRunId": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
      "clientRowId": "contractor-0042",
      "rowIndex": 41,
      "state": "PENDING",
      "lockedCurrencySide": "SENDING",
      "lockedCurrencyAmount": 125000,
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "createdAt": "2026-11-04T22:00:00Z",
      "updatedAt": "2026-11-05T02:14:00Z",
      "description": "October invoice",
      "purposeOfPayment": "GIFT",
      "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
      "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
      "failureCode": "INSUFFICIENT_FUNDS",
      "failureReason": "Insufficient balance on the source account."
    }
  ],
  "scheduledAt": "2026-11-05T02:00:00Z",
  "finishedAt": "2026-11-05T02:14:00Z"
}

{
  "id": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
  "status": "VALIDATING",
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "allOrNothing": false,
  "rowCounts": {
    "total": 1000,
    "pending": 0,
    "pendingClaim": 12,
    "processing": 0,
    "completed": 980,
    "failed": 8,
    "skipped": 0
  },
  "createdAt": "2026-11-04T22:00:00Z",
  "updatedAt": "2026-11-05T02:14:00Z",
  "rejectedRows": [
    {
      "id": "PayoutRunRow:019542f5-b3e7-1d02-0000-000000000002",
      "payoutRunId": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
      "clientRowId": "contractor-0042",
      "rowIndex": 41,
      "state": "PENDING",
      "lockedCurrencySide": "SENDING",
      "lockedCurrencyAmount": 125000,
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "createdAt": "2026-11-04T22:00:00Z",
      "updatedAt": "2026-11-05T02:14:00Z",
      "description": "October invoice",
      "purposeOfPayment": "GIFT",
      "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
      "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
      "failureCode": "INSUFFICIENT_FUNDS",
      "failureReason": "Insufficient balance on the source account."
    }
  ],
  "scheduledAt": "2026-11-05T02:00:00Z",
  "finishedAt": "2026-11-05T02:14:00Z"
}

{
  "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": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

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

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

Payout Runs

Create a payout run

Pay many recipients from one internal account in one request. Grid validates every row before it stores the run and answers with the run and the rows it rejected. The accepted rows are then paid in the background, each through its own quote, so each emits the usual OUTGOING_PAYMENT.* webhooks. A PAYOUT_RUN.* webhook reports the run when no row is left to pay.

Funding: the source must be an open INTERNAL_FIAT or INTERNAL_CRYPTO account of the platform or of one of its customers.

Validation: a rejected row is returned with its failureCode and failureReason and stored as FAILED. The run pays the accepted rows unless allOrNothing is set, in which case any rejection fails the run and skips every row. Every rule is enforced again when a row is paid, so a row can still fail then, for example on insufficient funds.

Rows to a contact: a row addressed to a phone number or email is accepted and held as PENDING_CLAIM. Grid does not pay it.

Requires an API token with the UMA_TRANSACT permission.

POST

payout-runs

Create a payout run

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/payout-runs \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "rows": [
    {
      "clientRowId": "contractor-0042",
      "lockedCurrencyAmount": 125000,
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "description": "October invoice"
    }
  ],
  "scheduledAt": "2026-11-05T02:00:00Z",
  "allOrNothing": false
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source: {
      accountId: 'InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965',
      customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001'
    },
    rows: [
      {
        clientRowId: 'contractor-0042',
        lockedCurrencyAmount: 125000,
        destination: {
          destinationType: 'EXTERNAL_ACCOUNT',
          externalAccountId: 'ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123'
        },
        description: 'October invoice'
      }
    ],
    scheduledAt: '2026-11-05T02:00:00Z',
    allOrNothing: false
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/payout-runs', 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  \"source\": {\n    \"accountId\": \"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965\",\n    \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\"\n  },\n  \"rows\": [\n    {\n      \"clientRowId\": \"contractor-0042\",\n      \"lockedCurrencyAmount\": 125000,\n      \"destination\": {\n        \"destinationType\": \"EXTERNAL_ACCOUNT\",\n        \"externalAccountId\": \"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\"\n      },\n      \"description\": \"October invoice\"\n    }\n  ],\n  \"scheduledAt\": \"2026-11-05T02:00:00Z\",\n  \"allOrNothing\": false\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/payout-runs")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

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

{
  "id": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
  "status": "VALIDATING",
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "allOrNothing": false,
  "rowCounts": {
    "total": 1000,
    "pending": 0,
    "pendingClaim": 12,
    "processing": 0,
    "completed": 980,
    "failed": 8,
    "skipped": 0
  },
  "createdAt": "2026-11-04T22:00:00Z",
  "updatedAt": "2026-11-05T02:14:00Z",
  "rejectedRows": [
    {
      "id": "PayoutRunRow:019542f5-b3e7-1d02-0000-000000000002",
      "payoutRunId": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
      "clientRowId": "contractor-0042",
      "rowIndex": 41,
      "state": "PENDING",
      "lockedCurrencySide": "SENDING",
      "lockedCurrencyAmount": 125000,
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "createdAt": "2026-11-04T22:00:00Z",
      "updatedAt": "2026-11-05T02:14:00Z",
      "description": "October invoice",
      "purposeOfPayment": "GIFT",
      "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
      "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
      "failureCode": "INSUFFICIENT_FUNDS",
      "failureReason": "Insufficient balance on the source account."
    }
  ],
  "scheduledAt": "2026-11-05T02:00:00Z",
  "finishedAt": "2026-11-05T02:14:00Z"
}

{
  "id": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
  "status": "VALIDATING",
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "allOrNothing": false,
  "rowCounts": {
    "total": 1000,
    "pending": 0,
    "pendingClaim": 12,
    "processing": 0,
    "completed": 980,
    "failed": 8,
    "skipped": 0
  },
  "createdAt": "2026-11-04T22:00:00Z",
  "updatedAt": "2026-11-05T02:14:00Z",
  "rejectedRows": [
    {
      "id": "PayoutRunRow:019542f5-b3e7-1d02-0000-000000000002",
      "payoutRunId": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
      "clientRowId": "contractor-0042",
      "rowIndex": 41,
      "state": "PENDING",
      "lockedCurrencySide": "SENDING",
      "lockedCurrencyAmount": 125000,
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "createdAt": "2026-11-04T22:00:00Z",
      "updatedAt": "2026-11-05T02:14:00Z",
      "description": "October invoice",
      "purposeOfPayment": "GIFT",
      "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
      "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
      "failureCode": "INSUFFICIENT_FUNDS",
      "failureReason": "Insufficient balance on the source account."
    }
  ],
  "scheduledAt": "2026-11-05T02:00:00Z",
  "finishedAt": "2026-11-05T02:14:00Z"
}

{
  "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": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "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>

Headers

Idempotency-Key

string

required

Unique identifier for this run. A retry with the same key and body returns the stored run; the same key with a different body is rejected.

Maximum string length: 255

Example:

"payroll-2026-11-04"

Body

application/json

source

object

required

Show child attributes

rows

object[]

required

Required array length: 1 - 1000 elements

Show child attributes

scheduledAt

string<date-time>

When to start paying the rows. Omit it, or give a time in the past, to start as soon as the run is created.

Example:

"2026-11-05T02:00:00Z"

allOrNothing

boolean

default:false

When true, a single rejected row fails the run and no row is paid.

Response

The run this Idempotency-Key already created

string

required

System-generated unique payout run identifier

Example:

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

status

enum<string>

required

Status of a payout run.

Status	Description
`VALIDATING`	Grid is validating the rows. No row is paid yet.
`SCHEDULED`	Accepted, waiting for `scheduledAt`.
`PROCESSING`	Rows are being paid.
`COMPLETED`	Every accepted row completed or is held for a claim, and none failed.
`PARTIALLY_FAILED`	At least one row completed or is held for a claim, and at least one failed.
`FAILED`	No row completed or is held for a claim.
`CANCELLED`	Cancelled. Rows that had not started are `SKIPPED`.

Available options:

VALIDATING,

SCHEDULED,

PROCESSING,

COMPLETED,

PARTIALLY_FAILED,

FAILED,

CANCELLED

source

object

required

Show child attributes

allOrNothing

boolean

required

Example:

false

rowCounts

object

required

Show child attributes

createdAt

string<date-time>

required

Example:

"2026-11-04T22:00:00Z"

updatedAt

string<date-time>

required

Example:

"2026-11-05T02:14:00Z"

rejectedRows

object[]

required

The rows Grid rejected at validation, in submission order. Empty when every row was accepted.

Show child attributes

scheduledAt

string<date-time>

When the run starts paying rows, if it was scheduled.

Example:

"2026-11-05T02:00:00Z"

finishedAt

string<date-time>

When the run reached COMPLETED, PARTIALLY_FAILED, FAILED or CANCELLED.

Example:

"2026-11-05T02:14:00Z"

Using the API

API documentation

Create a payout run

Authorizations

Headers

Body

Response