Rendben API documentation

USING CLAUDE CODE OR CHATGPT DESKTOP?

Give your coding assistant the right context.

Create a scoped API key, save it in your application environment, then give your assistant this documentation link to start the integration.

1
Complete human verification
Sign in with Google and verify the settlement wallet. Rendben never asks your AI for a seed phrase or private key.
Open setup guide
2
Store it securely
Save it as RENDBEN_API_KEY in the application's server environment. Never paste an API key into a chat.
3
Let your AI continue
With a read-write key, it can inspect setup, reserve the store URL, create products and prepare checkout links.
Create API key

https://rendben.com/docs/api

Copies the public documentation URL, not your API key.

MCP

OFFICIAL MCP ACTIONS

Let an agent pay without sharing its wallet secret.

Connect to Rendben's sessionless Streamable HTTP endpoint at https://rendben.com/mcp. Give an agent a public checkout link, or let a merchant create a payment capability with an API key. Rendben prepares unsigned transaction bytes. The agent reviews the exact terms, signs locally and submits through its own wallet or trusted Solana RPC.

1. INSPECT

Resolve the public checkout

The agent verifies the active merchant, product, exact amount and recurring interval before continuing.

2. PREPARE

Set a hard ceiling

The payer supplies its email, public wallet address and an explicit maximum USDC amount. No API key is needed for a public checkout.

3. SIGN LOCALLY

The secret never leaves

Rendben returns base64 transaction bytes. A local wallet signs and sends them.

4. VERIFY

Read payment status

Check one-time confirmation or subscription activation after submitting the signed transaction.

MCP connection

{
  "mcpServers": {
    "rendben": {
      "type": "http",
      "url": "https://rendben.com/mcp",
      "headers": {
        "Authorization": "Bearer ${RENDBEN_API_KEY}"
      }
    }
  }
}

Available tools

rendben_inspect_checkout
rendben_prepare_checkout_payment
rendben_create_payment_intent
rendben_prepare_usdc_payment
rendben_get_payment_status
rendben_get_subscription_status

Never pass a seed phrase or private key.

The MCP tools do not accept wallet secrets. Use an isolated wallet, keep its signer local and enforce a per-payment or daily policy in the wallet layer.

QUICK START

Verify access in one request.

Create a read-only key in your dashboard, keep it in your backend environment and send it as a Bearer token. This example answers the question your product actually needs: should this customer have access?

TypeScript

const response = await fetch(
  "https://rendben.com/api/v1/subscriptions?" +
    new URLSearchParams({
      customer_reference: "google-user-48391",
      product_id: "prod_ciocu_basic_2026",
    }),
  {
    headers: {
      Authorization: `Bearer ${process.env.RENDBEN_API_KEY}`,
    },
  },
);

if (!response.ok) throw new Error("Rendben verification failed");

const result = await response.json();
const hasAccess = result.hasActiveSubscription;

Keep API keys on the server.

Never place a Rendben key in browser code, a mobile app bundle or a public repository.

AUTHENTICATION

One workspace. Two permission levels.

Send your key on every request using the standard Authorization header.

HTTP header

Authorization: Bearer rdb_live_your_key

READ ONLY

Verify and reconcile

List products, subscriptions and orders. Recommended for entitlement checks.

READ AND WRITE

Configure and sell

Includes every read operation and can configure the storefront, create products and checkouts, and cancel customer renewals.

SAFE WRITES

Retry without creating duplicates.

Every public write request requires an Idempotency-Key header containing 8 to 128 safe characters. Repeating the same key and body returns the original response for 24 hours. Reusing a key with different JSON returns HTTP 409.

Required header

Idempotency-Key: order_8f2b7f46

API REFERENCE

Thirteen focused endpoints.

Read setup status/setupGET Read storefront/storefrontGET Configure storefront/storefrontPUT List products/productsGET Create product/productsPOST Create payment intent/payment-intentsPOST Retrieve payment intent/payment-intents/:idGET Create refund/refundsPOST Retrieve refund/refunds/:idGET Create subscription checkout/subscription-checkoutsPOST Verify subscription/subscriptionsGET Cancel subscription/subscriptions/:id/cancelPOST Verify order/ordersGET

GET/setup

Read workspace setup status

Lets an AI identify whether the human-controlled wallet step is complete and whether storefront, product and checkout preparation can continue.

Request

curl https://rendben.com/api/v1/setup \
  -H "Authorization: Bearer $RENDBEN_API_KEY"

The wallet boundary stays human.

The API reports wallet readiness but cannot access, replace or recover the wallet's seed phrase or private key.

GET/storefront

Read storefront settings

Returns the reserved store URL, currency, public merchant details and optional logo. A new workspace returns storefront: null.

PUT/storefront

Configure the storefront

Reserves or updates the workspace's unique Rendben store URL. The human owner must verify the settlement wallet first. This endpoint requires a read-write key and an Idempotency-Key.

Parameter	Type	Description
`slug`Required	string	Unique 3 to 32 character Rendben subdomain.
`logoImageUrl`	URL	Optional HTTPS square store logo.
`websiteUrl`	URL	Optional public merchant website.
`supportEmail`	email	Optional public customer-support address.
`refundPolicyUrl`	URL	Optional public refund-policy page.

Request

curl https://rendben.com/api/v1/storefront \
  -X PUT \
  -H "Authorization: Bearer $RENDBEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: storefront_ciocu_v1" \
  -d '{
    "slug": "ciocu",
    "websiteUrl": "https://ciocu.app",
    "supportEmail": "support@ciocu.app"
  }'

GET/products

List products

Returns every product in the API key's workspace, including pricing and recurring billing details.

Request

curl https://rendben.com/api/v1/products \
  -H "Authorization: Bearer $RENDBEN_API_KEY"

POST/products

Create a product

Creates a one-time or recurring USDC product. This endpoint requires a read and write key.

Send a unique Idempotency-Key for each intended product creation.

Parameter	Type	Description
`name`Required	string	Customer-facing product name.
`description`Required	string	Short explanation of what the customer receives.
`priceUsdc`Required	string	Price in USDC. Minimum 1 USDC.
`pricingModel`Required	enum	one_time or recurring.
`billingInterval`	object	Required for recurring products. Use day, week, month or year. A quarterly plan uses month with count 3.
`returnUrl`	URL	Optional page shown after a completed payment.
`coverImageUrl`	URL	Optional HTTPS product image.

JSON body

{
  "name": "Ciocu Pro",
  "description": "Voice, sync and monthly allowance",
  "returnUrl": "https://ciocu.app/billing/complete",
  "coverImageUrl": "https://cdn.example.com/ciocu-pro.webp",
  "priceUsdc": "20",
  "pricingModel": "recurring",
  "billingInterval": {
    "unit": "month",
    "count": 1
  }
}

POST/payment-intents

Create a payment intent

Creates one resumable checkout for an active one-time product. Your customer reference and metadata are returned in webhook events.

Parameter	Type	Description
`productId`Required	string	Active one-time product ID.
`customer.email`Required	email	Receipt and entitlement identity.
`customer.reference`	string	Your stable customer or account ID. Maximum 255 characters.
`metadata`	object	Your reconciliation data. Maximum 2 KB.

Request

curl https://rendben.com/api/v1/payment-intents \
  -X POST \
  -H "Authorization: Bearer $RENDBEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_8f2b7f46" \
  -d '{
  "productId": "prod_ciocu_basic_2026",
    "customer": { "email": "buyer@example.com", "reference": "customer_48391" },
    "metadata": { "orderId": "order_8f2b7f46" }
  }'

Response

{
  "paymentIntent": {
    "id": "pi_example",
    "status": "pending",
    "productId": "prod_ciocu_basic_2026",
    "customerReference": "customer_48391",
    "amountUsdc": "5",
    "merchantAmountUsdc": "4.795",
    "feeAmountUsdc": "0.205",
    "checkoutUrl": "https://yourstore.rendben.com/checkout/prod_ciocu_basic_2026?payment=pi_example",
    "agentPayment": {
      "intentId": "pi_example",
      "payerAccessToken": "rpa_v1_short_lived_capability",
      "mcpUrl": "https://rendben.com/mcp"
    }
  }
}

GET/payment-intents/:id

Retrieve a payment intent

Returns the current status, buyer wallet, Solana signature and confirmation timestamps. The API key must belong to the same workspace.

POST/refunds

Create a full or partial refund

Creates a refund linked to a confirmed payment. The merchant settlement wallet must approve the returned Solana Pay transaction. The original Rendben fee is not reversed and Rendben adds no refund fee.

Parameter	Type	Description
`paymentId`Required	string	Confirmed payment intent ID from the same workspace.
`amountUsdc`	string	Exact refund amount. Use either this or percentage.
`percentage`	string	Percentage of the original gross payment, from 0.01 to 100. Use either this or amountUsdc.

Send a unique Idempotency-Key. Multiple partial refunds are allowed, but their confirmed and pending total can never exceed the original payment.

Request

curl https://rendben.com/api/v1/refunds \
  -X POST \
  -H "Authorization: Bearer $RENDBEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund_order_8f2b7f46" \
  -d '{
    "paymentId": "pi_example",
    "percentage": "50"
  }'

GET/refunds/:id

Retrieve a refund

Returns pending, processing, confirmed, expired, failed or cancelled status plus the destination wallet, Solana signature and confirmation timestamps.

POST/subscription-checkouts

Create a bound subscription checkout

Creates an opaque, resumable checkout for an active recurring product. Rendben binds the receipt email and your stable customer reference on the server, so the customer cannot change the entitlement identity at checkout.

Parameter	Type	Description
`productId`Required	string	Active recurring product ID.
`customer.email`Required	email	Receipt and billing email. Stored server-side and not editable at checkout.
`customer.reference`Required	string	Your stable user or account ID. Use this for entitlement verification. Maximum 255 characters.

Request

curl https://rendben.com/api/v1/subscription-checkouts \
  -X POST \
  -H "Authorization: Bearer $RENDBEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: subscription_google-user-48391" \
  -d '{
    "productId": "prod_ciocu_basic_2026",
    "customer": {
      "email": "buyer@example.com",
      "reference": "google-user-48391"
    }
  }'

Response

{
  "subscriptionCheckout": {
    "id": "sub_example",
    "status": "authorization_pending",
    "productId": "prod_ciocu_basic_2026",
    "customerReference": "google-user-48391",
    "amountUsdc": "20",
    "periodHours": 720,
    "expiresAt": "2026-08-13T13:00:00.000Z",
    "checkoutUrl": "https://yourstore.rendben.com/checkout/prod_ciocu_basic_2026?subscription=sub_example"
  }
}

Create this URL on your backend.

Do not put the Rendben API key in Ciocu's browser code. Redirect the signed-in customer to the returned checkoutUrl, and do not append ?email=. The opaque URL already carries the server-bound identity.

GET/subscriptions

List and verify subscriptions

Omit customer filters to list the workspace's subscriptions and read total, lifecycle and MRR summary figures. For application entitlements, filter by your stable customer reference and product ID.

Parameter	Type	Description
`customer_reference`	string	Optional exact merchant customer ID. Recommended for entitlement checks.
`customer_email`	email	Optional exact receipt email filter. Prefer customer_reference for application identity.
`product_id`	string	Optional product filter. Recommended for entitlement checks.
`status`	enum	Filter returned records by lifecycle status. Defaults to all.
`page`	integer	Page number. Defaults to 1.
`limit`	integer	Records per page, from 1 to 100. Defaults to 50.

Response

{
  "customerEmail": "buyer@example.com",
  "customerReference": "google-user-48391",
  "productId": "prod_ciocu_basic_2026",
  "status": "all",
  "hasActiveSubscription": true,
  "summary": {
    "total": 12,
    "active": 8,
    "pastDue": 1,
    "cancelPending": 1,
    "cancelled": 2,
    "entitled": 9,
    "mrrUsdc": "160"
  },
  "hasMore": false,
  "page": 1,
  "pageSize": 50,
  "subscriptions": [
    {
      "id": "sub_example",
      "productId": "prod_ciocu_basic_2026",
      "productName": "Ciocu Pro",
      "status": "active",
      "entitled": true,
      "amountUsdc": "20",
      "periodHours": 720,
      "currentPeriodEnd": "2026-08-31T12:00:00.000Z",
      "nextChargeAt": "2026-08-31T12:00:00.000Z"
    }
  ]
}

Use the right response for the job.

Use summary.active and summary.mrrUsdc for merchant reporting. Use hasActiveSubscription to gate customer access.

POST/subscriptions/:id/cancel

Cancel future renewals

Lets your backend offer cancellation inside your own SaaS account page. It stops future collection immediately while preserving the customer's entitlement through the already-paid currentPeriodEnd.

Parameter	Type	Description
`customer_reference`	string	Recommended stable customer ID. Either this or customer_email is required and must match exactly.
`customer_email`	email	Exact normalized billing email. Either this or customer_reference is required and must match exactly.

Request

curl https://rendben.com/api/v1/subscriptions/sub_example/cancel \
  -X POST \
  -H "Authorization: Bearer $RENDBEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel_sub_example_1" \
  -d '{
    "customer_reference": "google-user-48391"
  }'

Response

{
  "subscription": {
    "id": "sub_example",
    "productId": "prod_ciocu_basic_2026",
    "customerEmail": "buyer@example.com",
    "status": "cancelled",
    "currentPeriodEnd": "2026-08-31T12:00:00.000Z",
    "nextChargeAt": null
  }
}

Call this only from your backend.

Use a read-write key and derive the customer identity from your authenticated session. Never accept an unchecked email or customer reference from browser input, and never expose the API key to the browser.

The operation emits subscription.cancelled, sends the customer cancellation email and is safely replayable for 24 hours with the same Idempotency-Key. It does not revoke the customer's on-chain token approval; the subscriber can do that separately from the Rendben management link.

GET/orders

Verify a one-time order

Returns payment intents for a customer. The default status=paid filter includes confirmed payments only.

Parameter	Type	Description
`customer_reference`	string	Exact merchant customer ID. Either this or customer_email is required.
`customer_email`	email	Exact receipt email. Either this or customer_reference is required.
`product_id`	string	Optional product filter for a top-up or purchase.
`status`	enum	paid, pending, processing, expired, failed or all. Defaults to paid.
`page`	integer	Page number. Defaults to 1.
`limit`	integer	Records per page, from 1 to 100. Defaults to 50.

Response

{
  "customerEmail": "buyer@example.com",
  "productId": "prod_topup",
  "status": "paid",
  "hasPaidOrder": true,
  "hasMore": false,
  "orders": [
    {
      "id": "pi_example",
      "productId": "prod_topup",
      "productName": "Five voice credits",
      "status": "paid",
      "amountUsdc": "5",
      "merchantAmountUsdc": "4.795",
      "feeAmountUsdc": "0.205",
      "transactionSignature": "solana_signature",
      "confirmedAt": "2026-08-10T10:00:02.000Z"
    }
  ]
}

ENTITLEMENT RULES

Grant access from paid facts.

1
Recurring access
Grant access only when hasActiveSubscription is true for the required product.
2
Credits and top-ups
Query orders with status=paid, then store every consumed order ID so it cannot be credited twice.
3
Cancelled subscriptions
Respect entitled until currentPeriodEnd. The customer keeps what they already paid for.
4
Plan changes
Upgrades become entitled after the atomic prorated payment confirms. Downgrades remain on the current tier through the paid period and change at renewal.
5
Failure behavior
Do not grant new access when the API cannot be reached. Keep your last verified state for a short, deliberate grace period if your product requires continuity.
6
Identity binding
Use your immutable user ID as customer.reference. Email is for receipts and can change; it must not be the primary entitlement key.

SIGNED EVENTS

React when the ledger changes.

Add an HTTPS endpoint in Dashboard → Webhooks. Rendben signs the exact JSON body with the secret shown once at creation. Verify Rendben-Signature before parsing the event, reject timestamps older than five minutes, and deduplicate with the top-level event id. Every envelope includes schemaVersion: 1; reject unsupported versions and ignore unknown fields within a supported version.

PAYMENTS

Confirmation events

payment.confirmed and payment.finalized.

SUBSCRIPTIONS

Lifecycle events

subscription.activated, renewed, failed, cancelled, change_requested, change_authorized, upgraded, downgraded, changed and change_failed.

REFUNDS

Refund events

refund.confirmed, refund.finalized and refund.failed.

Node.js signature verification

import { createHmac, timingSafeEqual } from "node:crypto";

const [timestampPart, signaturePart] = signatureHeader.split(",");
const timestamp = timestampPart.replace("t=", "");
const received = signaturePart.replace("v1=", "");
const expected = createHmac("sha256", process.env.RENDBEN_WEBHOOK_SECRET)
  .update(timestamp + "." + rawRequestBody)
  .digest("hex");

const valid = received.length === expected.length &&
  timingSafeEqual(Buffer.from(received), Buffer.from(expected));

Return any 2xx response within 8 seconds. Failed deliveries retry with increasing delays for up to 48 hours. The dashboard preserves every attempt and lets an owner or admin replay a delivery manually.

PAGINATION

Read complete histories safely.

Subscription and order responses include page, pageSize and hasMore. Increase page until hasMore is false. Customer responses are always private and are never cached.

ERRORS

One predictable error shape.

JSON

{ "error": "customer_email or customer_reference is required." }

Read limits are shared across all V1 read endpoints for the same credential. Writes use a separate, lower ceiling of 30 requests per minute. Additional per-IP ceilings prevent rotating invalid credentials from bypassing protection. A limited response includes RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After headers.

Workspace quotas protect retained resources: 100 active products, 10 active API keys and 10 active webhook endpoints. A full quota returns 409; deactivate or revoke an unused resource before retrying.

400Missing or invalid input

401Missing, invalid or revoked key

404Subscription or customer identity does not match

413Request body is too large

415Write request is not JSON

429Rate limit exceeded

409Idempotency conflict, request in progress or workspace quota reached

500Rendben could not complete the request

READY TO CONNECT?

Create a scoped key for your backend.

Start with read-only permission. Use read and write when your application creates products, payment intents or subscription checkouts.

Open API keys

Payment truth for your application.

Give your coding assistant the right context.

Let an agent pay without sharing its wallet secret.

Resolve the public checkout

Set a hard ceiling

The secret never leaves

Read payment status

Verify access in one request.

One workspace. Two permission levels.

Verify and reconcile

Configure and sell

Retry without creating duplicates.

Thirteen focused endpoints.

Read workspace setup status

Read storefront settings

Configure the storefront

List products

Create a product

Create a payment intent

Retrieve a payment intent

Create a full or partial refund

Retrieve a refund

Create a bound subscription checkout

List and verify subscriptions

Cancel future renewals

Verify a one-time order

Grant access from paid facts.

React when the ledger changes.

Confirmation events

Lifecycle events

Refund events

Read complete histories safely.

One predictable error shape.

Create a scoped key for your backend.