Billing Endpoints

Get Credit Balance

GET /api/v1/billing/balance

Scope: billing

Response

{
  "data": {
    "balanceCents": 15000,
    "currency": "USD"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-03-02T12:00:00.000Z"
  }
}

---

List Payment History

GET /api/v1/billing/payments

Scope: billing

Query Parameters

Parameter	Type	Default	Description
limit	integer	20	Max 100
cursor	string	—	Pagination cursor

Response

{
  "data": {
    "payments": [
      {
        "id": "pay-uuid",
        "amountCents": 10000,
        "status": "completed",
        "provider": "stripe",
        "externalId": "cs_abc123",
        "createdAt": "2026-02-15T10:00:00.000Z"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-03-02T12:00:00.000Z",
    "hasMore": false
  }
}

---

Get Payment Details

GET /api/v1/billing/payments/:id

Scope: billing

Response

{
  "data": {
    "payment": {
      "id": "pay-uuid",
      "amountCents": 10000,
      "status": "completed",
      "provider": "stripe",
      "externalId": "cs_abc123",
      "createdAt": "2026-02-15T10:00:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-03-02T12:00:00.000Z"
  }
}

---

Download Invoice

GET /api/v1/billing/payments/:id/invoice

Scope: billing

Returns a PDF invoice for the given payment. The response is a binary PDF file.

---

Purchase Credit (Stripe)

POST /api/v1/billing/credit

Scope: game_owner

Creates a Stripe Checkout session to top up account credit. The response includes a checkoutUrl to redirect the user to for payment.

Request Body

Field	Type	Required	Description
amountCents	integer	Yes	Amount in cents. Min 2000 ($20), max 1000000 ($10,000)
returnUrl	string	No	URL to redirect to after checkout. Appends ?payment_id=...&status=success or ?status=cancelled

Response

{
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_...",
    "paymentId": "pay-uuid",
    "amountCents": 10000
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-03-02T12:00:00.000Z"
  }
}

Redirect the user to checkoutUrl to complete payment. On success, credit is added automatically to their account.

---

Purchase Credit (x402 Crypto)

POST /api/v1/billing/credit/x402

Scope: game_owner

Top up account credit using crypto via the x402 payment protocol (USDC, ETH, or SOL). This is a two-step flow.

See the x402 Payments guide for full details on the x402 protocol.

Request Body

Field	Type	Required	Description
amountCents	integer	Yes	Amount in USD cents. Min 500 ($5), max 1000000 ($10,000)

Step 1 — Get payment instructions (402 response)

Send the request with the X-Payment-Method: x402 header and your preferred chain/currency:

curl -X POST https://app.weplaytestgames.com/api/v1/billing/credit/x402 \
  -H "Authorization: Bearer wpg_sk_..." \
  -H "Content-Type: application/json" \
  -H "X-Payment-Method: x402" \
  -H "X-Payment-Chain: base" \
  -H "X-Payment-Currency: USDC" \
  -d '{ "amountCents": 5000 }'

Returns 402 Payment Required with payment details:

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Send 50.00 USDC on base to complete this purchase",
    "payment": {
      "id": "x402-payment-uuid",
      "chain": "base",
      "currency": "USDC",
      "cryptoAmount": "50.00",
      "receiver": "0xABC...",
      "network": "mainnet",
      "expiresAt": "2026-03-02T12:15:00.000Z"
    }
  }
}

The X-Payment response header contains the full payment instructions in x402 format.

Step 2 — Submit transaction hash (confirmation)

After broadcasting the transaction, re-send the request with an X-Payment header containing a JSON object with your transaction hash, chain, and currency. No request body is needed — the amount is looked up from the pending payment created in Step 1:

curl -X POST https://app.weplaytestgames.com/api/v1/billing/credit/x402 \
  -H "Authorization: Bearer wpg_sk_..." \
  -H 'X-Payment: {"txHash":"0xabc123...","chain":"base","currency":"USDC"}'

Returns 200 on success:

{
  "data": {
    "message": "Payment confirmed",
    "paymentId": "pay-uuid",
    "creditedCents": 5000
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-03-02T12:00:00.000Z"
  }
}