Authentication

Send Pay Links uses JWT (JSON Web Tokens) for API authentication. Tokens are used to create secure, tamper-proof checkout sessions.

Creating a Checkout Token

To create a checkout, you need to generate a signed JWT token containing the checkout data.

Token Payload

interface CheckoutToken {
  // Required fields
  orderId: string;           // Your unique order ID
  amount: number;            // Amount in cents (e.g., 9999 = $99.99)
  currency: string;          // ISO 4217 currency code (e.g., "USD")

  // Product information
  productName: string;       // Product name to display
  productDescription?: string;
  productImage?: string;     // URL to product image

  // Customer information (optional, pre-fills form)
  customer?: {
    email?: string;
    firstName?: string;
    lastName?: string;
    phone?: string;
  };

  // Shipping address (optional)
  shippingAddress?: {
    address1: string;
    address2?: string;
    city: string;
    state: string;
    postalCode: string;
    country: string;
  };

  // Configuration
  provider?: string;         // Payment provider ID
  brandId?: string;          // Brand ID for styling

  // Callbacks
  successUrl?: string;       // Redirect after success
  cancelUrl?: string;        // Redirect on cancel
  webhookUrl?: string;       // Custom webhook URL

  // Metadata
  metadata?: Record<string, string>;

  // Token expiration
  exp: number;               // Unix timestamp
  iat: number;               // Issued at timestamp
}

Generating a Token

Use your secret key to sign the token:

import { SignJWT } from 'jose';

const secret = new TextEncoder().encode(process.env.CHECKOUT_TOKEN_SECRET);

const token = await new SignJWT({
  orderId: 'order_123',
  amount: 9999,
  currency: 'USD',
  productName: 'Premium Plan',
  customer: {
    email: 'customer@example.com',
  },
})
  .setProtectedHeader({ alg: 'HS256' })
  .setIssuedAt()
  .setExpirationTime('1h')
  .sign(secret);

// Use the token in your checkout URL
const checkoutUrl = `https://sendpaylinks.com/checkout/${token}`;

Token Security

Never expose your CHECKOUT_TOKEN_SECRET in client-side code. Always generate tokens on your server.

Best practices:

Set short expiration times (1 hour or less)
Generate unique tokens for each checkout
Validate tokens server-side before processing
Use HTTPS for all requests

Verifying Tokens

Tokens are automatically verified when a checkout is accessed. You can also verify tokens manually:

import { jwtVerify } from 'jose';

const secret = new TextEncoder().encode(process.env.CHECKOUT_TOKEN_SECRET);

try {
  const { payload } = await jwtVerify(token, secret);
  console.log('Token is valid:', payload);
} catch (error) {
  console.error('Token is invalid or expired');
}

API Key Authentication

For server-to-server API calls (coming soon), you'll use API keys:

curl -X POST https://api.sendpaylinks.com/v1/checkouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9999, "currency": "USD"}'

Environment Variables

# Required for token signing
CHECKOUT_TOKEN_SECRET=your-secret-key-min-32-chars

# API keys (coming soon)
API_KEY=your-api-key

Your CHECKOUT_TOKEN_SECRET should be at least 32 characters long and kept secure. Never commit it to version control.

Authentication

On this page