TeraWallet Documentation

TeraWallet ships a first-class REST API under the terawallet/v1 namespace. It powers the plugin’s own React dashboard and admin screens, and is fully available to your own apps and integrations.

The older wc/v3/wallet/* routes still exist as a deprecated back-compatibility layer and will be removed in a future major release. New integrations should target terawallet/v1.

Base URL

https://your-store.com/wp-json/terawallet/v1/

Authentication

Endpoints are grouped by who may call them, and each group uses the matching auth method:

Group	Path prefix	Who	Authentication
Customer	`me/*`	The logged-in customer (acts on their own wallet)	WordPress cookie + REST nonce (same-origin), e.g. an `X-WP-Nonce` header
Admin	`admin/*`	Users with the `manage_woocommerce` capability	Cookie + nonce, or WooCommerce Consumer Key / Secret (Basic Auth)
Settings / System	`settings/`, `system/`	`manage_woocommerce`	Cookie + nonce, or Consumer Key / Secret
Public	`public/*`, `settings/public`	Anyone	None

For external/server-to-server calls, generate keys under WooCommerce → Settings → Advanced → REST API and send them as HTTP Basic Auth.

Idempotency

State-changing customer endpoints (POST me/topup, POST me/transfer) and admin bulk operations honor an Idempotency-Key request header. Send a unique key (e.g. a UUID) per logical action; a retry with the same key replays the original response instead of creating a duplicate top-up, transfer, or credit. Keys are scoped per user with a 24-hour TTL.

Customer endpoints (`me/*`)

Get balance

GET /terawallet/v1/me/balance

Returns the current user’s balance. The response is multi-currency aware: amount is in the active storefront currency, while base_* fields are always normalized to the shop base currency.

{
  "amount": 250.00,
  "currency": "USD",
  "formatted": "$250.00",
  "base_currency": "USD",
  "base_amount": 250.00,
  "base_formatted": "$250.00",
  "mode": "single_base",
  "balances": [
    { "currency": "USD", "amount": 250.00, "formatted": "$250.00" }
  ]
}

Field	Description
`amount` / `currency` / `formatted`	Balance in the active storefront currency.
`base_amount` / `base_currency`	Total wallet value normalized to the shop base currency.
`mode`	`single_base` or `per_currency` (see multi-currency).
`balances[]`	Per-currency sub-balances; always at least one entry.

List transactions

GET /terawallet/v1/me/transactions
GET /terawallet/v1/me/transactions/{id}

Paginated ledger history for the current user.

Query arg	Type	Notes
`page`, `per_page`	integer	Standard pagination.
`orderby`	string	`date`, `amount`, or `transaction_id`.
`order`	string	`asc` or `desc`.
`type`	string	Filter by `credit` or `debit`.
`category`	string	Filter by transaction category (see below).

Each row exposes a typed category, one of: topup, cashback, cashback_adjustment, cashback_refund, partial_payment, transfer, refund, adjustment, other.

Create a top-up

POST /terawallet/v1/me/topup

Creates a top-up order and returns a payment URL to redirect the customer to.

Body field	Type	Required	Notes
`amount`	number	Yes	Minimum `0.01`.
`payment_method`	string	No	A WooCommerce gateway id (e.g. `stripe`).
`currency`	string	No	ISO 4217 code; charges the top-up in that currency.

{
  "order_id": 1234,
  "amount": 50.00,
  "currency": "USD",
  "payment_url": "https://your-store.com/checkout/order-pay/1234/?pay_for_order=true&key=wc_order_..."
}

Send an Idempotency-Key header so a double-submit (or a network retry) returns the original order instead of creating a second top-up.

Transfer funds

POST /terawallet/v1/me/transfer
GET  /terawallet/v1/me/transfer/recipients

Send wallet balance to another registered user. Provide either recipient_id or recipient_email.

Body field	Type	Required	Notes
`recipient_id`	integer	One of id/email	Recipient user id.
`recipient_email`	string	One of id/email	Recipient account email.
`amount`	number	Yes	Subject to the configured min/max and transfer charge.
`note`	string	No	Optional message stored on both ledger legs.
`currency`	string	No	Optional ISO 4217 code.

The recipients route returns a lookup list for an autocomplete picker (gated by a filter).

Endpoint	Returns
`GET /terawallet/v1/me`	Profile snapshot with wallet summary and related links.
`GET /terawallet/v1/me/referrals`	The customer’s referral share URL, visitor/signup counts and earnings.
`GET /terawallet/v1/me/cashback-rules`	The cashback rules currently active for this customer/cart.

Admin endpoints (`admin/*`)

Require the manage_woocommerce capability.

Transactions

GET    /terawallet/v1/admin/transactions
POST   /terawallet/v1/admin/transactions
GET    /terawallet/v1/admin/transactions/{id}
PATCH  /terawallet/v1/admin/transactions/{id}
DELETE /terawallet/v1/admin/transactions/{id}?force=true
POST   /terawallet/v1/admin/transactions/bulk

List supports page, per_page, orderby (id, transaction_id, date, amount, currency, type, user_id), order, and type filters. Create a manual credit or debit:

{
  "user_id": 42,
  "type": "credit",
  "amount": 10.00,
  "details": "Goodwill credit"
}

DELETE performs a soft delete by default; pass ?force=true for a permanent delete. The bulk route accepts an action of credit, debit, or delete and is idempotent per user.

Users

GET  /terawallet/v1/admin/users
GET  /terawallet/v1/admin/users/{id}
POST /terawallet/v1/admin/users/{id}/lock
POST /terawallet/v1/admin/users/{id}/unlock

List users with their balances, read a single user, and lock/unlock a wallet to block further spending (useful for fraud holds).

Admin transfer

POST /terawallet/v1/admin/transfer

Move balance between two users on the customer’s behalf.

Settings & system endpoints

Endpoint	Description
`GET /terawallet/v1/settings`	Fetch all plugin settings.
`POST /terawallet/v1/settings/section`	Save a settings section (`section_id` + fields).
`POST /terawallet/v1/settings/js-section`	Save a JS-registered settings tab (sanitized per server whitelist).
`GET /terawallet/v1/system/multicurrency`	Active currency provider, base/active currencies and ledger mode.
`GET /terawallet/v1/settings/public`	Unauthenticated public settings (e.g. cashback rules).

All responses are JSON. Send Content-Type: application/json on requests with a body, and an Idempotency-Key header on top-ups, transfers and bulk operations.

Legacy namespace (deprecated)

The wc/v3/wallet/* routes from earlier versions remain as thin proxies for back-compatibility and emit the same row shapes as their terawallet/v1 equivalents. Do not build new integrations against them — migrate to terawallet/v1.

REST API Reference

Base URL

Authentication

Idempotency

Customer endpoints (`me/*`)

Get balance

List transactions

Create a top-up

Transfer funds

Other customer reads

Admin endpoints (`admin/*`)

Transactions

Users

Admin transfer

Settings & system endpoints

Legacy namespace (deprecated)

​Base URL

​Authentication

​Idempotency

​Customer endpoints (me/*)

​Get balance

​List transactions

​Create a top-up

​Transfer funds

​Other customer reads

​Admin endpoints (admin/*)

​Transactions

​Users

​Admin transfer

​Settings & system endpoints

​Legacy namespace (deprecated)

Base URL

Authentication

Idempotency

Customer endpoints (`me/*`)

Get balance

List transactions

Create a top-up

Transfer funds

Other customer reads

Admin endpoints (`admin/*`)

Transactions

Users

Admin transfer

Settings & system endpoints

Legacy namespace (deprecated)