Skip to main content

​
Overview

The Royalti.io API provides comprehensive payment processing capabilities for managing royalty payments, subscription billing, and financial workflows. This guide covers integration patterns for Stripe-based payment processing.

​
Authentication

All payment endpoints require authentication with a Bearer token.

​
Payment Workflow

1

Configure Payment Settings

Set up payment thresholds, schedules, and Stripe integration.
Node.js
const response = await fetch('https://api.royalti.io/payment-settings/', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paymentThreshold: 50.00,
    paymentSchedule: 'monthly',
    currency: 'USD'
  })
});
2

Create Payment Requests

Generate payment requests for users with pending royalties.
Node.js
const response = await fetch('https://api.royalti.io/payment-requests/', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipientId: 'user-id',
    amount: 150.00,
    description: 'Q1 2024 Royalties'
  })
});
3

Process Payments

Execute batch payments through Stripe Connect.
Node.js
const response = await fetch('https://api.royalti.io/payments/process-batch', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paymentRequestIds: ['req-1', 'req-2', 'req-3']
  })
});
4

Handle Webhooks

Listen for payment status updates from Stripe.
Node.js
// Webhook endpoint example
app.post('/webhooks/stripe', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'payment_intent.succeeded':
      // Update payment status
      await updatePaymentStatus(event.data.object.id, 'completed');
      break;
    case 'payment_intent.payment_failed':
      // Handle failure
      await handlePaymentFailure(event.data.object.id);
      break;
  }

  res.json({ received: true });
});

​
Best Practices

​
Payment Security

Always validate webhook signatures to ensure requests come from Stripe.
Node.js
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

const signature = req.headers['stripe-signature'];
const event = stripe.webhooks.constructEvent(
  req.body,
  signature,
  process.env.STRIPE_WEBHOOK_SECRET
);

​
Error Handling

Implement retry logic for failed payments:
Node.js
async function processPaymentWithRetry(paymentId, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const result = await processPayment(paymentId);
      return result;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
}

​
Common Use Cases

​
Automated Monthly Payouts

Set up recurring payment processing:
Node.js
// Schedule monthly payout processing
cron.schedule('0 0 1 * *', async () => {
  const pendingPayments = await fetchPendingPayments();
  await processBatchPayments(pendingPayments);
});

​
Split Payments

Handle complex royalty splits:
Node.js
const response = await fetch('https://api.royalti.io/payments/split', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    totalAmount: 1000.00,
    splits: [
      { userId: 'user-1', percentage: 50 },
      { userId: 'user-2', percentage: 30 },
      { userId: 'user-3', percentage: 20 }
    ]
  })
});