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

# Quickstart

> Accept your first payment with Simiz in under 5 minutes.

By the end of this guide, you'll have created a sandbox payment with the Simiz API and redirected the customer to the hosted payment page.

## Prerequisites

* A [Simiz account](https://simiz.io/register) (free to create)
* cURL or any HTTP client

## Environments

| Environment    | Base URL                          | Key prefix  |
| -------------- | --------------------------------- | ----------- |
| **Sandbox**    | `https://sandbox.api.simiz.io/v1` | `smz_test_` |
| **Production** | `https://api.simiz.io/v1`         | `smz_live_` |

<Steps>
  <Step title="Create your Simiz account">
    Sign up at [simiz.io/register](https://simiz.io/register). You'll get instant access to your dashboard and sandbox environment.

    Once signed in, navigate to **Settings → API Keys** to find your test credentials.
  </Step>

  <Step title="Get your API keys">
    You'll have two types of API keys:

    | Key type     | Format                 | Purpose                                 |
    | ------------ | ---------------------- | --------------------------------------- |
    | **Test key** | `smz_test_sk_xxxxxxxx` | Sandbox transactions — no real money    |
    | **Live key** | `smz_live_sk_xxxxxxxx` | Production transactions — real payments |

    <Warning>
      **Never expose your secret key** in client-side code or public repositories. Use environment variables to store your keys securely.
    </Warning>
  </Step>

  <Step title="Create your first payment">
    From your backend, create a payment with your API key. Add an `Idempotency-Key` header to safely retry the request without creating a duplicate (key valid for 24h). See the [`POST /payments`](/api-reference/payments/create-a-payment) API reference.

    ```bash
    curl -X POST https://sandbox.api.simiz.io/v1/payments \
      -H "Authorization: Bearer smz_test_sk_xxxxxxxx" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: order-1234" \
      -d '{
        "userId": "550e8400-e29b-41d4-a716-446655440000",
        "amount": 5000,
        "currency": "XAF",
        "returnUrl": "https://your-site.com/payment/success",
        "cancelUrl": "https://your-site.com/payment/cancel",
        "description": "Order #1234"
      }'
    ```

    The response returns the payment `token`, its `PENDING` status and the hosted payment URL:

    ```json
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "token": "pay_abc123xyz789",
      "amount": 5000,
      "currency": "XAF",
      "status": "PENDING",
      "paymentUrl": "https://pay.simiz.io/pay/pay_abc123xyz789",
      "livemode": false,
      "createdAt": "2024-01-15T10:30:00Z"
    }
    ```
  </Step>

  <Step title="Redirect the customer to pay">
    Redirect the customer to the returned `paymentUrl`. On this hosted page they pick their Mobile Money operator (Orange Money, MTN MoMo…), enter their number and confirm via a USSD prompt on their phone.

    When done, Simiz sends them back to your `returnUrl` (success) or `cancelUrl` (cancelled).

    <Tip>
      The `returnUrl` does not prove payment — it's just a browser redirect. Always confirm the payment server-side via the webhook (below) or [`GET /v1/payments/{token}/verify`](/api-reference/payments/verify-payment-status).
    </Tip>
  </Step>

  <Step title="Confirm with a webhook">
    Once the payment is confirmed by the operator, Simiz sends a `transaction.completed` webhook to the webhook URL configured in your dashboard:

    ```json
    {
      "id": "evt_abc123",
      "type": "transaction.completed",
      "createdAt": "2024-03-15T10:30:00Z",
      "data": {
        "token": "pay_abc123xyz789",
        "amount": 5000,
        "currency": "XAF",
        "status": "COMPLETED"
      }
    }
    ```

    Every webhook is signed. Verify the `X-Simiz-Signature` header (format `t={timestamp},v1={hmac}`, HMAC-SHA256 computed over `{timestamp}.{raw_body}`) before processing the event.

    <Tip>
      See the [Signature Verification](/en/core-concepts/webhooks/signature-verification) guide for full examples in Node.js, Python and PHP.
    </Tip>
  </Step>
</Steps>

## Sandbox test numbers

On the hosted payment page in sandbox, use these numbers to simulate different outcomes:

| Number         | Operator     | Result               |
| -------------- | ------------ | -------------------- |
| `237690000001` | Orange Money | Success              |
| `237670000001` | MTN MoMo     | Success              |
| `237690000002` | Orange Money | Insufficient balance |
| `237690000003` | Orange Money | Timeout              |

<Card title="Full sandbox documentation" icon="flask" href="/en/guides/sandbox-testing">
  See all test numbers and scenarios in the Sandbox guide.
</Card>

## Next steps

<Tip>
  **Choosing a plan?** Visit the [pricing page](/en/core-concepts/billing/pricing) and append `?intent=growth` (or `starter` / `scale`) to the contact URL to pre-fill your plan of interest in the sales form.

  Example: `https://simiz.io/contact?intent=growth`
</Tip>

<CardGroup cols={2}>
  <Card title="Configure Webhooks" icon="webhook" href="/en/core-concepts/webhooks/overview">
    Set up real-time notifications for payment events.
  </Card>

  <Card title="Explore the API" icon="code" href="/api-reference">
    Browse the full API reference.
  </Card>
</CardGroup>