Quickstart: Build Your First Retempo Integration End-to-End

By the end of this guide you will have a fully wired Retempo integration: a live service with a monthly USDC payment plan, a checkout session ready to onboard a subscriber, an open invoice, and a settlement submitted to Arc for onchain confirmation. Every step maps to a single API call against https://api.retempo.xyz.

Create a Service

A service represents what you are selling. Send a POST request to /api/v1/services with a name, an optional description, and the owner’s email address. Set status to ACTIVE so that subscribers can check out immediately.

curl --request POST \
  --url https://api.retempo.xyz/api/v1/services \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Inference API",
    "description": "High-throughput LLM inference endpoint with usage-based and fixed plans.",
    "owner": {
      "email": "you@example.com"
    },
    "status": "ACTIVE"
  }'

Retempo returns the new service record, including its generated id. Copy the id — you will use it in the next step.

{
  "service": {
    "id": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
    "name": "Inference API",
    "description": "High-throughput LLM inference endpoint with usage-based and fixed plans.",
    "owner": {
      "email": "you@example.com"
    },
    "status": "ACTIVE",
    "createdAt": "2024-11-01T10:00:00.000Z",
    "updatedAt": "2024-11-01T10:00:00.000Z"
  }
}

Add a Payment Plan

A payment plan defines the price and billing cadence for your service. Post to /api/v1/services/:serviceId/plans, replacing :serviceId with the id you received above. This example creates a fixed $49.00 USDC monthly plan.

curl --request POST \
  --url https://api.retempo.xyz/api/v1/services/svc_01j9kqzr2e4f5g6h7j8k9l0m/plans \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Pro Monthly",
    "pricingType": "FIXED_RECURRING",
    "billingInterval": "MONTH",
    "amount": "49.00",
    "currency": "USDC"
  }'

The response includes the plan’s id. Copy both serviceId and planId — you will need them for the checkout session.

{
  "plan": {
    "id": "plan_02k1lrzs3f5g6h7j8k9l0m1n",
    "serviceId": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
    "name": "Pro Monthly",
    "pricingType": "FIXED_RECURRING",
    "billingInterval": "MONTH",
    "amount": "49.00",
    "currency": "USDC",
    "createdAt": "2024-11-01T10:01:00.000Z",
    "updatedAt": "2024-11-01T10:01:00.000Z"
  }
}

Open a Checkout Session

A checkout session gives your subscriber a way to complete payment and activate their subscription. Post to /api/v1/checkout-sessions with the serviceId and paymentPlanId. The session starts in PENDING status and includes an id you can use to build a checkout URL pointing to https://retempo.xyz/checkout/:checkoutSessionId.

curl --request POST \
  --url https://api.retempo.xyz/api/v1/checkout-sessions \
  --header 'Content-Type: application/json' \
  --data '{
    "serviceId": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
    "paymentPlanId": "plan_02k1lrzs3f5g6h7j8k9l0m1n"
  }'

When the subscriber completes the session, Retempo automatically creates a subscription and the session status moves from PENDING to PAID.

{
  "checkoutSession": {
    "id": "cs_03l2msat4g6h7j8k9l0m1n2o",
    "serviceId": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
    "paymentPlanId": "plan_02k1lrzs3f5g6h7j8k9l0m1n",
    "status": "PENDING",
    "expiresAt": "2024-11-01T11:01:00.000Z",
    "createdAt": "2024-11-01T10:02:00.000Z"
  }
}

Create an Invoice

An invoice is the billing record for a subscription cycle. Post to /api/v1/invoices with the service, plan, and subscriber identifiers. Set status to OPEN to signal that the invoice is ready for settlement.

curl --request POST \
  --url https://api.retempo.xyz/api/v1/invoices \
  --header 'Content-Type: application/json' \
  --data '{
    "serviceId": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
    "paymentPlanId": "plan_02k1lrzs3f5g6h7j8k9l0m1n",
    "userId": "usr_subscriber_abc123",
    "amount": "49.00",
    "status": "OPEN"
  }'

Copy the invoice id — you will reference it when you submit the settlement.

{
  "invoice": {
    "id": "inv_04m3ntbu5h7j8k9l0m1n2o3p",
    "serviceId": "svc_01j9kqzr2e4f5g6h7j8k9l0m",
    "paymentPlanId": "plan_02k1lrzs3f5g6h7j8k9l0m1n",
    "userId": "usr_subscriber_abc123",
    "amount": "49.00",
    "currency": "USDC",
    "status": "OPEN",
    "createdAt": "2024-11-01T10:03:00.000Z",
    "updatedAt": "2024-11-01T10:03:00.000Z"
  }
}

Submit a Settlement

A settlement submits the payment proof to Arc for onchain confirmation. Post to /api/v1/settlements with the invoice ID, a 32-byte hex reference hash, and the payer and merchant wallet addresses. Retempo submits the transaction to Arc and monitors for confirmation.

curl --request POST \
  --url https://api.retempo.xyz/api/v1/settlements \
  --header 'Content-Type: application/json' \
  --data '{
    "invoiceId": "inv_04m3ntbu5h7j8k9l0m1n2o3p",
    "referenceHash": "0xabc123def456abc123def456abc123def456abc123def456abc123def456abcd",
    "payerAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "merchantAddress": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"
  }'

Retempo creates the settlement record in PENDING status and submits the transaction to Arc. Once the chain confirms the transaction and records the settlement event, the status moves to CONFIRMED and the linked invoice is marked PAID.

{
  "settlement": {
    "id": "stl_05n4oucv6j8k9l0m1n2o3p4q",
    "invoiceId": "inv_04m3ntbu5h7j8k9l0m1n2o3p",
    "referenceHash": "0xabc123def456abc123def456abc123def456abc123def456abc123def456abcd",
    "payerAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "merchantAddress": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
    "amount": "49.00",
    "currency": "USDC",
    "status": "PENDING",
    "transactionHash": null,
    "createdAt": "2024-11-01T10:04:00.000Z",
    "updatedAt": "2024-11-01T10:04:00.000Z"
  }
}

Settlements are only marked CONFIRMED after a real Arc transaction receipt is observed. Until then, the settlement remains in PENDING or SUBMITTED status and the invoice stays OPEN.

Get Started

Core Workflows

Usage Billing

Onchain Settlement

Reference

Quickstart: Build Your First Retempo Integration End-to-End