Getting Started

This guide will help you integrate x402 payment acceptance in approximately 5 minutes through a streamlined integration process.

What You Need

• Ability to make HTTP requests (standard API integration experience)

• A wallet address to receive payments (setup assistance available if needed)

• This completes the prerequisites.

What We're Doing

The integration process consists of three steps:

1. Obtain your API key (30 seconds)

2. Make one API call to verify payments

3. Complete integration and begin accepting x402 payments

Setup

Oura402 operates through simple HTTP endpoints with no SDK installation or complex dependencies required.

To use the provided examples, install the HTTP library for your preferred language:

JavaScript/TypeScript

npm install axios  # or use fetch
npm install ws     # for WebSocket support

Python

Rust

Get Your API Key

1. Navigate to oura402.dev

2. Create an account (requires only your email address)

3. Retrieve your API key from the dashboard

4. Secure your API key (do not expose it in frontend code or version control systems)

Accept Your First Payment

Use the following code examples to implement payment verification:

cURL

curl -X POST https://api.oura402.dev/v1/payments/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "payment_proof": "BASE64_ENCODED_PAYMENT_PROOF",
    "amount": 1000000,
    "recipient": "YOUR_WALLET_ADDRESS",
    "network": "solana"
  }'

JavaScript

Python

Payment Verification Complete

Your payment verification is now configured.

Real Example (Production Implementation)

The following example demonstrates how to implement payment verification in a production server environment:

// Your API server receives a 402 Payment Required request
app.get('/api/protected-resource', async (req, res) => {
  const paymentProof = req.headers['x-payment-proof'];

  if (!paymentProof) {
    // No payment provided, return 402
    return res.status(402).json({
      error: 'Payment Required',
      amount: 1000000,
      recipient: 'YOUR_WALLET_ADDRESS',
      network: 'solana'
    });
  }

  try {
    // Verify the payment with Oura402
    const verification = await fetch('https://api.oura402.dev/v1/payments/verify', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
      },
      body: JSON.stringify({
        payment_proof: paymentProof,
        amount: 1000000,
        recipient: 'YOUR_WALLET_ADDRESS',
        network: 'solana'
      })
    });

    const result = await verification.json();

    if (result.verified) {
      // Settle the payment
      await fetch('https://api.oura402.dev/v1/payments/settle', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer YOUR_API_KEY'
        },
        body: JSON.stringify({
          payment_id: result.payment_id
        })
      });

      // Payment verified and settled, return the resource
      return res.json({ data: 'Your protected resource' });
    } else {
      return res.status(402).json({ error: 'Invalid payment' });
    }
  } catch (error) {
    return res.status(500).json({ error: 'Payment verification failed' });
  }
});

What's Next?

• Check out the API Reference for all the details

• See more code examples in your favorite language

• Set up WebSocket streaming to get notified when payments happen

• Read about x402 if you're curious how it works under the hood

Quick Tips

1. Keep your API key secret - Never expose it in frontend code or commit it to version control systems

2. Check payment amounts - Verify that received payments match expected amounts

3. Handle errors - Implement proper error handling for network failures and API timeouts

4. Start small - Begin testing with small transaction amounts

5. Use WebSockets - Enable real-time payment notifications for improved responsiveness

How x402 Works (Overview)

1. A client requests your API → Your server returns a 402 status code with payment requirements

2. The client submits a payment → Your server verifies it with Oura402

3. Payment is validated → Your server returns the requested resource

Oura402 handles all blockchain infrastructure, allowing you to focus on your application logic.