Skip to main content
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.
FieldDescription
invoiceIdThe Retempo invoice this settlement closes
serviceIdThe service the invoice belongs to
payerThe payer’s Arc wallet address
merchantThe merchant’s Arc wallet address
amountThe settled amount in USDC micro-units
referenceHashA 32-byte hash you supply as a unique proof identifier
timestampUnix 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.
1

Create settlement record

Retempo creates a settlement record in its database with status PENDING and validates all input fields, including your referenceHash.
2

Submit Arc transaction

Retempo’s backend encodes and submits a recordSettlement() call to the RetempoSettlement contract on Arc Testnet using an authorized operator wallet.
3

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.
4

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.
5

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.
Retempo never marks a settlement CONFIRMED without a real Arc transaction receipt and SettlementRecorded event.

​
What you see as a customer

Every settlement response includes a chain object that surfaces the onchain details directly. 
{
  "chain": {
    "transactionHash": "0xabc123...def456",
    "receiptStatus": "success",
    "eventObserved": true,
    "executor": "circle",
    "circleTransactionId": "ctxn_...",
    "circleTransactionState": "CONFIRMED"
  }
}
FieldWhat it tells you
transactionHashThe Arc transaction hash — use this to verify the settlement on the Arc explorer
receiptStatus"success" means the Arc transaction was mined without reverting
eventObservedtrue 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.
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.