Payment Requests

Payment requests are long-lived invoices where the XMR exchange rate is calculated when the customer visits the pay link, not when the request is created. This makes them ideal for invoices that may be paid hours or days later.

How They Differ from Charges

Use Cases

• Freelancer invoices: Send a pay link that stays valid until the client pays
• Recurring services: Reusable link for monthly payments at current rates
• Donations: A permanent link with no expiration

Pay Link

Each payment request has a public pay link:

/pay/request/:id

When a customer visits this link, a charge is created at the current XMR rate. The customer then pays the charge as usual.

Single-Use vs Reusable

• Single-use (single_use: true): Automatically deactivated after the first successful payment.
• Reusable (default): Can be paid multiple times. Each visit creates a new charge at the current rate.

Expiration

Set expires_at (ISO 8601) to make a payment request expire at a specific date. After expiration, the pay link returns an error. If omitted, the request stays active indefinitely (until manually deactivated).

API Endpoints

Create Payment Request

POST /api/payment-requests

Requires API key authentication.

Request Body:

{
  "amount": 50.00,              // Required: amount in currency
  "currency": "USD",            // Optional: USD, EUR, GBP (default: USD)
  "description": "Web design",  // Optional: shown on pay page
  "reference": "INV-2026-042",  // Optional: your internal reference
  "single_use": false,          // Optional: deactivate after first payment
  "expires_at": "2026-03-15T00:00:00Z"  // Optional: expiration date
}

Response:

{
  "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "amount": 50.00,
  "currency": "USD",
  "description": "Web design",
  "reference": "INV-2026-042",
  "single_use": false,
  "active": true,
  "pay_url": "/pay/request/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "expires_at": "2026-03-15T00:00:00.000Z",
  "created_at": "2026-02-15T12:00:00.000Z"
}

Example:

curl -X POST https://your-server.com/api/payment-requests \
  -H "Content-Type: application/json" \
  -H "x-api-key: rp_live_abc123" \
  -d '{
    "amount": 50.00,
    "currency": "USD",
    "description": "Web design invoice",
    "single_use": true
  }'

List Payment Requests

GET /api/payment-requests

Requires API key authentication. Returns all payment requests for your account.

Get Public Payment Request

GET /api/payment-requests/:id/public

Public endpoint — no authentication required. Rate-limited. Returns the payment request details needed to display the pay page.

Toggle Active/Inactive

POST /api/payment-requests/:id/toggle

Requires API key authentication. Toggles the payment request between active and inactive. Inactive requests return an error when customers visit the pay link.

Example:

curl -X POST https://your-server.com/api/payment-requests/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/toggle \
  -H "x-api-key: rp_live_abc123"