Ra Pay is AI CLI-Native Payment Infrastructure. It's the first company to use CLI as the distribution layer for AI-native payments, enabling payments to over 1 billion computers with one command.

How do I install Ra Pay?

Install Ra Pay with one command: npm install -g @rapay/cli. It works on macOS, Linux, and Windows.

Why use CLI for AI payments?

CLI is what AI was waiting for. It provides structured JSON data (not HTML), instant execution, no browser overhead, 40x token efficiency, and universal access across all platforms. Ra Pay is the first to use CLI as the AI payments distribution layer.

Yes. Stripe-powered security. No cookies, no fingerprinting. Your payment data stays private.

Is Ra Pay independent from big tech?

Yes. Ra Pay is not owned by OpenAI, Google, Anthropic, or any AI provider. We're the Switzerland of AI payments - independent infrastructure that works with any AI agent or provider.

MARKETPLACE API

The CLI AI Agent Payment Primitive

Add AI agent payments to your platform with Stripe security. Seller onboarding, direct charges, and fee splitting through four API endpoints so you can focus on your product.

Request API Access

Overview

Ra Pay is the CLI AI agent payment primitive built on Stripe. Add AI agent payments to your marketplace with seller onboarding, direct charges, and automatic fee splitting through four endpoints.

How It Works

1.Onboard sellers — Create Stripe Connect Express accounts for your sellers via API

2.Validate sellers — Resolve seller session tokens to Stripe account IDs

3.Seller dashboard — Give sellers access to their Stripe Express Dashboard to view payouts and balances

4.Create checkouts — Process payments with direct charges on the seller's connected account

5.Automatic fee splitting — Stripe collects fees and distributes your platform's share to your connected account automatically

Authentication

All API requests require a marketplace partner API key. Include your key as a Bearer token in the Authorization header.

Request Header

Authorization: Bearer rpmp_your_api_key_here

API keys use the rpmp_ prefix followed by 48 hex characters. Keys are hashed before storage and verified using timing-safe comparison. Keep your API key secure — treat it like a password.

Base URL

https://api.rapay.ai

All endpoint paths below are relative to this base URL.

Endpoints

POST/api/v1/marketplace/onboard-seller

Create a Stripe Connect Express account for a seller and return the onboarding URL. If the seller already exists (via stripeAccountId), generate a new onboarding link.

Request Body

{
  "returnUrl": "https://yoursite.com/onboard/complete",
  "refreshUrl": "https://yoursite.com/onboard/refresh",
  "idempotencyKey": "user_abc123",      // Required for new sellers
  "stripeAccountId": "acct_..."         // Optional — re-onboard existing seller
}

Response (200 OK)

{
  "success": true,
  "onboardingUrl": "https://connect.stripe.com/setup/...",
  "stripeAccountId": "acct_1a2b3c4d5e"
}

Notes

•idempotencyKey is required when creating a new seller (prevents duplicate Stripe accounts). Optional when re-onboarding an existing seller via stripeAccountId.
•If a seller was already created with the same idempotencyKey, the existing seller is returned with a fresh onboarding URL.
•If stripeAccountId is provided, verifies the seller belongs to your partner account before generating a new onboarding link.
•New sellers are created as Stripe Connect Express accounts with card_payments, transfers, and ACH capabilities.

POST/api/v1/marketplace/validate-seller

Resolve a seller's Ra Pay session token to their Stripe account ID and capabilities.

Request Body

{
  "token": "a1b2c3d4...64_hex_characters"
}

Response (200 OK)

{
  "success": true,
  "valid": true,
  "stripeAccountId": "acct_1a2b3c4d5e",
  "canReceive": true,
  "canSend": false
}

Notes

•Sellers share their session token with your platform (e.g., via the ra show-token CLI command).
•Token format: 64 lowercase hex characters.
•Returns valid: false if the token is expired, revoked, or the account is inactive.

POST/api/v1/marketplace/seller-dashboard-link

Generate a single-use Stripe Express Dashboard login link for a seller. Sellers use this to view their payouts, balances, and tax documents.

Request Body

{
  "stripeAccountId": "acct_1a2b3c4d5e"
}

Response (200 OK)

{
  "success": true,
  "url": "https://connect.stripe.com/express/..."
}

Notes

•The seller must belong to your partner account.
•Links are single-use and expire automatically — generate a new one each time the seller needs access.
•The seller must have completed Stripe onboarding before a dashboard link can be generated.

POST/api/v1/payments/checkout

Create a Stripe Checkout Session with a direct charge on the seller's connected account. The buyer pays on the seller's account, and fees are split automatically.

Request Body

{
  "amountCents": 10000,
  "destinationAccountId": "acct_1a2b3c4d5e",
  "applicationFeeCents": 1200,
  "successUrl": "https://yoursite.com/payment/success",
  "cancelUrl": "https://yoursite.com/payment/cancel",
  "idempotencyKey": "order_xyz789",     // Optional
  "metadata": {                          // Optional — up to 20 keys
    "order_id": "ORD-123",
    "customer_email": "[email protected]"
  }
}

Response (200 OK)

{
  "success": true,
  "checkoutUrl": "https://checkout.stripe.com/c/pay/...",
  "sessionId": "cs_live_..."
}

Notes

•amountCents: minimum 100 ($1.00 USD).
•applicationFeeCents: total platform fee in cents. Must be at least 2% of amountCents (Ra Pay's minimum platform fee). Set higher to add your own platform fee on top — the surplus over 2% auto-transfers to your connected Stripe account. Requests below 2% are rejected with INSUFFICIENT_FEE.
•Metadata keys cannot start with rapay_ (reserved) or contain [ or ]. Max 20 keys, 40-char key names, 500-char values.
•If idempotencyKey is provided and a checkout already exists with that key, the existing checkout URL is returned.

Pricing

Ra Pay charges a 2% platform fee on each transaction, deducted from the application fee captured at checkout.

You set applicationFeeCents on each checkout. The minimum is 2% of amountCents (Ra Pay's fee). Anything above 2% is your platform fee, which auto-transfers to your connected Stripe account after the buyer pays.

Example on a $100 charge: set applicationFeeCents: 1200 → Stripe collects ~$3.20 processing on the seller's account, $12 application fee on Ra Pay's platform, then $10 transfers to you and $2 stays with Ra Pay. Seller nets ~$84.80.

Volume pricing for high-volume partners is available —contact us for details.

Error Codes

All errors return a consistent JSON format:

{
  "success": false,
  "error": {
    "message": "Human-readable error description",
    "code": "ERROR_CODE"
  }
}

HTTP	Code	Description
400	VALIDATION_ERROR	Invalid request parameters
400	INSUFFICIENT_FEE	Application fee is below the required minimum
400	INVALID_APPLICATION_FEE	Application fee exceeds the payment amount
401	UNAUTHORIZED	Missing, malformed, invalid, or inactive API key
401	API_KEY_EXPIRED	API key has expired — contact Ra Pay to rotate it
403	ACCOUNT_INACTIVE	Seller's account is suspended or inactive
403	CHARGES_NOT_ENABLED	Seller hasn't completed Stripe onboarding
404	SELLER_NOT_FOUND	Seller or destination account not found for your partner account
409	IDEMPOTENCY_MISMATCH	Idempotency key reused with different parameters
429	MARKETPLACE_*_RATE_LIMIT_EXCEEDED	Too many requests — endpoint-specific code (e.g. MARKETPLACE_CHECKOUT_RATE_LIMIT_EXCEEDED). See rate limits below.
500	INTERNAL_ERROR	Server error — safe to retry

Rate Limits

Rate limits are applied per partner API key using sliding windows. Idempotent retries (same idempotency key) do not count against rate limits.

Endpoint	Limit	Window
onboard-seller	10 requests	per hour
validate-seller	100 requests	per hour
seller-dashboard-link	30 requests	per hour
checkout	100 requests	per hour
checkout (per seller)	50 requests	per hour

Webhooks

Ra Pay delivers webhook events to your registered endpoint when payment events occur. Webhooks are signed with your webhook secret using HMAC-SHA256.

Signature Verification

Each webhook includes a X-RaPay-Signature header with the format:

t=1712534400,v1=5257a869...

To verify: compute HMAC-SHA256(webhook_secret, timestamp.body) where timestamp is the t value and body is the raw request body. Compare the result to the v1 value.

Event Types

Event	Trigger	Idempotency Key
checkout.completed	Buyer completes payment on a Ra Pay checkout	(checkoutId, eventType)
seller.account.updated	Stripe Connect status change on a seller you onboarded (KYC, charges enabled, suspension)	(partnerId, stripeEventId)

Events are idempotent on the keys above — deduplicate on these to safely handle redeliveries.

Sample Payload — checkout.completed

{
  "event": "checkout.completed",
  "checkoutId": "chk_1a2b3c",
  "stripeSessionId": "cs_live_...",
  "stripePaymentIntentId": "pi_3T...",
  "stripeTransferId": "tr_1T...",
  "amountCents": 10000,
  "destinationAccountId": "acct_1a2b3c4d5e",
  "partnerFeeCents": 1000,
  "metadata": {
    "order_id": "ORD-123"
  }
}

Verifying the Signature (Node.js)

import crypto from 'crypto';

function verifyRaPaySignature(rawBody, signatureHeader, webhookSecret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('='))
  );
  const timestamp = parts.t;
  const signature = parts.v1;

  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Always use timingSafeEqual, not string comparison, to prevent timing attacks. The rawBody must be the unparsed request body bytes — JSON re-serialization will break the signature.

Delivery Policy

✓Persistent delivery with exponential backoff: up to 5 attempts, retried after 30s, 2min, 10min, 30min. After the 5th attempt fails, the delivery is terminally marked FAILED and surfaced for manual replay.
✓HTTPS-only delivery with DNS pinning (SSRF protection — private/loopback addresses rejected).
✓Webhook secret is required during partner onboarding. Unsigned events are not delivered — partners without a configured secret will not receive webhooks.
✓Partner platform fees auto-transfer to your connected Stripe account on checkout.completed — no pull required. The transfer ID appears in stripeTransferId.

Ready to Integrate?

Email us to request API access. Include the following details and we'll provision your API key and webhook secret within 24 hours.

Required Information

•Business: Company name and entity type

•Contact: Name and email of the technical lead

•Use case: What you're building and how you'll use the API

•Website: Your company or product URL

•Volume: Expected monthly transaction count and average payment size

•Webhook URL: HTTPS endpoint for payment event delivery

•Environment: Production or testing (use Stripe test cards for integration testing)

•Timeline: Expected integration timeline

Request API Access