Skip to main content
The Therius sandbox is a fully isolated test environment — requests hit a test-provider stub, no real money moves, and no card network is involved. Your sandbox key starts with prv_sandbox_... and every Therius account includes one by default. Everything you build here works identically in production; you only swap the key and base URL when you are ready to go live.
The Idempotency-Key header is mandatory in production. Retrying a network timeout without it can double-charge a customer. The examples below include it so you build the habit from the start.

​
Steps

1

Get a sandbox key

Log in to your Therius dashboard and copy the key labeled Sandbox Secret Key. It looks like prv_sandbox_xxxxxxxxxxxx.Every request to https://api-sandbox.therius.io/v1 sends this key as Authorization: Bearer prv_sandbox_.... The key prefix (prv_sandbox_) tells Therius to route the request to the sandbox environment automatically — no extra configuration needed.
2

Fire your first purchase

Paste the following command into your terminal, replacing prv_sandbox_your_key_here with your actual sandbox key.
A few things to note about this request:
  • Test cards — 4111111111111111 always results in a sandbox approval. Use 4000000000000002 to simulate a decline.
  • amount.value is always in minor units. 1999 means $19.99 in USD. For zero-decimal currencies like JPY or CLP, 1999 means ¥1999.
  • amount.exponent is the number of decimal places: 2 for USD/EUR, 0 for JPY/CLP.
A successful response looks like this:
Save the id — it is the handle for this payment, used as the {id} path segment for capture, refund and cancel. (paymentCode is a reference for lookups and reconciliation.)
3

Look up the payment

Retrieve any payment by passing its id (or its paymentCode) to GET /payment/inquiry/{id}.
The response returns the same PaymentResponse shape as the original purchase, including the current status and full amount details.
4

Tokenize a card

To save a card for a returning shopper, add "tokenize": true and a shopper.id to your purchase request. Therius stores the card in its vault and returns a token in the response.
The response includes a token field (e.g., vt_abc123). On future requests for this shopper, pass card.tokenData.token instead of card.cardData — no card number needed.
5

Go live

When you are ready to accept real payments, make two changes:
  1. Replace prv_sandbox_... with your production key prv_production_....
  2. Point your requests at https://api.therius.io/v1 instead of https://api-sandbox.therius.io/v1.
No other code changes are required. The key prefix selects the environment automatically.
Confirm that every mutating request in your production code sends an Idempotency-Key header before going live.

​
What’s Next

API Reference

Explore every endpoint — purchase, authorize, capture, refund, cancel, subscriptions, and more.

JS SDK

Embed a PCI-safe card form in your frontend without raw card data touching your server.

Connections

Connect acquirers, processors, and alternative payment providers to your Therius account.

Webhooks

Receive payment and subscription events on your server, with signature verification.

Testing

Every sandbox test card, decline reason, and 3D Secure scenario in one table.