Guide

Getting started

Get a sandbox key, make your first authenticated call and price your first quote.

The Moja Switch Partner API is JSON over HTTPS. This guide takes you from no credentials to a priced quote in the sandbox, in three calls.

#1. Get a sandbox API key

POST /signup creates a sandbox partner and returns a sandbox API key. It is the only endpoint that needs no key. It can only ever create sandbox access.

curl -sS -X POST https://api-sandbox.mojaswitch.com/v1/signup \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Acme Remit", "contact_email": "dev@acme.example" }'

The 201 response contains your partner id, status: SANDBOX, your corridor entitlements and an api_key object. api_key.secret is shown once. Store it in your secrets manager now; Moja Switch keeps only a hash and cannot show it again.

{
  "id": "partner_acme_remit",
  "status": "SANDBOX",
  "corridor_entitlements": [{ "corridor": "CA-TZ", "enabled": true }],
  "api_key": {
    "environment": "sandbox",
    "key_prefix": "sk_sandbox_1a2b3c",
    "secret": "sk_sandbox_…"
  }
}

The response is abridged. The full schema is in the API reference.

Export the key for the rest of this guide:

export MOJA_KEY='sk_sandbox_…'   # never commit or log this value
export MOJA_BASE='https://api-sandbox.mojaswitch.com/v1'

#2. Read a corridor

Corridors are data, not a fixed list. Read the one you are entitled to, and take its currencies and minor-unit exponents from the response rather than hardcoding them.

curl -sS "$MOJA_BASE/corridors/CA-TZ" \
  -H "Authorization: Bearer $MOJA_KEY"

The response lists the payout methods, the limits in force and, for both currencies, minor_unit_exponent. Never assume two decimal places: some currencies have none. See Get corridor detail.

#3. Price your first quote

curl -sS -X POST "$MOJA_BASE/quotes" \
  -H "Authorization: Bearer $MOJA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "corridor": "CA-TZ",
    "send_amount": { "value": "100.00", "currency": "CAD" },
    "receive_currency": "TZS",
    "payout_method": "MOBILE_MONEY"
  }'

The 201 response carries the quote id, send_amount, receive_amount, fx_rate, fees, a cost disclosure and expires_at.

How a quote is priced depends on your tenant's FX model, which Moja Switch sets for you. In the sandbox, a request without fx on CA-TZ is priced from a sandbox rate, as a development convenience. That is never production pricing. Read FX quotes and Moja FX before you build pricing.

#What next

• Sending a payment needs an Idempotency-Key. Read Idempotency first.
• Your tenant must also be enabled for the corridor before a payment is accepted (403 tenant_not_activated until then). Moja Switch does this for you; an entitlement alone is not enablement.
• Learn the error envelope and set up webhooks.
• Exercise outcomes safely with sandbox testing.