# Quickstart

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

<Callout type="caution" title="Every request is live">
There is no sandbox. All requests use the live environment. To test without moving money, ask Lunch to
mark an organization as a test account before sending requests for it. See
[Authentication](/authentication).
</Callout>

## 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:

```bash
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

```bash
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](/webhooks).

## 3. Sync an Invoice

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

```bash
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`](/reference/onboarding#send-an-invitation) so
the vendor can claim its account, sign the agreement and add a bank account. Check status with
[`GET /v1/organizations/{externalId}`](/reference/businesses#retrieve-a-business). See
[Vendor Onboarding](/onboarding).

## 5. Quote the Advance

```bash
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

```bash
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:

```json
{
  "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.

<Callout type="caution" title="Update the vendor's remittance details">
Once an advance is requested, your platform is responsible for updating the vendor's remittance
details to the `remittance` account. The payor's payment for the invoice must go to this account, not
the vendor's external bank account.
</Callout>

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](/financing-an-invoice)