Copy page

Guides

Quickstart

Request your first advance in seven steps. Each step links to its full documentation.

1. Confirm Your API Key

Lunch issues your API key (prefix lux_sk_). Store it server-side and send it as a bearer token. Verify it with a read-only request:

Code
curl https://api.lunchpayments.com/v1/webhooks \
  -H "Authorization: Bearer lux_sk_..."

401 unauthorized: the key is missing, malformed or revoked.

2. Subscribe to Webhooks

Code
curl -X POST https://api.lunchpayments.com/v1/webhooks \
  -H "Authorization: Bearer lux_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/lunch/webhooks" }'

Store the signing secret from the response. It is returned only once. See Webhooks.

3. Sync an Invoice

Creates or updates the invoice, the vendor (payee) and the city (payor). Amounts are in cents.

Code
curl -X PUT https://api.lunchpayments.com/v1/invoices/INV-001 \
  -H "Authorization: Bearer lux_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "payee": { "externalId": "vendor-88", "legalName": "Ridgeline Electrical LLC" },
    "payor": { "externalId": "city-of-boise", "legalName": "City of Boise" },
    "status": "ISSUED",
    "faceValue": 100000,
    "issueDate": "2026-09-01T00:00:00Z",
    "dueDate": "2026-11-30T00:00:00Z"
  }'

4. Onboard the Vendor

Send POST /v1/invitations so the vendor can claim its account, sign the agreement and add a bank account. Check status with GET /v1/organizations/{externalId}. See Vendor Onboarding.

5. Quote the Advance

Code
curl -X POST https://api.lunchpayments.com/v1/quotes \
  -H "Authorization: Bearer lux_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "vendor-88", "invoiceFaceValue": 100000 }'

For example, a $1,000.00 invoice could return $800.00 up front, $50.00 in fees, and $150.00 when the city pays. Rates vary by vendor. Always quote.

6. Request the Advance

Code
curl -X POST https://api.lunchpayments.com/v1/advances \
  -H "Authorization: Bearer lux_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "payeeExternalId": "vendor-88", "invoiceExternalId": "INV-001" }'

Response:

Code
{
  "alreadyRequested": false,
  "financeableAmount": 100000,
  "advanceAmount": 80000,
  "feeTotal": 5000,
  "forwardedAtPayment": 15000,
  "remittance": {
    "accountNumber": "9900012345",
    "routingNumber": "021000021"
  }
}

remittance is the vendor's collection account, where the payor must pay this invoice.

Repeat requests return the existing advance. Refusals return 409 with a code.

7. Receive Payment Events

Event	Description
partner.loan.issued	The vendor has been paid the advance.
partner.invoice.paid	The city has paid the invoice.

What's Next

• Requesting an Advance