Quickstart

In a few minutes, you’ll create a test payment link, settle it, and see the webhook land — all from your terminal. No code yet — just curl. Once it works end-to-end, port the same calls into your stack.

0. Get a test API key

Self-serve, no waiting on us: in the business dashboard, Settings → Developers → New API key. Name it, pick test, and give it payments:create + payments:read. Copy the full key now — it’s shown once. (Need a merchant account provisioned first? That part is still [email protected].)

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 payment link

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

You’ll get back the link:

{
  "success": true,
  "data": {
    "id": "…",
    "link_code": "PL-A1B2C3D4",
    "title": "Quickstart test",
    "amount": 1250,
    "currency": "USD",
    "status": "pending"
  }
}

amount: 1250 is cents — that’s $12.50. Every amount in Soxara is an integer in the currency’s minor unit. (more →)

The real payer URL is https://checkout.soxara.com/{link_code} — but for this quickstart, skip the browser and settle it directly (next step).

3. Settle it (sandbox only)

Test links can be settled instantly, without a browser or a real card/MoMo, via simulate:

curl -sS -X POST "$SOXARA_BASE/v1/api/payment-links/{id}/simulate" \
  -H "Authorization: Bearer $SOXARA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "card", "outcome": "completed"}'

This runs the same settlement fan-out a real payment does — including firing your webhook (step 5) — just without touching a card network or MoMo.

4. Retrieve the payment

curl -sS "$SOXARA_BASE/v1/api/payments/{payment_id}" \
  -H "Authorization: Bearer $SOXARA_KEY"

Returns the payment’s current status — this is the read your own reconciliation job calls if a webhook is ever missed.

5. Subscribe to webhooks

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

The response includes a secret — store it now, it’s shown once. Every webhook delivery is signed with it; verify the signature before trusting the payload. (handle-webhook guide →)

Register this endpoint before step 3 if you want to actually see the delivery land — order doesn’t matter for the API calls themselves, but you’ll only catch the webhook in real time if your endpoint already exists when you simulate.

6. 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. simulate settles a test link instantly; a live link only settles through real checkout.
• Payloads carry "environment": "test" inside data.payment, so you can double-check you’re looking at test traffic.
• Rate limits are shared with live traffic — sandbox isn’t more permissive.

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