Quickstart

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 (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_`

Create your Simiz account

Sign up at 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.

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

Never expose your secret key in client-side code or public repositories. Use environment variables to store your keys securely.

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.

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:

{
  "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"
}

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

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.

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:

{
  "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.

See the Signature Verification guide for full examples in Node.js, Python and PHP.

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

Full sandbox documentation

See all test numbers and scenarios in the Sandbox guide.

Next steps

Choosing a plan? Visit the pricing page 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

Configure Webhooks

Set up real-time notifications for payment events.

Explore the API

Browse the full API reference.

Getting Started

Core Concepts

Billing

Guides

Prerequisites

Environments

Sandbox test numbers

Full sandbox documentation

Next steps

Configure Webhooks

Explore the API

​Prerequisites

​Environments

​Sandbox test numbers

Full sandbox documentation

​Next steps

Configure Webhooks

Explore the API

Prerequisites

Environments

Sandbox test numbers

Next steps