Merchant API

Summary

The RapidCents Merchant API v1 is a server-to-server REST API for managing customers, products, prices, subscriptions, refunds, and voids. Authenticate with a secret API key (rc_sk_…). The business is resolved from the key and is never accepted from the request body.

Integration Flow

Typical recurring billing flow with the Merchant API:

1. Create a customer — POST /api/v1/customers with name and/or email.
2. Create product & recurring price — Catalog items first; amounts live on prices (cents).
3. Create a subscription — Pass customer, recurring price, and optionally a stored payment_method.
4. Collect payment method if needed — Without a stored card, RapidCents returns a hosted checkout_url.
5. Reconcile via webhooks & payments API — Listen for subscription/payment events; list payments under the subscription.

API Key Authentication

All Merchant API endpoints require a secret API key in the Authorization header. Keys are created in the RapidCents dashboard and start with rc_sk_.

Required Headers

Authorization: Bearer rc_sk_…
Content-Type: application/json
Accept: application/json

Base URL Pattern

All Merchant API endpoints are under /api/v1/…. Business scope comes from the key — do not send business_id in the body.

Smoke Test

GET /api/v1/account

{
  "data": {
    "object": "account",
    "business_id": "biz-uuid",
    "business_name": "Acme Store",
    "api_key_id": "key-uuid",
    "api_key_name": "Production",
    "api_key_last_four": "a1b2"
  }
}

IP Whitelisting

Configure allowed_ips when creating or rotating keys in the dashboard (1–2 IPs per key). Staging and production keys have separate allowlists.

Rate Limits

Limits are enforced per API key / business. Exceeding a limit returns 429 with rate_limit_error.

Account

GET /api/v1/account

Returns safe identifiers for the authenticated key and its business. Use this to verify credentials after onboarding.

Customers

Create a Customer

POST /api/v1/customers

POST /api/v1/customers
Authorization: Bearer rc_sk_…
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "[email protected]",
  "phone": "+1-555-0100",
  "metadata": { "crm_id": "123" }
}

Request Fields

{
  "id": "cust-uuid",
  "object": "customer",
  "name": "Jane Doe",
  "email": "[email protected]",
  "phone": "+1-555-0100",
  "metadata": { "crm_id": "123" },
  "created": 1710000000
}

List / Show / Update

Payment Methods

Read and delete stored cards. Raw card create is not supported on Merchant API v1.

{
  "id": "pm-uuid",
  "object": "payment_method",
  "type": "card",
  "customer": "cust-uuid",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2030
  },
  "status": "active",
  "created": 1710000000
}

Products

POST /api/v1/products

{
  "name": "Pro Plan",
  "description": "Monthly subscription",
  "active": true,
  "metadata": {}
}

Also: GET /products, GET /products/{id}, PATCH /products/{id}. List filter: ?active=true|false.

Prices

POST /api/v1/prices

{
  "product": "prod-uuid",
  "unit_amount": 2999,
  "recurring": {
    "interval": "month",
    "interval_count": 1
  },
  "nickname": "Pro Monthly",
  "active": true
}

Supported cadences

day:1, week:1, week:2, month:1, month:3, month:6, year:1

Subscriptions

POST /api/v1/subscriptions

{
  "customer": "cust-uuid",
  "price": "price-uuid",
  "payment_method": "pm-uuid",
  "start_date": "2026-08-01",
  "tax_rate": 13,
  "surcharge_rate": 2.4
}

Request Fields

Create behavior

• With payment_method — Attempts first charge. Decline deletes the subscription and returns 402.
• Without payment_method — Creates inactive subscription + hosted link; optionally emails the customer.
• Emits webhook subscription.created.

Cancel

DELETE /api/v1/subscriptions/{id}

Deactivates the subscription, clears next billing, unfulfills pending queue rows, and emits subscription.cancelled.

List filters

?customer= and ?status=active|canceled|pending_payment_method (aliases: cancelled, incomplete).

Subscription Payments

Read-only history of sales for a subscription.

{
  "id": "pay-uuid",
  "object": "payment",
  "subscription": "sub-uuid",
  "amount": 2999,
  "currency": "CAD",
  "status": "succeeded",
  "refunded_amount": 0,
  "created": 1710000000
}

Statuses: succeeded, failed, refunded, voided. Refund ledger rows are excluded; use refunded_amount on the original payment.

Refunds

POST /api/v1/refunds

{
  "payment": "pay-uuid",
  "amount": 1000
}

• Subscription payments only (not VT / payment-link)
• Webhooks: payment.refunded or payment.partially_refunded
• Customer email: refund notification
• Show: GET /api/v1/refunds/{id}

Voids

POST /api/v1/voids

{
  "payment": "pay-uuid"
}

Voids an open-batch subscription payment. Returns the updated payment object with status: "voided" and emits payment.voided.

All Endpoints

Account

Customers

Payment Methods

Products & Prices

Subscriptions & Payments

Refunds & Voids

Pagination

List endpoints return a Stripe-style list envelope with cursor pagination:

{
  "object": "list",
  "data": [ … ],
  "has_more": false
}

Order: created_at DESC, id tiebreaker.

Environment Configuration

Error Handling

Errors use a consistent envelope (not the dashboard { ok, status } shape):

{
  "error": {
    "type": "validation_error",
    "code": "parameter_invalid",
    "message": "The email must be a valid email address.",
    "param": "email"
  }
}

Security Best Practices

• Secret keys stay on the server — Never expose rc_sk_ keys in frontend code or mobile apps.
• Use HTTPS exclusively — All API traffic must use TLS.
• Whitelist server IPs — Activate keys with allowlisted outbound IPs; update before infrastructure changes.
• Never send raw card data — Collect cards via hosted checkout; use stored payment method IDs only.
• Money in cents — Send integer minor units for amounts; tax/surcharge rates as human percentages.
• Verify webhooks — Treat webhook deliveries as the source of truth for payment state changes.
• Rotate compromised keys — Revoke and reissue from the dashboard immediately.

Integration Checklist

Authentication & Setup

• Secret API key created and stored in a secrets manager
• Server IP(s) allowlisted and key activated
• GET /api/v1/account succeeds from your server
• Staging and production keys stored separately

Catalog & Customers

• Products and recurring prices created with amounts in cents
• Customer create/update/list wired to your CRM
• Email conflict / firstOrCreate behavior understood

Subscriptions

• Create with stored payment_method path tested (including 402 declines)
• Create without PM returns checkout_url; hosted flow completes
• Cancel path tested; pending queue rows cleared
• Webhooks for subscription.created / subscription.cancelled handled

Refunds & Voids

• Full and partial refunds tested on subscription payments
• Void only used for open-batch payments
• payment.refunded / payment.voided webhooks handled