Reconcile a payment against open invoices

Match an incoming bank payment to a customer's open invoices and record it as a sale receipt — the full four-call flow, run against the mock sandbox.

1. Find the customer

Search by name to get the customer's id:

curl "https://developer.luca.pro/api/v1/customers?search=Acme" \
  -H "Authorization: Bearer sandbox-token"

Take data[].id from the response — that's the customer id for the next call.

2. List their open invoices

Fetch the customer's invoices to see what the payment could settle:

curl "https://developer.luca.pro/api/v1/customers/12/invoices" \
  -H "Authorization: Bearer sandbox-token"

Take each invoice's invoice_transaction_id and due_amount — you'll allocate the payment against these.

3. Pick a payment method

List the company's configured payment methods:

curl "https://developer.luca.pro/api/v1/payment-methods" \
  -H "Authorization: Bearer sandbox-token"

Take the method's id to use on the receipt below.

4. Create the sale receipt

Post the receipt with the customer's chosen payment method, one allocation per invoice it settles, and an Idempotency-Key:

curl -X POST "https://developer.luca.pro/api/v1/sale-receipts" \
  -H "Authorization: Bearer sandbox-token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem-2026-06-16-bankref-9912834" \
  -d '{
    "payment_method_id": 3,
    "date": "2026-06-16",
    "amount_received": 500.00,
    "reference": "Bank ref 9912834",
    "allocations": [
      {"invoice_transaction_id": 4521, "amount": 500.00}
    ]
  }'

Three rules the endpoint enforces:

• The allocations amounts must sum to exactly amount_received.
• No single allocation may exceed that invoice's outstanding balance.
• The Idempotency-Key header is required on every request. Reusing a key doesn't create a duplicate receipt — it returns 409 with the id of the original receipt, so a retried request after a timeout or a dropped connection is always safe.

5. Verify (optional)

Confirm the invoice's payment status reflects the new receipt:

curl "https://developer.luca.pro/api/v1/invoices/payment-status?invoice_number=INV-2026-0087" \
  -H "Authorization: Bearer sandbox-token"