---
name: bijection-convex-oxapay
description: "Evaluate and integrate the OxaPay component with Bijection."
---

# OxaPay

Crypto payments for Convex. Invoices, wallets, and payouts in your Convex backend.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-oxapay
- Source: https://github.com/BradPerbs/convex-oxapay
- npm: https://www.npmjs.com/package/convex-oxapay
- Directory: https://bijection.com/components/convex-oxapay

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-oxapay. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# OxaPay

## Instructions

Use OxaPay to add crypto payment processing to convex apps with bitcoin, ethereum, usdt support, hosted invoices, and real-time status updates. This Convex component integrates directly with your backend.

### Installation

```bash
npm install convex-oxapay
```

### Capabilities

- Process crypto payments with one API call and automatic status mirroring in your Convex database
- Build custom checkout flows with white-label payments or use hosted invoice pages
- Track payment status in real-time with live React components and webhook handling
- Accept 30+ cryptocurrencies including Bitcoin, Ethereum, USDT, and USDC across multiple networks

## Examples

### how to accept bitcoin payments in Convex app

The convex-oxapay component provides createInvoice() and createWhiteLabel() functions that generate crypto payment addresses for Bitcoin and 30+ other cryptocurrencies. Payment status automatically syncs to your Convex database via webhooks, so you can query the latest status with useQuery() without API calls.

### crypto payment gateway with real-time status updates

OxaPay component mirrors all payment data to Convex tables and handles webhook verification automatically. Your React components get instant status updates through Convex's live queries whenever payments transition from waiting to paid or expired.

### accept recurring crypto payments subscription

Use the staticAddresses API to generate permanent wallet addresses for each user. Customers can send crypto to these addresses repeatedly for subscriptions or wallet top-ups, with automatic detection and processing.

### send crypto payouts from Convex backend

The payouts API lets you send crypto payments to users with status tracking. All payout statuses are mirrored to your Convex database so you can build payout dashboards and handle confirmations through webhook events.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by OxaPay is not needed

## Troubleshooting

**What cryptocurrencies does the OxaPay component support?**

The convex-oxapay component supports Bitcoin, Ethereum, USDT, USDC, and dozens of other cryptocurrencies across multiple blockchain networks. It accepts both fiat-priced invoices (USD, EUR) and crypto-native amounts.

**How does webhook verification work with OxaPay?**

The convex-oxapay component automatically handles HMAC-SHA512 webhook verification using your API key as the secret. It performs idempotent deduplication and only processes forward status transitions, so duplicate or out-of-order webhooks are safely ignored.

**Can I build custom checkout UI instead of hosted pages?**

Yes, the convex-oxapay component provides createWhiteLabel() for fully custom checkout experiences. This returns the crypto address, exact payment amount, and QR code data so you can build your own payment interface while still getting automatic status updates.

**How do I test payments before going live?**

The convex-oxapay component supports OxaPay's sandbox mode by setting OXAPAY_SANDBOX=true in your environment variables. This sends sandbox:true on all payment creation calls for testing without real cryptocurrency transactions.

**What Convex functions do I need to handle payments?**

The convex-oxapay component works through Convex actions for creating payments (since they call external APIs) and queries for reading payment status from the mirrored tables. Webhook handling runs automatically through HTTP routes you register in convex/http.ts.

## Resources

- [npm package](https://www.npmjs.com/package/convex-oxapay)
- [GitHub repository](https://github.com/BradPerbs/convex-oxapay)
- [Live demo](https://convex-oxapay.bradperbs-11a.workers.dev/)
- [Convex Components Directory](https://www.convex.dev/components/convex-oxapay)
- [Convex documentation](https://docs.convex.dev)