Reconciliation

Reconciliation of payments

This guide explains how to reconcile transactions between your internal systems and the Grid API using two complementary mechanisms: real-time webhooks and periodic queries.

Use webhooks for real-time updates and daily queries as a backstop to detect missed events or data drift.

Handling webhooks

Listen for transaction webhooks to track transaction status change until a terminal state is reached.

Terminal statuses for outgoing transactions: COMPLETED, FAILED, EXPIRED. All other statuses will progress until reaching one of the above.

• Outbound transactions: The originating account is debited at transaction creation. If the transaction ultimately fails, a refund is posted back to the originating account.
• Inbound transactions: The receiving account is credited only on success. Failures do not change balances.

Grid retries failed webhooks up to 160 times over 7 days with exponential backoff. Use the dashboard to review and remediate webhook delivery issues.

1. Subscribe and verify signatures

   Configure your webhook endpoint and verify signatures. See Webhooks.

   Sample webhook payload:

   {
     "transaction": {
       "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
       "status": "COMPLETED",
       "type": "OUTGOING",
       "source": {
         "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
         "currency": "USD"
       },
       "destination": {
         "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
         "currency": "EUR"
       },
       "sentAmount": {
         "amount": 10000,
         "currency": { "code": "USD", "symbol": "$", "decimals": 2 }
       },
       "receivedAmount": {
         "amount": 9200,
         "currency": { "code": "EUR", "symbol": "€", "decimals": 2 }
       },
       "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
       "platformCustomerId": "customer_12345",
       "createdAt": "2025-10-03T15:00:00Z",
       "settledAt": "2025-10-03T15:30:00Z",
       "description": "Payment for services - Invoice #1234"
     },
     "timestamp": "2025-10-03T15:30:01Z",
     "webhookId": "Webhook:019542f5-b3e7-1d02-0000-0000000000ab",
     "type": "OUTGOING_PAYMENT"
   }
   
2. Process events idempotently

   Use the webhookId, transaction.id, and timestamp to ensure idempotent handling, updating your internal ledger on each status transition.

3. Recognize terminal states

   When a transaction reaches a terminal state, finalize your reconciliation for that transaction.

Reconcile via queries

Additionally, you can list transactions for a time window and compare with your internal records.

We recommend querying days from 00:00:00.000 to 23:59:59.999 in your preferred timezone.

cURL

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?startDate=2025-10-01T00:00:00.000Z&endDate=2025-10-01T23:59:59.999Z&limit=100' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

Response

{
  "data": [
    {
      "id": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
      "status": "COMPLETED",
      "type": "OUTGOING",
      "source": {
        "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
        "currency": "USD"
      },
      "destination": {
        "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
        "currency": "EUR"
      },
      "sentAmount": {
        "amount": 10000,
        "currency": { "code": "USD", "symbol": "$", "decimals": 2 }
      },
      "receivedAmount": {
        "amount": 9200,
        "currency": { "code": "EUR", "symbol": "€", "decimals": 2 }
      },
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "platformCustomerId": "customer_12345",
      "description": "Payment for services - Invoice #1234",
      "exchangeRate": 0.92,
      "settledAt": "2025-10-03T15:30:00Z",
      "createdAt": "2025-10-03T15:00:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJpZCI6IlRyYW5zYWN0aW9uOjAxOTU0MmY1LWIzZTctMWQwMi0wMDAwLTAwMDAwMDAwMDAzMCJ9",
  "totalCount": 45
}

Troubleshooting

• Missing webhook: Check delivery logs in the dashboard and ensure your endpoint returns 2xx. Retries continue for 7 days.
• Mismatched balances: Re-query the date range and verify terminal statuses; remember outbound failures are refunded, inbound failures do not change balances.
• Pagination gaps: Always follow nextCursor until hasMore is false.