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

# Integrate Centsless into your POS platform

> A step-by-step guide to integrating the Centsless API into your POS platform. Covers onboarding merchants, processing transactions, and handling edge cases.

Centsless is designed for POS vendors who want to add multi-state cash rounding compliance for all their merchants with a single integration. You authenticate once with a partner API key, provision your merchants through that key, and then submit transactions on their behalf — the engine resolves the correct jurisdiction and rounding rule automatically for every cash sale.

## Integration overview

<Steps>
  <Step title="Get a Partner API key">
    Contact Centsless to obtain a partner API key. Partner keys carry the prefix `centsless_partner_` and grant vendor-scoped access for merchant onboarding and transaction processing across your platform.
  </Step>

  <Step title="Provision each merchant">
    Before processing transactions, register each merchant on the Centsless platform using your partner key. Include a `merchant_id` that matches your internal merchant identifier — you'll send this field with every transaction to associate it with the correct merchant record.
  </Step>

  <Step title="Process transactions">
    Submit each cash transaction to `POST /transaction` with `merchant_id`, the amounts (`subtotal_cents` and `tax_total_cents`), `payment_method`, and either `zip_code` (recommended) or `state` for jurisdiction resolution. The engine applies the correct rounding rule and returns the rounded total in real time.
  </Step>

  <Step title="Display the rounded amount">
    Surface `cash_total_cents` from the response on your cashier-facing and customer-facing displays. This is the legally correct amount for the customer to pay.
  </Step>

  <Step title="Store the transaction ID">
    Persist the transaction `id` returned in the response. You'll need it to generate compliance receipts and to submit any subsequent overrides or voids against this transaction.
  </Step>
</Steps>

## Minimal transaction request

The four required fields are `merchant_id`, `subtotal_cents`, `tax_total_cents`, and `payment_method`. Adding `zip_code` enables automatic jurisdiction resolution.

```bash theme={null}
curl -X POST https://api.centsless.org/api/v1/transaction \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "merchant_id": "MERCHANT-001",
    "subtotal_cents": 1299,
    "tax_total_cents": 104,
    "payment_method": "cash",
    "zip_code": "85001"
  }'
```

## Response fields to surface in your POS UI

The transaction response contains several fields your integration should act on:

| Field                        | Where to surface it                                                         |
| ---------------------------- | --------------------------------------------------------------------------- |
| `cash_total_cents`           | Amount to collect from the customer — show on cashier and customer displays |
| `rounding_delta_cents`       | Display on the receipt as a rounding adjustment line item                   |
| `cash_rounding_mode`         | Log for compliance recordkeeping                                            |
| `compliance_status`          | Alert the cashier or manager if the value is `WARN` or `FAIL`               |
| `fraud_score` / `risk_level` | Flag for manager review if the risk level is elevated                       |

<Note>
  Always pass `zip_code` for automatic jurisdiction resolution. The engine resolves state, county, and city from the ZIP and applies the correct rounding rule for that location. Only fall back to `state`, `county`, or `city` fields if you don't have ZIP data for a merchant location.
</Note>

<Tip>
  Pass `terminal_id` and `cashier_id` on every transaction request. These optional fields are stored with the transaction record and provide employee-level audit attribution, which is essential for compliance investigations and override reporting.
</Tip>