Quote a claim

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/quote \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "claimToken": "<string>",
  "accountInfo": {
    "accountType": "AED_ACCOUNT",
    "iban": "AE070331234567890123456",
    "swiftCode": "EBILAEAD"
  },
  "paymentRail": "ACH"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    claimToken: '<string>',
    accountInfo: {
      accountType: 'AED_ACCOUNT',
      iban: 'AE070331234567890123456',
      swiftCode: 'EBILAEAD'
    },
    paymentRail: 'ACH'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/quote', 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  \"claimToken\": \"<string>\",\n  \"accountInfo\": {\n    \"accountType\": \"AED_ACCOUNT\",\n    \"iban\": \"AE070331234567890123456\",\n    \"swiftCode\": \"EBILAEAD\"\n  },\n  \"paymentRail\": \"ACH\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/quote")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

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

{
  "claimablePayout": {
    "id": "ClaimablePayout:019542f5-b3e7-1d02-0000-000000000077",
    "status": "PENDING_APPROVAL",
    "senderName": "Kevin",
    "amount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "recipient": {
      "name": "Maria",
      "phoneNumber": "+639171234567",
      "email": "maria@example.com",
      "country": "PH"
    },
    "expiresAt": "2025-10-10T15:00:00Z",
    "note": "Happy birthday, Mom",
    "receivedAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "paymentRail": "ACH",
    "failureReason": "INSUFFICIENT_FUNDS"
  },
  "quote": {
    "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "status": "PENDING",
    "createdAt": "2025-10-03T12:00:00Z",
    "expiresAt": "2025-10-03T12:05:00Z",
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "paymentRail": "ACH"
    },
    "sendingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "receivingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "totalSendingAmount": 123010,
    "totalReceivingAmount": 1000,
    "exchangeRate": 123,
    "feesIncluded": 10,
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "platformFeesIncluded": 5,
    "paymentInstructions": [
      {
        "accountOrWalletInfo": {
          "accountType": "USD_ACCOUNT",
          "paymentRails": [
            "ACH",
            "WIRE"
          ],
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "bankName": "Chase Bank",
          "reference": "UMA-Q12345-REF"
        },
        "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
      },
      {
        "accountOrWalletInfo": {
          "accountType": "SPARK_WALLET",
          "assetType": "BTC",
          "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
          "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
        }
      }
    ],
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "rateDetails": {
      "counterpartyMultiplier": 1.08,
      "counterpartyFixedFee": 10,
      "gridApiMultiplier": 0.925,
      "gridApiFixedFee": 10,
      "gridApiVariableFeeRate": 0.003,
      "gridApiVariableFeeAmount": 30
    },
    "purposeOfPayment": "GIFT",
    "documentIds": [
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
    ],
    "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"
      ]
    }
  }
}

{
  "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": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

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

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

Claimable Payouts

Quote a claim

Lock a quote paying a claimable payout to the recipient’s account. Call it only after the recipient has proved she holds the payout’s phone number or email. Grid validates accountInfo as POST /customers/external-accounts does, screens the recipient, and saves her account under the sender’s customer, where an agent can pay it again. Grid then quotes the payout’s full amount from the sender’s wallet to that account. The payout stays AWAITING_CLAIM until the quote is confirmed; calling again replaces the quote.

POST

claimable-payouts

claim

quote

Quote a claim

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/quote \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "claimToken": "<string>",
  "accountInfo": {
    "accountType": "AED_ACCOUNT",
    "iban": "AE070331234567890123456",
    "swiftCode": "EBILAEAD"
  },
  "paymentRail": "ACH"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    claimToken: '<string>',
    accountInfo: {
      accountType: 'AED_ACCOUNT',
      iban: 'AE070331234567890123456',
      swiftCode: 'EBILAEAD'
    },
    paymentRail: 'ACH'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/quote', 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  \"claimToken\": \"<string>\",\n  \"accountInfo\": {\n    \"accountType\": \"AED_ACCOUNT\",\n    \"iban\": \"AE070331234567890123456\",\n    \"swiftCode\": \"EBILAEAD\"\n  },\n  \"paymentRail\": \"ACH\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/claimable-payouts/claim/quote")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

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

{
  "claimablePayout": {
    "id": "ClaimablePayout:019542f5-b3e7-1d02-0000-000000000077",
    "status": "PENDING_APPROVAL",
    "senderName": "Kevin",
    "amount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "recipient": {
      "name": "Maria",
      "phoneNumber": "+639171234567",
      "email": "maria@example.com",
      "country": "PH"
    },
    "expiresAt": "2025-10-10T15:00:00Z",
    "note": "Happy birthday, Mom",
    "receivedAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "paymentRail": "ACH",
    "failureReason": "INSUFFICIENT_FUNDS"
  },
  "quote": {
    "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "status": "PENDING",
    "createdAt": "2025-10-03T12:00:00Z",
    "expiresAt": "2025-10-03T12:05:00Z",
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "paymentRail": "ACH"
    },
    "sendingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "receivingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "totalSendingAmount": 123010,
    "totalReceivingAmount": 1000,
    "exchangeRate": 123,
    "feesIncluded": 10,
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "platformFeesIncluded": 5,
    "paymentInstructions": [
      {
        "accountOrWalletInfo": {
          "accountType": "USD_ACCOUNT",
          "paymentRails": [
            "ACH",
            "WIRE"
          ],
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "bankName": "Chase Bank",
          "reference": "UMA-Q12345-REF"
        },
        "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
      },
      {
        "accountOrWalletInfo": {
          "accountType": "SPARK_WALLET",
          "assetType": "BTC",
          "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
          "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
        }
      }
    ],
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "rateDetails": {
      "counterpartyMultiplier": 1.08,
      "counterpartyFixedFee": 10,
      "gridApiMultiplier": 0.925,
      "gridApiFixedFee": 10,
      "gridApiVariableFeeRate": 0.003,
      "gridApiVariableFeeAmount": 30
    },
    "purposeOfPayment": "GIFT",
    "documentIds": [
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
    ],
    "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"
      ]
    }
  }
}

{
  "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": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

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

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

Authorizations

Authorization

string

header

required

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

Body

application/json

The recipient's payout details. Grid validates them as for POST /customers/external-accounts, screens the recipient, saves the account under the sender's customer and locks a quote for the payout.

claimToken

string

required

The claim token from the recipient's link.

Required string length: 1 - 128

accountInfo

AED Account · object

required

Show child attributes

Example:

{
  "accountType": "AED_ACCOUNT",
  "iban": "AE070331234567890123456",
  "swiftCode": "EBILAEAD"
}

paymentRail

enum<string>

The rail the recipient chose from POST /claimable-payouts/claim/options, when her account type is paid on more than one (for example SEPA or SEPA_INSTANT). Omit it to use the account type's default rail.

Available options:

ACH,

ACH_COLOMBIA,

ACH_SAME_DAY,

BANK_TRANSFER,

BRE_B,

CIPS,

FAST,

FASTER_PAYMENTS,

FEDNOW,

INSTAPAY,

MOBILE_MONEY,

NEFT,

PAYNOW,

PESONET,

PIX,

RTGS,

RTP,

SEPA,

SEPA_INSTANT,

SPEI,

SWIFT,

UNIONPAY,

UPI,

WIRE

Example:

"ACH"

Response

Quote locked

A locked quote paying the claimable payout to the recipient. Confirm it before quote.expiresAt; after that, request another.

claimablePayout

object

required

A claimable payout as its claim token shows it to the platform. Show the recipient no more than senderName and amount until she has proved she holds recipient.phoneNumber or recipient.email.

Show child attributes

quote

object

required

Show child attributes

Using the API

API documentation

Quote a claim

Authorizations

Body

Response