Quickstart

In 15 minutes, you’ll make a test payment through Soxara from your terminal. No code yet — just curl. Once it works end-to-end, port the same calls into your stack.

You need a test API key. During the early-access window, request one at [email protected]. Self-serve key creation in the business dashboard is shipping soon.

1. Set your environment

Your test key looks like sxm_test_AbCdEfGh<32 random chars>. Live keys look identical but start with sxm_live_. The prefix is how Soxara routes your request to sandbox or production — same URL, same endpoints. (more on environments →)

export SOXARA_KEY=sxm_test_AbCdEfGh...replaceme...
export SOXARA_BASE=https://api.soxara.com

2. Create a test PaymentIntent

Stripe-style: you create a PaymentIntent on the server, hand its client_secret to your customer’s browser/app, and they confirm it with their card details.

curl -sS -X POST "$SOXARA_BASE/v1/payments" \
  -H "Authorization: Bearer $SOXARA_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 1250,
    "currency": "USD",
    "description": "Quickstart test"
  }'

You’ll get back a payment object with a client_secret:

{
  "success": true,
  "data": {
    "id": "pi_3TZ...",
    "status": "requires_payment_method",
    "amount": 1250,
    "currency": "USD",
    "client_secret": "pi_3TZ..._secret_...",
    "livemode": false
  }
}

Two things to note:

• amount: 1250 is cents. That’s $12.50. Every amount in Soxara is an integer in the currency’s minor unit. (more →)
• livemode: false confirms you’re in sandbox. Your test key never touches a real card.

3. Retrieve the PaymentIntent

curl -sS "$SOXARA_BASE/v1/payments/pi_3TZ..." \
  -H "Authorization: Bearer $SOXARA_KEY"

Same payment object comes back. This is the call your frontend makes to verify status before showing a success screen.

4. Subscribe to webhooks

When a payment moves from requires_payment_method → succeeded (or fails, or gets refunded), Soxara POSTs a webhook to your endpoint.

Register a webhook URL (one per environment — test keys point at your sandbox URL, live keys point at production):

curl -sS -X POST "$SOXARA_BASE/v1/webhook-endpoints" \
  -H "Authorization: Bearer $SOXARA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/soxara",
    "events": ["payment.succeeded", "payment.failed", "refund.created"]
  }'

The response includes a signing_secret — store it. Every webhook delivery is signed with it; verify the signature before trusting the payload. (handle-webhook guide →)

5. What to read next

Test mode safe-zone

Test mode is identical to production in shape — same endpoints, same response envelope, same webhook events — except:

• No real money moves. Test cards (4242 4242 4242 4242) succeed; live cards are rejected.
• MoMo deposits return synthetic success/failure based on the MSISDN you supply.
• Webhooks always have "livemode": false in the payload.

Anything that works in test mode will work in production with one change: swap sxm_test_* for sxm_live_* in your Authorization header. URL doesn’t change.