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

# Quickstart: Reserve and repay a settlement advance

> Check your credit line, reserve funds, send a wire and upload proof, and observe disbursement and repayment for a Settlement Advance draw.

This quickstart walks through a complete Settlement Advance draw lifecycle: you
check the credit line, reserve funds, send a wire and upload proof, observe
disbursement and accrued fees, and then repay by wire and confirm the repayment.
For the conceptual model behind these calls, see the
[Credit API](/circle-mint/concepts/credit-api) concept page.

## Prerequisites

Before you begin, make sure that you've:

* Contacted your Circle representative to activate Settlement Advance on your
  Circle Mint account.
* Confirmed your Circle Mint wallet holds the required USDC `minBalance` for
  your credit line.
* Configured API authentication per
  [Getting Started](/circle-mint/quickstarts/getting-started). Examples below
  use `$API_KEY` and the base URL `https://api-sandbox.circle.com`.
* Identified the `fiatAccountId` of the wire bank account from which you'll send
  the inbound wire to Circle.

## Step 1. Check the credit line

Call `GET /v1/credit` to confirm your credit line is active and has sufficient
capacity for the draw.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/credit \
  -H "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "data": {
    "id": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
    "product": "settlementAdvance",
    "feeCadence": "daily",
    "status": "active",
    "limit": { "amount": "500000.00", "currency": "USD" },
    "used": { "amount": "100000.00", "currency": "USD" },
    "available": { "amount": "400000.00", "currency": "USD" },
    "outstandingTransfers": 1,
    "feeRates": { "drawFee": "0.0001", "recurringFee": "0.0003" },
    "unpaidFees": { "amount": "0.00", "currency": "USD" },
    "minBalance": { "amount": "50000.00", "currency": "USD" },
    "validationErrors": [],
    "createDate": "2024-01-15T10:30:00.000Z",
    "updateDate": "2024-03-20T14:22:00.000Z"
  }
}
```

Before proceeding, confirm:

* `product` is `settlementAdvance`.
* `available.amount` covers the draw amount you plan to reserve.
* `validationErrors` is an empty array.

For the meaning of each field, see the
[credit-line model](/circle-mint/concepts/credit-api#the-credit-line-model).

## Step 2. Get wire repayment instructions

Call `GET /v1/credit/repaymentAccounts/{fiatAccountId}` to retrieve wire
instructions for the repayment account tied to your wire bank account.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/credit/repaymentAccounts/b8627ae8-732b-4d25-b947-1df8f4007a29 \
  -H "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "data": {
    "id": "c9f2a1b3-6d84-4e0f-b512-9a8c7e3d4f01",
    "description": "WELLS FARGO BANK, NA ****1111",
    "status": "unverified",
    "wireInstructions": {
      "trackingRef": "CIR3XBZZ4N",
      "beneficiary": {
        "name": "CIRCLE INTERNET FINANCIAL INC",
        "address1": "1 Main Street",
        "address2": "Suite 1"
      },
      "beneficiaryBank": {
        "swiftCode": "CRYPTO99",
        "routingNumber": "999999999",
        "accountNumber": "3302726104",
        "currency": "USD",
        "name": "CIRCLE BANKING PARTNER",
        "address": "100 MAIN STREET",
        "city": "NEW YORK",
        "postalCode": "10001",
        "country": "US"
      }
    }
  }
}
```

The repayment account is `unverified` until Circle matches the first incoming
wire repayment to it, after which it transitions to `active`. Cache the
`wireInstructions` block—you reuse it when repaying in Step 6.

<Tip>
  In the sandbox, simulate a matching wire and verify the account by posting a
  mock repayment.

  <Accordion title="Sandbox mock repayment example">
    ```bash theme={null}
    curl -X POST https://api-sandbox.circle.com/v1/credit/mocks/repayments \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "fiatAccountId": "b8627ae8-732b-4d25-b947-1df8f4007a29",
        "amount": { "amount": "100000.00", "currency": "USD" }
      }'
    ```

    ```json theme={null}
    {
      "data": {
        "trackingRef": "CIR3XBZZ4N",
        "amount": { "amount": "100000.00", "currency": "USD" },
        "status": "pending"
      }
    }
    ```
  </Accordion>
</Tip>

## Step 3. Reserve funds for the advance

Call `POST /v1/credit/transfers/reserveFunds` to hold capacity against your
credit line while you initiate the supporting wire. To use Credit Express,
include the optional `destination` field to disburse directly to a verified
address from your Circle Mint recipient address book; omit it to land the
disbursement in your Mint wallet.

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/credit/transfers/reserveFunds \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "destination": {
      "type": "verified_blockchain",
      "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
  }'
```

```json theme={null}
{
  "data": {
    "id": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "funds_reserved",
    "expiresAt": "2024-03-20T15:00:00.000Z",
    "outstanding": { "amount": "100000.00", "currency": "USD" },
    "blockchainDestination": {
      "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "status": "pending"
    },
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-20T14:30:00.000Z"
  }
}
```

Save the transfer `id` from the response—it identifies this draw for the
remaining steps. Reservations expire 30 minutes after creation and only one can
be open per credit line at a time; for the full set of constraints, see
[Settlement Advance lifecycle](/circle-mint/concepts/credit-api#settlement-advance-lifecycle).
If you can't send the wire before the reservation expires, cancel it with
[`PUT /v1/credit/transfers/{id}/cancelReserve`](/api-reference/circle-mint/credit/cancel-credit-transfer-reserve)
to free the capacity immediately.

<Warning>
  Settlement Advance cannot use `POST /v1/credit/transfers` to create a draw.
  That endpoint is for Line of Credit only and returns HTTP 400 for Settlement
  Advance credit lines. Use `reserveFunds` followed by `requestReservedFunds`.
</Warning>

## Step 4. Send the wire and upload wire proof

Using the wire instructions from Step 2, instruct your bank to send a wire to
Circle for the reserved amount. Then upload proof of the wire to request
disbursement by calling `PUT /v1/credit/transfers/{id}/requestReservedFunds`
with a `multipart/form-data` request. Accepted file types are `application/pdf`,
`image/jpeg`, and `image/png`.

```bash theme={null}
curl -X PUT https://api-sandbox.circle.com/v1/credit/transfers/b3d9d2d5-4c12-4946-a09d-953e82fae2b0/requestReservedFunds \
  -H "Authorization: Bearer $API_KEY" \
  -F "fileName=wire-proof.pdf" \
  -F "file=@wire-proof.pdf"
```

```json theme={null}
{
  "data": {
    "id": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "requested",
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-20T14:45:00.000Z"
  }
}
```

The transfer moves from `funds_reserved` to `requested`. Circle's Treasury team
manually reviews the wire proof. In the sandbox the request auto-approves
quickly; in production, approval typically takes 20 minutes to 2 hours.

## Step 5. Observe disbursement and fee accrual

Once Treasury approves the request, the transfer moves to `disbursed` and
`recurringFee` begins accruing daily against the outstanding balance.

### 5.1. Poll the transfer

Call `GET /v1/credit/transfers/{id}` to inspect the disbursement, due date, and
accrued fees.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/credit/transfers/b3d9d2d5-4c12-4946-a09d-953e82fae2b0 \
  -H "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "data": {
    "id": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "disbursed",
    "outstanding": { "amount": "100040.00", "currency": "USD" },
    "fees": {
      "total": { "amount": "40.00", "currency": "USD" },
      "unpaid": { "amount": "40.00", "currency": "USD" }
    },
    "dueDate": "2024-03-28T10:00:00.000Z",
    "disbursedDate": "2024-03-21T10:00:00.000Z",
    "blockchainDestination": {
      "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "status": "complete",
      "transferId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
    },
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-21T10:00:00.000Z"
  }
}
```

The `outstanding` amount is the principal plus accrued fees. Each day the credit
line is open with an outstanding balance, `recurringFee` is applied to the
principal and added to `fees.total`. The `dueDate` is 7 days after
`disbursedDate` for Settlement Advance.

If you reserved with a Credit Express `destination`, the `blockchainDestination`
block tracks the onchain leg separately from the credit transfer. The
`blockchainDestination.transferId` references the underlying Circle Mint
transfer once disbursement initiates onchain.

### 5.2. Subscribe to webhooks

For asynchronous updates, subscribe to `creditTransfers`, `creditFees`, and
`creditRepayments` in the Circle Mint Console. Webhook payloads mirror the
corresponding `GET` endpoints. See
[webhook topics](/circle-mint/concepts/credit-api#webhook-topics) for what each
topic publishes.

## Step 6. Repay by wire

Send a wire from the bank account from Step 2 to Circle for the outstanding
amount (principal plus accrued fees). Use the `wireInstructions` you cached from
Step 2.

In the sandbox, simulate the wire by posting a mock repayment:

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/credit/mocks/repayments \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fiatAccountId": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "amount": { "amount": "100040.00", "currency": "USD" }
  }'
```

```json theme={null}
{
  "data": {
    "trackingRef": "CIR3XBZZ4N",
    "amount": { "amount": "100040.00", "currency": "USD" },
    "status": "pending"
  }
}
```

## Step 7. Confirm the repayment

List repayments filtered to your transfer by calling
`GET /v1/credit/repayments?transferId={id}` and confirm a record exists with
`type: fiat` and `status: completed`.

```bash theme={null}
curl "https://api-sandbox.circle.com/v1/credit/repayments?transferId=b3d9d2d5-4c12-4946-a09d-953e82fae2b0" \
  -H "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "transferId": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0",
      "repaymentAccountId": "b8627ae8-732b-4d25-b947-1df8f4007a29",
      "amountApplied": { "amount": "100040.00", "currency": "USD" },
      "paymentAmount": { "amount": "100040.00", "currency": "USD" },
      "type": "fiat",
      "status": "completed",
      "settlementDate": "2024-03-22T09:30:00.000Z",
      "createDate": "2024-03-22T09:30:00.000Z",
      "updateDate": "2024-03-22T09:30:00.000Z"
    }
  ]
}
```

`paymentAmount` is the total wire received and `amountApplied` is the portion
applied to this transfer's outstanding balance (principal plus fees).
`repaymentAccountId` is the fiat account the wire was matched to—the same
account whose wire instructions you retrieved in Step 2.

Then call `GET /v1/credit/transfers/{id}` again and confirm the transfer is
`paid`.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/credit/transfers/b3d9d2d5-4c12-4946-a09d-953e82fae2b0 \
  -H "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "data": {
    "id": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "paid",
    "outstanding": { "amount": "0.00", "currency": "USD" },
    "fees": {
      "total": { "amount": "40.00", "currency": "USD" },
      "unpaid": { "amount": "0.00", "currency": "USD" }
    },
    "dueDate": "2024-03-28T10:00:00.000Z",
    "paidDate": "2024-03-22T09:30:00.000Z",
    "disbursedDate": "2024-03-21T10:00:00.000Z",
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-22T09:30:00.000Z"
  }
}
```

The transfer now shows `status: paid`, `outstanding` is zero, and `fees.unpaid`
is zero—the draw lifecycle is complete.

<Warning>
  Settlement Advance does not support crypto repayment. `POST
      /v1/credit/cryptoRepayment` returns HTTP 400 for Settlement Advance credit
  lines. Repay by wire only.
</Warning>

* [Getting Started](/circle-mint/quickstarts/getting-started): API
  authentication and account setup.