Skip to main content
Submitting a settlement closes an invoice by recording proof of USDC payment on Arc. You provide the invoice ID, a unique reference hash, and the payer and merchant wallet addresses. Retempo submits the transaction, waits for an on-chain receipt and a SettlementRecorded event, then returns the settlement as CONFIRMED. The associated invoice is automatically marked PAID at the same time. 
POST https://api.retempo.xyz/api/v1/settlements

​
Request Body

​
invoiceId
string
required
The ID of the invoice this settlement closes.
​
referenceHash
string
required
A unique 32-byte identifier for this settlement, encoded as a hex string — 0x followed by exactly 64 hex characters (e.g. 0xabcdef12...). You generate this value and use it to deduplicate submissions. Submissions with a malformed hash are rejected with 400.
​
payerAddress
string
required
The EVM wallet address of the payer. Must be a valid, non-zero checksummed address.
​
merchantAddress
string
required
The EVM wallet address of the merchant. Must be a valid, non-zero checksummed address.
​
payerId
string
The Retempo user ID of the payer. If provided, it must match the userId on the invoice. If omitted, defaults to the invoice’s userId.
​
merchantId
string
The Retempo user ID of the merchant. If provided, it must match the ownerId of the associated service. If omitted, defaults to the service owner.
​
amount
string | number
The settlement amount as a decimal string or number. If omitted, Retempo uses the invoice amount. Must be a non-negative decimal.
​
currency
string
The currency of the settlement. Defaults to the invoice currency if omitted.
​
recordedAt
string
An ISO 8601 datetime string for when the settlement occurred. Defaults to the time of the API call if omitted.

​
Response

A successful settlement returns HTTP 201 Created with both a settlement object and a chain object containing the on-chain transaction details.
​
settlement
object
The confirmed settlement record with related objects.
​
chain
object
On-chain transaction details returned alongside the settlement.

​
201 — Settlement confirmed

{
  "settlement": {
    "id": "clz1settle222",
    "invoiceId": "clz1invoice999",
    "serviceId": "clz1abc2def3ghi4",
    "payerId": "clz1user111",
    "merchantId": "clz1owner123",
    "amount": "49.000000",
    "currency": "USDC",
    "referenceHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "transactionHash": "0x9f8e7d6c5b4a392817263544536271819f0e1d2c3b4a5968...",
    "status": "CONFIRMED",
    "recordedAt": "2025-06-01T10:20:00.000Z",
    "createdAt": "2025-06-01T10:20:00.000Z",
    "invoice": {
      "id": "clz1invoice999",
      "status": "PAID",
      "amount": "49.000000",
      "currency": "USDC",
      "paidAt": "2025-06-01T10:20:00.000Z"
    },
    "service": {
      "id": "clz1abc2def3ghi4",
      "name": "DataStream Pro"
    },
    "payer": {
      "id": "clz1user111",
      "email": "subscriber@example.com"
    },
    "merchant": {
      "id": "clz1owner123",
      "email": "owner@datastreampro.com"
    }
  },
  "chain": {
    "transactionHash": "0x9f8e7d6c5b4a392817263544536271819f0e1d2c3b4a5968...",
    "receiptStatus": "success",
    "eventObserved": true,
    "executor": "direct",
    "circleTransactionId": null,
    "circleTransactionState": null
  }
}

​
Example Request

curl -X POST https://api.retempo.xyz/api/v1/settlements \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "clz1invoice999",
    "referenceHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "payerAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "merchantAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "amount": "49.000000"
  }'

​
Error Codes

StatusMessageCondition
400 Bad RequestinvoiceId is required.invoiceId was omitted.
400 Bad RequestreferenceHash is required.referenceHash was omitted.
400 Bad RequestreferenceHash must be a 32-byte hex value.The hash is not 0x + exactly 64 hex characters.
400 Bad RequestpayerAddress must be a valid address.payerAddress is missing or is not a valid EVM address.
400 Bad RequestmerchantAddress must be a valid address.merchantAddress is missing or is not a valid EVM address.
400 Bad RequestSettlement payer must match the invoice user.The provided payerId does not match the invoice’s userId.
400 Bad RequestSettlement merchant must match the service owner.The provided merchantId does not match the service’s ownerId.
404 Not FoundReferenced database record was not found.The invoiceId was not found.
500 Internal Server Error(error message)The on-chain transaction failed or could not be verified.

​
Idempotency

Settlements are idempotent on the combination of invoiceId and referenceHash. If you submit a settlement with the same pair and a matching settlement already exists in CONFIRMED status, Retempo returns 200 with the existing settlement record instead of creating a duplicate. Use this behavior to safely retry on network failures without risk of double-charging.
The referenceHash must be exactly 32 bytes as a hex string — 0x followed by exactly 64 hex characters. Submissions with a malformed hash are rejected immediately with a 400 error and the message "referenceHash must be a 32-byte hex value.".
A settlement is marked CONFIRMED only after a real on-chain transaction receipt and SettlementRecorded event are observed. The endpoint does not return until that verification is complete. If verification fails, the settlement is recorded as FAILED and a 500 is returned.