Sandbox environment

Build and test against the sandbox, including deterministic off-ramp outcomes, before you move to production.

Every integration starts in the sandbox. When you register an application in the business portal, it is issued sandbox application credentials by default. The sandbox exposes the same API contract as production, so you can build and test the full flow before requesting production access.

Base URL: https://api.zeam.money/gw/v1

The sandbox uses the same base URL as production. Which environment a request runs in is determined by your application’s registration and role, not by the host. Sandbox and production credentials are separate.

What the sandbox is for

• Authenticating: issuing an access token and calling protected endpoints.
• Building the payment flow end to end: wallets, connectors, quotes, and P2P, swap, and off-ramp payments.
• Exercising deterministic off-ramp outcomes.
• Testing your webhook handling.
• Validating your error handling against the RFC 7807 contract.

Sandbox versus production

• Same base URL. Sandbox and production share https://api.zeam.money/gw/v1; your application’s registration determines the environment, so there is no host to switch.
• Separate credentials. Sandbox and production credentials are distinct and not interchangeable. See Register your application.
• Two specific off-ramp outcomes are simulated. A sender MSISDN ending in 111 or 000 deterministically succeeds or fails without reaching a real payout provider (see below) — this is the only simulation in the sandbox.
• Same contract. Endpoints, request and response shapes, and error formats match production, so your integration code does not change between them.

A sandbox token does not provide test isolation. See Sandbox limitations below before you create records or move funds.

Treat the sandbox as a shared, non-production environment. Do not send real personal data, real customer identifiers, or anything you could not put in a test system.

Off-ramp testing

In the sandbox, off-ramp execution is simulated so you can test both outcomes deterministically. The simulator decides the result from the sender’s MSISDN (mobile number):

• Sender MSISDN ends in 111: the off-ramp succeeds.
• Sender MSISDN ends in 000: the off-ramp fails.

These are the only two guaranteed-simulated outcomes, and only apply in the sandbox. A sender MSISDN ending in anything else is not guaranteed to be simulated at all — it may attempt a real payout through the actual connector. Never rely on any MSISDN ending in production, where the real payout provider always determines the outcome. There is currently no equivalent way to simulate an off-ramp to a bank-account connector — the MSISDN convention only applies to mobile-money-style connectors.

The simulator evaluates the sender MSISDN that the platform resolves for the off-ramp. The gateway’s POST /v1/payments/offramp request does not itself carry a sender MSISDN field.

Off-ramps are asynchronous: a submission returns 202 Accepted with a transactionRecordId, and the simulated outcome arrives afterwards. Poll the transaction or receive webhooks to observe it.

1. Get a quote

   Request a quote for the connector and amount first — POST /v1/payments/offramp executes against a quoteId, it does not create one. Quotes expire roughly two minutes after creation, so request one right before you submit.

   cURL

   curl -sS -X POST https://api.zeam.money/gw/v1/quotes \
     -H "Authorization: Bearer $ZEAM_TOKEN" \
     -H "x-zeam-auth: $ZEAM_APP_SECRET" \
     -H "Content-Type: application/json" \
     -d '{
       "connectorId": "44444444-4444-4444-4444-444444444444",
       "amount": 100,
       "beneficiaryId": "77777777-7777-7777-7777-777777777777"
     }'
   

   200 OK

   {
     "quoteId": "bbbb1111-2222-3333-4444-555566667777",
     "sendAmount": 100,
     "sendCurrency": "USDZ",
     "receiveAmount": 1750.00,
     "receiveCurrency": "ZAR",
     "rate": 17.5,
     "fee": 5,
     "feeCurrency": "USDZ",
     "total": 105,
     "expiresAt": "2026-01-15T10:22:07Z",
     "connectorId": "44444444-4444-4444-4444-444444444444"
   }
   

   Use the returned quoteId in the next step before it expires.

2. Submit the off-ramp

   cURL

   curl -sS -X POST https://api.zeam.money/gw/v1/payments/offramp \
     -H "Authorization: Bearer $ZEAM_TOKEN" \
     -H "x-zeam-auth: $ZEAM_APP_SECRET" \
     -H "Content-Type: application/json" \
     -d '{
       "transactionId": "3d594650-3436-11e5-bf7f-0002a5d5c51b",
       "walletId": "66666666-6666-6666-6666-666666666666",
       "beneficiaryId": "77777777-7777-7777-7777-777777777777",
       "paymentDestinationId": "aaaa1111-2222-3333-4444-555566667777",
       "quoteId": "bbbb1111-2222-3333-4444-555566667777",
       "sendingAssetCode": "USDZ",
       "purpose": "FAMILY_SUPPORT",
       "sourceOfFunds": "SALARY"
     }'
   

   202 Accepted

   {
     "transactionRecordId": "d94b0f8a-6d1e-4a2c-9f3b-2a7c1e5d8b90",
     "intentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "status": "accepted",
     "isIdempotent": false
   }
   
3. Confirm a success (sender MSISDN ends in 111)

   A successful simulation moves the transaction to completed and emits the IntentSuccessful webhook event.

   GET /v1/transactions/{transactionRecordId}

   {
     "transactionRecordId": "d94b0f8a-6d1e-4a2c-9f3b-2a7c1e5d8b90",
     "type": "offramp",
     "status": "completed",
     "sendAmount": 100.00,
     "sendCurrency": "USD",
     "receiveAmount": 1750.00,
     "receiveCurrency": "ZAR",
     "completedAt": "2026-01-15T10:32:07Z"
   }
   
4. Confirm a failure (sender MSISDN ends in 000)

   A failed simulation moves the transaction to failed and emits the IntentFailed webhook event.

   GET /v1/transactions/{transactionRecordId}

   {
     "transactionRecordId": "d94b0f8a-6d1e-4a2c-9f3b-2a7c1e5d8b90",
     "type": "offramp",
     "status": "failed",
     "failureReason": "off-ramp payout failed",
     "errorCode": "RAMP_FAILED"
   }
   

Sandbox limitations

The sandbox is for integration testing, not load testing or production traffic. A sandbox token is a credential and role distinction only — it does not provide test isolation from production:

• Wallets and beneficiaries are real, permanently persisted records — including real on-chain wallet funding — whether created with sandbox or production credentials. There is no synthetic or disposable version, and nothing to reset or discard afterward.
• Beneficiaries created with a sandbox token are not separated from production. They appear in the same list as beneficiaries created with production credentials — there is no per-environment scoping.
• P2P transfers are never simulated, regardless of token type. Sending from a wallet created with sandbox credentials moves real funds, including to a wallet or beneficiary that was created with production credentials.
• Off-ramp simulation only covers the two MSISDN endings above. Any other sender MSISDN may attempt a real payout — see the warning in Off-ramp testing.
• There is no way to simulate an off-ramp to a bank-account connector. The MSISDN convention only applies to mobile-money-style connectors.

Treat any sandbox call that creates a record or moves funds as if it were production, unless it is specifically the MSISDN-based off-ramp simulation described above.

Moving to production

When your integration works end to end in the sandbox, review Moving to production.