> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant cash advances (MCAs)

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](/api-reference/loan/loan#loan-proceed-object) 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).

```bash Request theme={null}
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](/api-reference/loan/loan#loan-payment-object) 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](/api-reference/invoice/payments) as a `LOAN_REPAYMENT` additional fee when you [record the payment](/api-reference/v1/record-a-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`.

```bash Request theme={null}
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](/api-reference/v1/loans/create-loan-payment), then reference them when you [create the payout](/api-reference/v1/create-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`:

```bash Request theme={null}
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](/api-reference/customer-payouts/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.

```bash Request theme={null}
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" }
  ]
}'
```