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

# Bill pay with crypto

> Pay real-world bills directly with stablecoins.

Bill pay lets your users pay real-world bills, like credit cards, loans, and utilities,
directly with crypto. You link the user's bills once, then pay any of them by settling
crypto over the `bill_pay` rail.

## Before you start

* Authenticate as an integrator and act on behalf of a verified user. See
  [Authentication](/guides/authentication) and [Onboarding](/guides/onboarding).
* Confirm the user's `bill_pay` capability is `active`
  (see [capabilities](/guides/onboarding#3-read-capabilities)).

## Link the user's bills

Start activation. The `consent` object records the user accepting the bill pay terms.

```bash theme={null}
curl -X POST https://platform.spritz.finance/v1/bills/activate \
  -H "Content-Type: application/json" \
  # plus your integrator signing headers and the user's Authorization (see Authentication)
  -d '{
    "consent": {
      "termsText": "...",
      "termsTextVersion": "2026-01-01",
      "acceptedAt": "2026-07-01T10:00:00.000Z"
    }
  }'
```

```json theme={null}
{
  "status": "verification_required",
  "activationId": "...",
  "verification": {
    "status": "challenge_required",
    "challenge": {
      "questions": [
        { "id": "q1", "prompt": "Which of these is a past address?", "options": [
          { "id": "o1", "text": "..." }, { "id": "o2", "text": "..." }
        ] }
      ]
    }
  }
}
```

If `status` is `activated` or `already_active`, you're done and bills will sync. If it's
`verification_required`, run the identity challenge:

<Steps>
  <Step title="Start verification">
    ```bash theme={null}
    curl -X POST https://platform.spritz.finance/v1/bills/start_verification \
      # plus signing headers and the user's Authorization
      -d '{ "activationId": "..." }'
    ```
  </Step>

  <Step title="Present the questions and submit answers">
    Show the `challenge.questions` to the user (they're multiple choice), then submit
    their selections.

    ```bash theme={null}
    curl -X POST https://platform.spritz.finance/v1/bills/submit_verification/{activationId} \
      # plus signing headers and the user's Authorization
      -d '{ "responses": [ { "questionId": "q1", "value": "o2" } ] }'
    ```
  </Step>
</Steps>

## List bills

Once activated, the user's bills sync. List them to get balances and due dates:

```bash theme={null}
curl "https://platform.spritz.finance/v1/bills/" \
  # plus signing headers and the user's Authorization
```

```json theme={null}
[
  {
    "id": "6a43ac369288351e982157b9",
    "status": "active",
    "name": "Chase Sapphire Card",
    "type": "credit_card",
    "accountNumberLast4": "4567",
    "currency": "USD",
    "liability": {
      "balance": "240.23",
      "amountDue": "28.34",
      "minimumPayment": "28.34",
      "nextPaymentDueDate": "2026-07-15"
    }
  }
]
```

A bill's `type` is one of `credit_card`, `auto_loan`, `loan`, `student_loan`,
`mortgage`, `mobile_phone`, `utility`, or `unknown`. Only bills with `status: "active"`
can be paid.

## Pay a bill

Paying a bill uses the same quote-based flow as an [off-ramp](/guides/use-cases/off-ramp),
with the bill as the destination and the `bill_pay` rail:

```bash theme={null}
curl -X POST https://platform.spritz.finance/v1/off-ramp-quotes/ \
  -H "Content-Type: application/json" \
  # plus signing headers and the user's Authorization
  -d '{
    "accountId": "6a43ac369288351e982157b9",
    "amount": "28.34",
    "amountMode": "output",
    "rail": "bill_pay",
    "chain": "ethereum",
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  }'
```

From there the flow is identical to an off-ramp: fetch the transaction parameters, have
the user execute the payment on-chain, and track settlement. See the
[off-ramp guide](/guides/use-cases/off-ramp) for those steps, and use the `payment.*`
[webhooks](/guides/webhooks) to follow the bill payment to completion.

## Remove a bill

```bash theme={null}
curl -X DELETE https://platform.spritz.finance/v1/bills/{billId} \
  # plus signing headers and the user's Authorization
```

## Related

<CardGroup cols={2}>
  <Card title="Off-ramp" icon="arrow-right-from-bracket" href="/guides/use-cases/off-ramp">
    The quote-and-settle flow bill payments build on.
  </Card>

  <Card title="Webhooks" icon="bell" href="/guides/webhooks">
    Track bill payments with payment events.
  </Card>
</CardGroup>