Recipes›Lending›Originate a merchant advance

Originate a merchant advance

Create and fund Northstar's receivables purchase, then turn a verified daily sales report into a traceable remittance without pretending the forecast is a loan maturity schedule.

Time

~10 min plus settlement

Surface

LMS API

Steps

Gate

Merchant verification · sales provenance · reconciliation

EndpointsPOST /v1/merchant-advancesPOST /v1/merchant-advances/{advanceId}/approvePOST /v1/merchant-advances/{advanceId}/funding-intentsPOST /v1/merchant-advances/{advanceId}/sales-reportsPOST /v1/merchant-advances/{advanceId}/remittances

Northstar sells $60,000.00 of future receivables for a $48,000.00 purchase price. It remits 12% of verified settled sales until the purchased amount is delivered.

Create the receivables purchase

Commercial contract

POST/v1/merchant-advances

curl -X POST "$BASE/v1/merchant-advances" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: northstar-advance-2026" \
  -d '{
    "merchantId": "party_NORTHSTAR_4",
    "productId": "prod_MERCHANT_ADVANCE_1",
    "externalId": "northstar-advance-2026",
    "terms": {
      "purchasePrice": "48000.00",
      "purchasedAmount": "60000.00",
      "currency": "USD",
      "remittanceRate": "0.12",
      "reportingFrequency": "daily",
      "expectedMonthlySales": "50000.00"
    }
  }'

The advance is submitted; its initial remaining purchased amount is $60,000.00.

Approve and fund the merchant

Terms frozen

POST/v1/merchant-advances/ma_northstar_6N8Q/approve

Approve the versioned purchase terms, then create the $48,000.00 payout to Northstar’s verified account:

curl -X POST "$BASE/v1/merchant-advances/ma_northstar_6N8Q/approve" \
  -H "Authorization: Bearer $APPROVER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: approve-northstar-decision-4" \
  -d '{
    "approvedOn": "2026-09-03",
    "approvedPurchasePrice": "48000.00",
    "decisionId": "decision_NORTHSTAR_4",
    "expectedVersion": 2
  }'

curl -X POST "$BASE/v1/merchant-advances/ma_northstar_6N8Q/funding-intents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fund-northstar-purchase-price" \
  -d '{
    "amount": "48000.00",
    "currency": "USD",
    "paymentInstrumentId": "pi_NORTHSTAR_BANK_1",
    "rail": "ach_credit"
  }'

Activation follows posted funding, not approval or rail acceptance.

Record verified settled sales

POST/v1/merchant-advances/ma_northstar_6N8Q/sales-reports

curl -X POST "$BASE/v1/merchant-advances/ma_northstar_6N8Q/sales-reports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: settlement-884210" \
  -d '{
    "periodStart": "2026-09-08",
    "periodEnd": "2026-09-09",
    "currency": "USD",
    "settledSales": "11875.40",
    "source": "processor_report",
    "sourceReference": "settlement_884210"
  }'

The report calculates a $1,425.05 remittance after currency rounding: $11,875.40 × 0.12 = $1,425.048, rounded to $1,425.05.

Create the remittance

Sales linked

POST/v1/merchant-advances/ma_northstar_6N8Q/remittances

curl -X POST "$BASE/v1/merchant-advances/ma_northstar_6N8Q/remittances" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: northstar-remittance-msr-91dc" \
  -d '{
    "salesReportIds": ["msr_91DC"],
    "amount": "1425.05",
    "currency": "USD",
    "paymentInstrumentId": "pi_NORTHSTAR_BANK_1",
    "rail": "ach_debit",
    "effectiveDate": "2026-09-10"
  }'

The remaining purchased amount stays $60,000.00 while the debit is submitted. It becomes $58,574.95 only after authoritative posting.

Reconcile report, settlement, and balance

Four-way match

GET/v1/merchant-advances/ma_northstar_6N8Q/reconciliation

reported settled sales         11,875.40
× contractual remittance rate       12%
calculated remittance           1,425.05
provider-settled remittance     1,425.05
posted balance reduction        1,425.05
difference                          0.00

The projection may now forecast a different completion month. That date remains a forecast driven by actual sales—not a fixed installment due date or contractual loan maturity.