> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Therius Quickstart: Your First Payment in 5 Minutes

> Send a real sandbox payment with the Therius API in under five minutes — no SDK needed, no frontend setup. Just a key and a curl command.

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.

<Warning>
  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.
</Warning>

## Steps

<Steps>
  <Step title="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.
  </Step>

  <Step title="Fire your first purchase">
    Paste the following command into your terminal, replacing `prv_sandbox_your_key_here` with your actual sandbox key.

    ```bash theme={"dark"}
    curl -X POST https://api-sandbox.therius.io/v1/payment/purchase \
      -H "Authorization: Bearer prv_sandbox_your_key_here" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "merchantCode": "MERCHANT_001",
        "orderCode": "QUICKSTART-001",
        "amount": { "currency": "USD", "value": 1999, "exponent": 2 },
        "card": {
          "cardData": {
            "cardNumber": "4111111111111111",
            "cardholderName": "Ada Lovelace",
            "expiryMonth": "12",
            "expiryYear": "2030",
            "cvv": "123"
          }
        }
      }'
    ```

    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:

    ```json theme={"dark"}
    {
      "id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
      "status": "captured",
      "paymentCode": "PAY-abc123xyz",
      "orderCode": "QUICKSTART-001",
      "amount": { "currency": "USD", "value": 1999, "exponent": 2 }
    }
    ```

    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.)
  </Step>

  <Step title="Look up the payment">
    Retrieve any payment by passing its `id` (or its `paymentCode`) to `GET /payment/inquiry/{id}`.

    ```bash theme={"dark"}
    curl https://api-sandbox.therius.io/v1/payment/inquiry/9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e \
      -H "Authorization: Bearer prv_sandbox_your_key_here"
    ```

    The response returns the same `PaymentResponse` shape as the original purchase, including the current `status` and full amount details.
  </Step>

  <Step title="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.

    ```json theme={"dark"}
    {
      "merchantCode": "MERCHANT_001",
      "orderCode": "QUICKSTART-002",
      "amount": { "currency": "USD", "value": 1999, "exponent": 2 },
      "shopper": { "id": "shopper-42" },
      "card": {
        "cardData": {
          "cardNumber": "4111111111111111",
          "cardholderName": "Ada Lovelace",
          "expiryMonth": "12",
          "expiryYear": "2030",
          "cvv": "123",
          "tokenize": true
        }
      }
    }
    ```

    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.

    ```json theme={"dark"}
    {
      "card": {
        "tokenData": {
          "token": "vt_abc123"
        }
      }
    }
    ```
  </Step>

  <Step title="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.

    <Warning>
      Confirm that every mutating request in your production code sends an `Idempotency-Key` header before going live.
    </Warning>
  </Step>
</Steps>

## What's Next

<CardGroup cols={3}>
  <Card icon="book" title="API Reference" href="/api-reference">
    Explore every endpoint — purchase, authorize, capture, refund, cancel, subscriptions, and more.
  </Card>

  <Card icon="code" title="JS SDK" href="/sdk/overview">
    Embed a PCI-safe card form in your frontend without raw card data touching your server.
  </Card>

  <Card icon="plug" title="Connections" href="/connections">
    Connect acquirers, processors, and alternative payment providers to your Therius account.
  </Card>

  <Card icon="bell" title="Webhooks" href="/webhooks/overview">
    Receive payment and subscription events on your server, with signature verification.
  </Card>

  <Card icon="flask-vial" title="Testing" href="/guides/testing">
    Every sandbox test card, decline reason, and 3D Secure scenario in one table.
  </Card>
</CardGroup>