Wallets & Billing API

Manage multi-currency wallet balances, convert between currencies, apply promo credits, and complete Stripe checkout flows.

Wallets

List Wallet Balances

GET /v1/billing/wallets

Returns balances for all currencies in the project.

curl https://api.fugoku.com/v1/billing/wallets \
  -H "X-Fugoku-API-Key: $FUGOKU_API_TOKEN"

Get Wallet Balance

GET /v1/billing/wallets/:currency

curl https://api.fugoku.com/v1/billing/wallets/USD \
  -H "X-Fugoku-API-Key: $FUGOKU_API_TOKEN"

Credit Wallet

POST /v1/billing/wallets/:currency/credit

Request Body:

Field	Type	Description
`amountCents`	integer	Amount to credit in cents (must be positive)

curl -X POST https://api.fugoku.com/v1/billing/wallets/USD/credit \
  -H "X-Fugoku-API-Key: $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{ "amountCents": 5000 }'

Debit Wallet

POST /v1/billing/wallets/:currency/debit

curl -X POST https://api.fugoku.com/v1/billing/wallets/USD/debit \
  -H "X-Fugoku-API-Key: $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amountCents": 2500 }'

Currency Conversion

Convert Amount

POST /v1/billing/convert

Request Body:

Field	Type	Description
`amountCents`	integer	Amount to convert in cents
`fromCurrency`	string	Source currency code
`toCurrency`	string	Target currency code

Get Exchange Rate

GET /v1/billing/rates/:from/:to

curl https://api.fugoku.com/v1/billing/rates/USD/NGN \
  -H "X-Fugoku-API-Key: $FUGOKU_API_TOKEN"

Credits

List Credits

GET /v1/billing/credits

POST /v1/billing/credits/promo

Request Body:

Field	Type	Description
`amountCents`	integer	Credit amount in cents
`currency`	string	`USD` or `NGN`
`description`	string	Optional description

Billing Overview

Get Billing Overview

GET /v1/billing/overview

Returns a summary of wallets, credits, payments, and invoices.

curl https://api.fugoku.com/v1/billing/overview \
  -H "X-Fugoku-API-Key: $FUGOKU_API_TOKEN"

Response:

{
  "data": {
    "type": "billing-overview",
    "id": "proj-abc123",
    "attributes": {
      "totalSpendCents": 186200,
      "totalCreditsCents": 1000,
      "upcomingChargesCents": 12000,
      "currency": "USD",
      "balances": [
        { "currency": "USD", "balanceCents": 50000 },
        { "currency": "NGN", "balanceCents": 7500000 }
      ],
      "paymentCount": 5,
      "creditCount": 1,
      "invoiceCount": 2
    }
  }
}

Checkout

Create Setup Intent

POST /v1/billing/checkout/setup-intent

Creates a Stripe Setup Intent for collecting payment method details.

POST /v1/billing/checkout/:checkoutId/promo

Request Body:

Field	Type	Description
`code`	string	Promo code to apply

Complete Checkout

POST /v1/billing/checkout/:checkoutId/complete

Request Body:

Field	Type	Description
`paymentMethodId`	string	Stripe payment method ID
`setupIntentId`	string	Stripe setup intent ID

Usage

Get Usage Data

GET /v1/billing/usage

Returns usage data for billing calculations.

curl https://api.fugoku.com/v1/billing/usage \
  -H "X-Fugoku-API-Key: $FUGOKU_API_TOKEN"

Wallets & Billing API

On this page