Payments & Web3 API

Handle cryptocurrency payments, credit card processing, and voucher redemptions.

Web3 Payments

Get Crypto Conversion Rates {#get-conversions}

Get current cryptocurrency to USD conversion rates.

Endpoint

GET /api/v1/web3/conversions

Authentication

Required

Response

{
  "ETH": "2500.50",
  "DRGN": "0.05",
  "USDC": "1.00",
  "USDT": "1.00"
}

Supported Cryptocurrencies

• ETH - Ethereum
• DRGN - Dragonchain Token
• USDC - USD Coin
• USDT - Tether

Submit Transaction Hash {#submit-txn-hash}

Submit blockchain transaction hash for purchase verification.

Endpoint

POST /api/v1/web3/purchase/txnhash

Authentication

Required

Request Body

{
  "purchaseId": 12345,
  "txnHash": "0xabc123..."
}

Request Fields

Response

204 No Content

Notes

• Payment status starts as PENDING
• Backend verifies transaction hash against blockchain
• Automatically determines payment type (spawn or marketplace)

Get Payment Status {#get-payment}

Check status of a web3 payment.

Endpoint

GET /api/v1/web3/payment/{id}

Authentication

Required - Must own the payment

Path Parameters

Response

{
  "id": 1,
  "accId": "user123",
  "purchaseRequest": { /* full purchase request */ },
  "txnHash": "0xabc123...",
  "txnStatus": "PENDING",
  "paymentType": "spawn",
  "paymentSource": "ETH"
}

Transaction Statuses

• PENDING - Awaiting blockchain confirmation
• CONFIRMED - Transaction confirmed
• FAILED - Transaction failed

Vouchers

Purchase with Voucher {#purchase-voucher}

Complete purchase using a voucher.

Endpoint

POST /api/v1/voucher/purchase

Authentication

Required

Request Body

{
  "purchaseId": 12345
}

Request Fields

Response

204 No Content

Process Flow

1. Validates purchase total fee is zero (voucher covers cost)
2. Posts PAYMENT transaction to Dragonchain
3. Waits 15 seconds for initial processing
4. Polls transaction status until confirmed
5. Retrieves block proof for verification
6. Finalizes purchase

Notes

• Voucher must cover entire purchase cost
• Includes automatic polling for blockchain confirmation

Credit Card (Stripe)

Create Spawn Checkout Session {#spawn-checkout}

Create Stripe checkout session for spawning eggs.

Endpoint

POST /api/v1/cc/spawn/checkout/{id}

or

POST /api/v1/cc/checkout/{id}

Authentication

Required - Must own purchase request

Path Parameters

Response

{
  "stripeRedirectUrl": "https://checkout.stripe.com/..."
}

Notes

• Purchase request must exist and belong to you
• Purchase request must not be expired
• Supports eggs, keys, and gateway key vouchers
• Redirects to Stripe checkout page

Create Marketplace Checkout Session {#marketplace-checkout}

Create Stripe checkout session for marketplace purchase.

Endpoint

POST /api/v1/cc/marketplace/checkout/{id}

Authentication

Required - Must own purchase request

Path Parameters

Response

{
  "stripeRedirectUrl": "https://checkout.stripe.com/..."
}

Notes

• Purchase request must exist and belong to you
• Purchase request must not be expired
• Calculates total including marketplace fees
• Redirects to Stripe checkout page

Stripe Webhook {#stripe-webhook}

Webhook endpoint for Stripe payment events.

Endpoint

POST /api/v1/cc/webhook

Authentication

Not required (validates Stripe signature)

Notes

• Validates Stripe signature for security
• Stores all events in database
• Processes checkout.session.completed events
• For spawn: Posts to Dragonchain and processes purchase
• For marketplace: Transfers asset and creates wallet transaction
• Uses database transaction for atomicity

Bot Integration

X (Twitter) OAuth Callback {#bot-oauth}

OAuth callback for X bot integration.

Endpoint

GET /api/v1/bot/oauth

Authentication

Not required (public callback)

Query Parameters

Response

{
  "code": "oauth_code",
  "state": "state_value",
  "error": ""
}

Notes

• Callback endpoint called by X OAuth service
• State parameter should be validated to prevent CSRF

System Metrics

Get System Metrics {#get-metrics}

Retrieve system-wide statistics.

Endpoint

GET /api/v1/metrics

Authentication

Not required (public endpoint)

Response

{
  "totalUsers": 5000,
  "totalDragons": 15000,
  "totalEggs": 8000,
  "marketplaceListings": 250,
  "marketplaceSales": 1200
}

Notes

• Returns comprehensive system metrics
• Includes users, dragons, eggs, and marketplace activity