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

# Onchain Settlement: How Retempo Proves Payments on Arc

> Retempo records USDC payment proof on Arc using the RetempoSettlement contract. Learn how offchain and onchain components work together.

Retempo uses a hybrid settlement model: your billing data — services, plans, and invoices — lives in Retempo's offchain infrastructure, while every completed payment is permanently proved onchain. When a settlement finalizes, Retempo's backend writes a compact, tamper-proof record to the **RetempoSettlement** contract on the Arc blockchain. The result is a system that combines the speed and flexibility of traditional APIs with the verifiability of a public ledger.

## Why onchain settlement?

Storing a settlement proof onchain gives you guarantees that a database record alone cannot provide.

* **Immutability.** Once Retempo writes a settlement to Arc, no party — including Retempo — can alter or delete it. The record exists independently of Retempo's servers.
* **Public verifiability.** Anyone with the Arc transaction hash can look up the settlement on the Arc explorer and confirm that a specific amount was settled between a payer and a merchant at a specific time.
* **Audit trail.** The Arc transaction hash serves as a durable reference you can include in your own accounting systems, compliance reports, or dispute resolution processes.

## What is recorded onchain?

Retempo does not replicate your full billing history to the blockchain. Instead, the **RetempoSettlement** contract stores a minimal settlement proof containing exactly the fields needed for verification.

| Field           | Description                                            |
| --------------- | ------------------------------------------------------ |
| `invoiceId`     | The Retempo invoice this settlement closes             |
| `serviceId`     | The service the invoice belongs to                     |
| `payer`         | The payer's Arc wallet address                         |
| `merchant`      | The merchant's Arc wallet address                      |
| `amount`        | The settled amount in USDC micro-units                 |
| `referenceHash` | A 32-byte hash you supply as a unique proof identifier |
| `timestamp`     | Unix timestamp of the settlement                       |

Your plan history, subscription metadata, and invoice line items remain offchain in Retempo's database. The onchain record is purely a proof of settlement.

## Settlement flow

When you call `POST /api/v1/settlements`, Retempo executes the following sequence before returning a confirmed response.

<Steps>
  <Step title="Create settlement record">
    Retempo creates a settlement record in its database with status **PENDING** and validates all input fields, including your `referenceHash`.
  </Step>

  <Step title="Submit Arc transaction">
    Retempo's backend encodes and submits a `recordSettlement()` call to the RetempoSettlement contract on Arc Testnet using an authorized operator wallet.
  </Step>

  <Step title="Wait for receipt">
    The backend waits for a real Arc transaction receipt — there is no optimistic confirmation. The transaction must be mined before the flow continues.
  </Step>

  <Step title="Verify the event">
    Retempo inspects the receipt for a `SettlementRecorded` event. If the event is absent or the receipt status is not `success`, the settlement is **not** confirmed.
  </Step>

  <Step title="Mark settlement CONFIRMED">
    Once the event is observed in a successful receipt, Retempo marks the settlement **CONFIRMED** and the invoice **PAID**. The Arc transaction hash is stored and returned to you.
  </Step>
</Steps>

<Note>
  Retempo never marks a settlement CONFIRMED without a real Arc transaction receipt and SettlementRecorded event.
</Note>

## What you see as a customer

Every settlement response includes a `chain` object that surfaces the onchain details directly.

```json theme={null}
{
  "chain": {
    "transactionHash": "0xabc123...def456",
    "receiptStatus": "success",
    "eventObserved": true,
    "executor": "circle",
    "circleTransactionId": "ctxn_...",
    "circleTransactionState": "CONFIRMED"
  }
}
```

| Field             | What it tells you                                                                       |
| ----------------- | --------------------------------------------------------------------------------------- |
| `transactionHash` | The Arc transaction hash — use this to verify the settlement on the Arc explorer        |
| `receiptStatus`   | `"success"` means the Arc transaction was mined without reverting                       |
| `eventObserved`   | `true` means Retempo confirmed the `SettlementRecorded` event is present in the receipt |

Take the `transactionHash` value and look it up on the Arc Testnet explorer to independently verify the settlement. You will see the `SettlementRecorded` event with all the fields Retempo recorded on your behalf.

<Tip>
  Store the `transactionHash` in your own system alongside the invoice ID. It gives you a portable, trust-minimized reference to the settlement that does not depend on Retempo's API being available.
</Tip>