POST /api/v1/settlements — Submit a USDC Settlement

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

string

required

The ID of the invoice this settlement closes.

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.

string

required

The EVM wallet address of the payer. Must be a valid, non-zero checksummed address.

string

required

The EVM wallet address of the merchant. Must be a valid, non-zero checksummed address.

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.

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.

string | number

The settlement amount as a decimal string or number. If omitted, Retempo uses the invoice amount. Must be a non-negative decimal.

string

The currency of the settlement. Defaults to the invoice currency if omitted.

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.

object

The confirmed settlement record with related objects.

Show settlement fields

string

Unique identifier for the settlement.

string

ID of the closed invoice.

string

ID of the associated service.

string

Retempo user ID of the payer.

string

Retempo user ID of the merchant.

string

Settled amount as a decimal string with six decimal places.

string

Currency of the settlement.

string

The reference hash you supplied.

string

The on-chain transaction hash.

string

CONFIRMED once the on-chain receipt is verified, or FAILED if the transaction did not succeed.

string

Datetime the settlement was recorded.

string

ISO 8601 datetime the settlement was created.

object

Nested invoice object.

object

Nested service object.

object

Nested payer user object.

object

Nested merchant user object.

object

On-chain transaction details returned alongside the settlement.

Show chain fields

string

The on-chain transaction hash.

string

Receipt status — success when confirmed.

boolean

true when the SettlementRecorded event was detected in the transaction receipt.

string

The execution method used — direct or circle.

string | null

Circle transaction identifier when the circle executor was used, otherwise absent.

string | null

Circle transaction state when applicable — e.g. COMPLETE. Otherwise absent.

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

Status	Message	Condition
`400 Bad Request`	`invoiceId is required.`	`invoiceId` was omitted.
`400 Bad Request`	`referenceHash is required.`	`referenceHash` was omitted.
`400 Bad Request`	`referenceHash must be a 32-byte hex value.`	The hash is not `0x` + exactly 64 hex characters.
`400 Bad Request`	`payerAddress must be a valid address.`	`payerAddress` is missing or is not a valid EVM address.
`400 Bad Request`	`merchantAddress must be a valid address.`	`merchantAddress` is missing or is not a valid EVM address.
`400 Bad Request`	`Settlement payer must match the invoice user.`	The provided `payerId` does not match the invoice’s `userId`.
`400 Bad Request`	`Settlement merchant must match the service owner.`	The provided `merchantId` does not match the service’s `ownerId`.
`404 Not Found`	`Referenced 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.

Overview

Services

Payment Plans

Checkout & Invoicing

Settlements

POST /api/v1/settlements — Submit a USDC Settlement

Request Body

Response

201 — Settlement confirmed

Example Request

Error Codes

Idempotency

​Request Body

​Response

​201 — Settlement confirmed

​Example Request

​Error Codes

​Idempotency

Request Body

Response

201 — Settlement confirmed

Example Request

Error Codes

Idempotency