POST /transaction — Process a cash transaction

The /transaction endpoint is the core of the Centsless API. You send a transaction, and the engine resolves the jurisdiction, applies the correct rounding rule for that location, and returns the legally correct cash total — complete with compliance certification and a fraud score. Every transaction is committed to an immutable audit hash chain, giving you a tamper-evident record for regulators and auditors.

Endpoint

POST https://api.centsless.org/api/v1/transaction

Authentication

All requests require an x-api-key header. Use your merchant key or partner key.

string

required

Your merchant or partner API key.

Request body

string

required

Unique merchant identifier issued by Centsless or your POS vendor.

integer

required

Pre-tax subtotal in cents. Tax is always calculated on this pre-rounded amount.

integer

required

Sales tax in cents. Always pass the tax calculated on the pre-rounded subtotal — never recalculate tax after rounding.

string

required

Payment tender type. One of: cash, card, ebt, mobile. Only cash transactions are subject to rounding. EBT transactions are never rounded per 7 CFR 278.2.

string

ZIP code for automatic jurisdiction resolution. Recommended — the engine resolves state, county, city, and the applicable rounding rule from a single field.

string

Two-letter state code (e.g., AZ, IN). Use when you don’t have a ZIP code.

string

County name for sub-state jurisdiction resolution. Combined with state for county-level rules.

string

City name for municipal-level jurisdiction resolution. Combined with state and county.

string

Explicit rounding mode override. One of: swedish_rounding, mandatory_round_down, mandatory_round_up, symmetrical_rounding, nearest_nickel, none. Use for testing only — omit this field in production to let the engine resolve the correct rule for the jurisdiction.

string

Store location identifier for multi-location merchants.

string

POS terminal identifier. Included in the audit record.

string

Cashier or employee identifier. Included in the audit record.

boolean

Set to true when the customer is splitting payment across multiple tender types.

array

Array of tender components for split tender transactions. Each item has a type (one of cash, card, ebt, mobile) and an amount_cents integer.

Examples

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": "YOUR-MERCHANT-ID",
    "subtotal_cents": 523,
    "tax_total_cents": 200,
    "payment_method": "cash",
    "zip_code": "85001"
  }'

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": "YOUR-MERCHANT-ID",
    "subtotal_cents": 523,
    "tax_total_cents": 200,
    "payment_method": "cash",
    "state": "IN"
  }'

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": "YOUR-MERCHANT-ID",
    "subtotal_cents": 523,
    "tax_total_cents": 200,
    "payment_method": "ebt",
    "state": "AZ"
  }'

Response fields

object

The processed transaction record.

Show properties

string

Unique transaction identifier. Format: TXN-YYYY-MM-DD-XXXXXXXX (e.g., TXN-2026-04-14-A82C2EAA).

object

Rounding calculation results.

Show properties

integer

Post-rounded cash total to collect from the customer, in cents.

integer

The rounding adjustment in cents — the difference between the ledger total and the cash total. Positive means rounded up, negative means rounded down.

string

The rounding method applied to this transaction (e.g., swedish_rounding).

string

The resolved jurisdiction identifier (e.g., US-AZ).

object

Compliance certification for this transaction.

Show properties

string

Overall compliance result. One of: PASS, WARN, or FAIL.

integer

Fraud risk score for this transaction. 0 means no detected risk.

string

Risk classification. One of: NONE, LOW, MEDIUM, HIGH, CRITICAL.

string

SHA-256 hash of this transaction record. Each hash includes the previous transaction’s hash, forming a tamper-evident chain.

Response example

{
  "success": true,
  "transaction": {
    "id": "TXN-2026-04-14-A82C2EAA",
    "calculation": {
      "subtotal_cents": 523,
      "tax_total_cents": 200,
      "ledger_total_cents": 723,
      "cash_total_cents": 725,
      "rounding_delta_cents": 2,
      "payment_method": "cash",
      "cash_rounding_mode": "swedish_rounding",
      "jurisdiction": "US-AZ",
      "rounding_applied": true
    },
    "compliance": {
      "compliance_status": "PASS"
    },
    "fraud_score": 0,
    "risk_level": "NONE"
  }
}

The customer pays **

7.25** instead of

7.23. The 2-cent rounding delta is applied per Arizona HB 2938 (mandatory Swedish rounding).

Overview

Transactions

Jurisdiction

Tipping

Compliance & Audit

POST /transaction — Process a cash transaction

Endpoint

Authentication

Request body

Examples

Response fields

Response example

​Endpoint

​Authentication

​Request body

​Examples

​Response fields

​Response example

Endpoint

Authentication

Request body

Examples

Response fields

Response example