Skip to main content
A merchant cash advance is an up-front lump sum that the business repays out of its incoming sales, plus a fixed fee. In Layer you model an MCA in two parts: create the loan (fully disbursed up front), then record repayments as they are withheld from sales.

​
Step 1: Create the loan

Create a loan with loan_type set to MCA, and disburse the full advance immediately by including a single DISBURSEMENT proceed for the whole amount. Set an external_id so you can reference the loan later without storing Layer’s IDs. The fee_percentage is the fixed fee expressed as a percentage (for example, "15" for a 15% fee on a $20,000 advance).
Request
curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/loans \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "loan_type": "MCA",
  "external_id": "mca-001",
  "display_name": "Working capital advance",
  "origination_date": "2024-03-01",
  "original_principal": 2000000,
  "fee_percentage": "15",
  "proceeds": [
    {
      "loan_proceed_type": "DISBURSEMENT",
      "amount": 2000000,
      "date": "2024-03-01",
      "method": "ACH"
    }
  ]
}'

​
Step 2: Record repayments

MCA repayments are typically withheld from the business’s incoming sales, so each repayment reduces the outstanding principal and includes a portion of the fee. Each repayment is a loan payment split into PRINCIPAL and FEE. For MCAs you can omit the payment’s splits and Layer derives them from the loan’s fee_percentage (principal = amount / (1 + fee_percentage / 100), fee = remainder); provide explicit splits to override. How you create those loan payments depends on the granularity of your data.

​
If you have payment-level granularity

If you know how much was withheld for each individual sale, attach the repayment to that invoice payment as a LOAN_REPAYMENT additional fee when you record the payment. Layer creates the linked loan payment and ties the two together. In the example below, a customer pays a $1,150.00 invoice and the MCA provider withholds $150.00 of it to repay the advance, so the business nets $1,000.00. Because the loan is an MCA, splits are omitted and Layer derives the principal and fee from the loan’s fee_percentage.
Request
curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/invoices/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "paid_at": "2024-03-15T12:00:00Z",
  "method": "ACH",
  "amount": 115000,
  "invoice_payments": [
    { "invoice_external_id": "invoice-789", "amount": 115000 }
  ],
  "additional_fees": [
    {
      "type": "LOAN_REPAYMENT",
      "loan_payment": {
        "loan_external_id": "mca-001",
        "amount": 15000,
        "date": "2024-03-15"
      }
    }
  ]
}'

​
If you have payout-level granularity

If you only know repayment totals at the payout level, create the loan payment(s) directly with Create a loan payment, then reference them when you create the payout they were deducted from. First, create the loan payment with an external_id you can reference. As above, splits are omitted so Layer derives the principal and fee from the loan’s fee_percentage:
Request
curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/loans/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "loan_external_id": "mca-001",
  "external_id": "mca-001-payment-2024-03-15",
  "amount": 115000,
  "date": "2024-03-15"
}'
Then reference the loan payment(s) in the payout they were deducted from via loan_payments. The MCA repayment reduces the amount deposited: here $5,000.00 of sales were collected and $1,150.00 was withheld for the advance, so paid_out_amount is $3,850.00.
Request
curl --request POST \
  --url https://sandbox.layerfi.com/v1/businesses/{businessId}/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "external_id": "payout-2024-03-15",
  "paid_out_amount": 385000,
  "fee": 0,
  "completed_at": "2024-03-15T23:00:00Z",
  "payments": [
    { "invoice_payment_external_id": "card-sales-2024-03-15", "amount": 500000 }
  ],
  "loan_payments": [
    { "loan_payment_external_id": "mca-001-payment-2024-03-15" }
  ]
}'