osuvox Hosted Checkout

osuvox Hosted Checkout gives you a complete payment page without building your own UI. You create a payment with success and cancel URLs, then redirect customers to the returned payment_url.

• Branded checkout - Use your logo and colors
• Redirect flow - Return customers after payment
• Webhooks - Receive payment confirmations
• Multi-currency - Accept BTC, LTC, and DOGE

Authenticate requests by including your API key in the Authorization header:

Authorization: Bearer sk_live_your_api_key

Hosted Checkout Notes

• Redirects are UX only: Fulfill orders from webhooks, not the success_url redirect.
• OSUVOX_WEBHOOK_URL: If set, use it as the default webhook URL unless explicitly overridden per payment.
• TXID guarantee: Fulfill using payment.confirmed or payment.completed because they always include txid.
• Reconciliation: GET /payments is for reconciliation only. Webhooks are the primary signal.
• Internal monitoring: Monitoring is internal; there is no public monitoring endpoint.

Create a payment with redirect URLs to enable the hosted checkout flow.

Required Parameters

Example Request

curl -X POST https://www.osuvox.net/api/v1/payments \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "0.001",
    "coin": "BTC",
    "external_id": "order_12345",
    "description": "Premium Plan - Monthly",
    "success_url": "https://yoursite.com/checkout/success",
    "cancel_url": "https://yoursite.com/checkout/cancel"
  }'

Redirect customers to the payment_url returned by the Payments API. After confirmation, customers return to your site using the success_url or cancel_url.

How It Works

1. Create a payment with success_url and/or cancel_url
2. Redirect the customer to payment_url
3. Customer pays on the hosted checkout page
4. Customer returns to your site via the configured URL

Redirect URL Parameters

We append the payment ID when redirecting to your success_url or cancel_url:

https://yoursite.com/checkout/success?payment_id=pay_abc123def456

Verify payment status server-side using the Get Payment API.

Branding Your Checkout

Customize the hosted checkout appearance in Dashboard - Settings.

• Brand Name - Displayed at the top of checkout
• Logo URL - Your company logo (HTTPS required)
• Brand Color - Accent color for buttons and highlights

Retrieve details for a specific payment.

curl https://www.osuvox.net/api/v1/payments/pay_abc123def456 \
  -H "Authorization: Bearer sk_live_xxx"

Webhooks notify your server when payment events occur. Configure your webhook URL in Dashboard - Settings.

{
  "id": "evt_abc123def456789",
  "type": "payment.confirmed",
  "created_at": "2026-01-11T22:15:00Z",
  "data": {
    "payment": {
      "id": "pay_abc123def456",
      "status": "confirmed",
      "coin": "BTC",
      "amount": "0.00100000",
      "amount_received": "0.00100000",
      "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "confirmations": 3,
      "confirmations_required": 3,
      "metadata": {
        "customer_id": "cust_abc"
      }
    }
  }
}

All webhooks include a timestamped HMAC-SHA256 signature in the X-Osuvox-Signature header. Verify using the raw request body before parsing JSON.

export const POST = async ({ request }) => {
  const payload = await request.text();
  const signature = request.headers.get('x-osuvox-signature');
  const secret = process.env.OSUVOX_WEBHOOK_SECRET;

  if (!verifySignature(payload, signature, secret)) {
    return new Response('Unauthorized', { status: 401 });
  }

  const event = JSON.parse(payload);
  return new Response('OK');
};

Error Response Format

{
  "error": {
    "code": "invalid_amount",
    "message": "Amount must be a positive number",
    "param": "amount"
  }
}

HTTP Status Codes

Authenticated endpoints are limited to 100 requests per minute per API key.

Copy these types into your TypeScript project:

export type OsuvoxCoin = 'BTC' | 'LTC' | 'DOGE';

export type PaymentStatus =
  | 'pending'
  | 'detecting'
  | 'confirming'
  | 'confirmed'
  | 'completed'
  | 'expired'
  | 'failed';