API Reference

Integrate RydderPay into your application to accept cryptocurrency payments simply and securely. All endpoints use JSON and respond with consistent structures.

Base URLhttps://rydderpay.com/api/v1

Formatapplication/json

AuthenticationBearer Token

Quick Start

Get up and running with RydderPay in 4 simple steps:

Create your account

Configure your settings

In Dashboard → Settings , set your Solana wallet address, webhook URL, and generate your API Key.

Copy your keys

Save your API Key (rp_live_xxx) for authentication and your Webhook Signing Secret (whsec_xxx) for verifying webhook signatures.

Create your first payment

Make a POST request to /api/v1/payments/create from your backend with your API Key.

Authentication

All API requests require an API Key sent as an Authorization header. You can get your API key from the settings panel.

Header

Authorization: Bearer rp_live_xxxxxxxxxxxxxxxxxxxxxxx

⚠

Important: Never expose your API key in client-side code. Always make API calls from your backend server.

Create Payment

Create a new payment and get a link for your customer to complete the payment.

POST/api/v1/payments/create

Parameters

amountnumberrequired

Payment amount in the specified currency.

currencystringrequired

Payment currency. Values: SOL, USDC.

networkstringrequired

Blockchain network where the payment will be processed. Values: solana. Coming soon: ethereum, polygon, base.

descriptionstringoptional

Payment description visible to the customer.

metadataobjectoptional

Key-value pairs with custom data (e.g.: order_id).

redirect_urlstringoptional

URL to redirect the customer to after completing the payment.

webhook_urlstringoptional

URL that will receive the webhook when the payment status changes. If not specified, the webhook configured in settings will be used.

{
  "amount": 0.5,
  "currency": "SOL",
  "network": "solana",
  "description": "Purchase of product #123",
  "metadata": {
    "order_id": "ORD-123",
    "customer_email": "customer@email.com"
  },
  "redirect_url": "https://my-store.com/thanks",
  "webhook_url": "https://my-store.com/api/webhook"
}

Get Payment

Check the status and details of a specific payment.

GET/api/v1/payments/:id

{
  "success": true,
  "payment": {
    "id": "pay_abc123def456",
    "amount": 0.5,
    "currency": "SOL",
    "network": "solana",
    "status": "completed",
    "tx_signature": "5xH3zRxQm8vYkT2...",
    "fee_amount": 0.0075,
    "net_amount": 0.4925,
    "created_at": "2025-01-15T12:00:00Z",
    "confirmed_at": "2025-01-15T12:05:30Z"
  }
}

List Payments

Get a paginated list of all your payments with optional filters.

GET/api/v1/payments

Query Parameters

statusstringoptional

Filter by status: pending, completed, failed, expired.

currencystringoptional

Filter by currency: SOL, USDC.

pagenumberdefault: 1

Page number.

limitnumberdefault: 20

Results per page (maximum 100).

fromstringISO 8601

Start date of the range.

tostringISO 8601

End date of the range.

Response

{
  "success": true,
  "payments": [
    {
      "id": "pay_abc123",
      "amount": 0.5,
      "currency": "SOL",
      "network": "solana",
      "status": "completed",
      "created_at": "2025-01-15T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

Create Subscription Plan

Create a recurring payment plan. Once created, share the checkout_url with your customers so they can subscribe by connecting their Solana wallet.

POST/api/subscriptions/plans

🔑

Authentication: This endpoint requires a Firebase ID Token (from your dashboard session), not the API Key.

Parameters

namestringrequired

Name of the subscription plan (e.g. "Premium Monthly").

amountnumberrequired

Recurring charge amount in USDC.

currencystringrequired

Currently only USDC is supported for subscriptions.

intervalstringrequired

Billing interval: weekly, monthly, or yearly.

descriptionstringoptional

Description visible to subscribers on the checkout page.

metadataobjectoptional

Key-value pairs for your internal use (e.g. tier, features). Included in webhooks.

{
  "name": "Premium Monthly",
  "amount": 9.99,
  "currency": "USDC",
  "interval": "monthly",
  "description": "Access to all premium features",
  "metadata": {
    "tier": "premium",
    "features": ["api", "chat", "analytics"]
  }
}

💡

Tip: Share the checkout_url with your customers. Each user who opens the link can connect their wallet and subscribe individually. One plan, many subscribers — each identified by their unique wallet address.

Subscribe to a Plan

Register a new subscription after the user signs the on-chain transaction. This is called from the frontend checkout page after wallet confirmation.

POST/api/subscriptions/:planId/subscribe

Parameters

subscriber_walletstringrequired

The Solana wallet address of the subscriber.

tx_signaturestringrequired

The on-chain transaction signature from the subscribe instruction.

metadataobjectoptional

Custom data to associate with this subscription (e.g. user_id, email). Included in all webhooks.

{
  "subscriber_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "tx_signature": "5nRmB4eFpP9a9gUxb1z7N2vL3kX8qR1tW9yH4...",
  "metadata": {
    "user_id": "usr_12345",
    "email": "customer@example.com",
    "plan_tier": "premium"
  }
}

Cancel Subscription

Cancel an active subscription. The subscriber is identified by their wallet address. No authentication is required — this is a public endpoint.

POST/api/subscriptions/:planId/cancel

Parameters

subscriber_walletstringrequired

The wallet address of the subscriber to cancel.

{
  "subscriber_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
}

Webhooks

Webhooks notify you in real time when a payment or subscription status changes. Configure your webhook URL in Settings or send it in each payment creation request.

Payment Events

Event	Description
`payment.completed`	Payment confirmed and funds transferred to the merchant.
`payment.failed`	Payment failed (incorrect amount, transfer error).
`payment.expired`	Payment expired without receiving funds.

Subscription Events

Event	Description
`subscription.created`	A new subscriber has joined the plan.
`subscription.charged`	Recurring charge was processed successfully.
`subscription.charge_failed`	Recurring charge failed (insufficient funds). Subscription is auto-cancelled.
`subscription.cancelled`	Subscription was cancelled by the subscriber.

Payment Webhook Payload

POST — Your webhook URL

{
  "event": "payment.completed",
  "payment": {
    "id": "pay_abc123",
    "amount": 0.5,
    "currency": "SOL",
    "network": "solana",
    "status": "completed",
    "tx_signature": "5xH3zRxQm8vYkT2...",
    "net_amount": 0.4925,
    "metadata": {
      "order_id": "ORD-123"
    }
  },
  "timestamp": "2025-01-15T12:05:30Z"
}

Subscription Webhook Payload

POST — Your webhook URL

{
  "event": "subscription.created",
  "subscription": {
    "id": "sub_xyz789",
    "plan_id": "abc123def456",
    "plan_name": "Premium Monthly",
    "subscriber_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "merchant_wallet": "3mRk7VBsPn...",
    "amount": 9.99,
    "currency": "USDC",
    "interval": "monthly",
    "status": "active",
    "charges_count": 1,
    "total_charged": 9.99,
    "next_charge_at": "2025-03-15T10:00:00Z",
    "metadata": {
      "user_id": "usr_12345",
      "email": "customer@example.com"
    }
  },
  "timestamp": "2025-02-15T10:00:00Z"
}

Webhook Verification

Each webhook includes an X-RydderPay-Signature header with an HMAC-SHA256 signature. The signature is generated using your Webhook Signing Secret (whsec_xxx), which you can find in Dashboard → Settings under the Webhook section.

⚠

Important: The Webhook Signing Secret (whsec_xxx) is different from your API Key (rp_live_xxx). The API Key authenticates API requests. The Webhook Secret verifies incoming webhooks. Both payment and subscription webhooks use the same signing secret.

const crypto = require('crypto');

// Your Webhook Signing Secret from Dashboard → Settings
const WEBHOOK_SECRET = process.env.RYDDERPAY_WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-rydderpay-signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  if (signature === expected) {
    const { event } = req.body;

    // Handle both payment and subscription events
    if (event.startsWith('payment.')) {
      const { payment } = req.body;
      console.log(`Payment ${payment.id}: ${event}`);
    } else if (event.startsWith('subscription.')) {
      const { subscription } = req.body;
      console.log(`Subscription ${subscription.id}: ${event}`);
      console.log(`Wallet: ${subscription.subscriber_wallet}`);
    }

    res.status(200).send('OK');
  } else {
    res.status(401).send('Invalid signature');
  }
});

Error Codes

The API uses standard HTTP status codes. All errors include an error field with details.

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Amount must be greater than 0"
  }
}

HTTP	Code	Description
`400`	`INVALID_AMOUNT`	The amount is invalid or less than 0.
`400`	`INVALID_CURRENCY`	Currency not supported.
`400`	`MISSING_WALLET`	You don't have a destination wallet configured.
`400`	`INVALID_NAME`	Plan name is required.
`400`	`INVALID_INTERVAL`	Invalid interval. Options: weekly, monthly, yearly.
`400`	`INVALID_WALLET`	Subscriber wallet is required.
`400`	`ALREADY_SUBSCRIBED`	An active subscription already exists for this wallet and plan.
`401`	`UNAUTHORIZED`	Invalid or missing API key.
`403`	`EMAIL_NOT_VERIFIED`	You must verify your email before using the API.
`404`	`PAYMENT_NOT_FOUND`	The specified payment does not exist.
`404`	`PLAN_NOT_FOUND`	The specified subscription plan does not exist.
`404`	`SUBSCRIPTION_NOT_FOUND`	No active subscription found for this wallet.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests. Wait before retrying.
`500`	`INTERNAL_ERROR`	Internal server error.

Rate Limits

To ensure service stability, the API has request limits per API key.

Endpoint	Limit	Window
`POST /payments/create`	60 requests	per minute
`GET /payments`	100 requests	per minute
`GET /payments/:id`	100 requests	per minute

ℹ

When you exceed the limit, the API responds with 429 Too Many Requests. The Retry-After header indicates how many seconds to wait.

SDKs

We will soon offer official SDKs to facilitate integration.

Node.jsComing Soon

PythonComing Soon

PHPComing Soon

RubyComing Soon

Changelog

v1.1.0February 2025

Subscription plans: create, subscribe, cancel.
Subscription webhooks: subscription.created, subscription.charged, subscription.charge_failed, subscription.cancelled.
Metadata support for plans and subscriptions.
Automatic recurring charges via cron.

v1.0.0February 2025

Initial release of API v1.
Support for SOL and USDC payments (Solana).
Webhooks for payment events.
Webhook verification with HMAC-SHA256.