Environments

• Sandbox - a safe, isolated environment for development and QA.
• Production - live traffic and real money movement.

​

Base URLs

Note: All APIs are served through the Waftpay gateway. Service paths are identical across environments — the only difference is the host. Sandbox is served from dev.waftpay.io and Production from api.waftpay.io. For example, /auth/v1/generate-token is the same path in both; only swap the host.

​

Service examples

• Sandbox: https://dev.waftpay.io/auth/v1/generate-token
• Production: https://api.waftpay.io/auth/v1/generate-token

• Sandbox: https://dev.waftpay.io/payments/v1/payouts
• Production: https://api.waftpay.io/payments/v1/payouts

​

Switching environments

# .env (example)
WAFTPAY_BASE_URL=https://dev.waftpay.io
WAFTPAY_CONSUMER_KEY=...
WAFTPAY_CONSUMER_SECRET=...
WAFTPAY_PUBLIC_KEY_PATH=./keys/sandbox_public.pem
WAFTPAY_PRIVATE_KEY_PATH=./keys/sandbox_private.pem

// config.ts
export const WAFTPAY = {
  baseUrl: process.env.WAFTPAY_BASE_URL ?? "https://dev.waftpay.io",
  consumerKey: process.env.WAFTPAY_CONSUMER_KEY!,
  consumerSecret: process.env.WAFTPAY_CONSUMER_SECRET!,
};

WAFTPAY_BASE_URL=https://api.waftpay.io
# ...and production credentials / keys

Heads up: Paths are the same in both environments. When composing full URLs, use /<service>/v1/... and only change the host — api.waftpay.io for Production, dev.waftpay.io for Sandbox.

​

Quick start: per‑environment calls

​

1) Get an access token

# SANDBOX
curl -X POST \
  https://dev.waftpay.io/auth/v1/generate-token \
  -H 'Content-Type: application/json' \
  -d '{
    "consumer_key":"<sandbox-consumer-key>",
    "consumer_secret":"<sandbox-consumer-secret>"
  }'

# PRODUCTION
curl -X POST \
  https://api.waftpay.io/auth/v1/generate-token \
  -H 'Content-Type: application/json' \
  -d '{
    "consumer_key":"<prod-consumer-key>",
    "consumer_secret":"<prod-consumer-secret>"
  }'

​

2) Create a payout

# SANDBOX
curl --request POST \
  --url https://dev.waftpay.io/payments/v1/payouts \
  --header 'Authorization: Bearer <sandbox-access-token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Custom-Signature: <signature>' \
  --data '{
  "transaction": {
    "reference": "TXN213687756272200",
    "amount": 1000,
    "currency": "KES",
    "description": "Test description",
    "service_code": "MPESAB2C",
    "timestamp": "2025-01-21T12:30:10Z"
  },
  "originator": {
    "msisdn": "254708374149",
    "channel": "USSD",
    "country": "KE"
  },
  "recipient": {
    "reference": "INVJMA02",
    "account": "254708374149"
  },
  "callback_url": "https://staging.example.com/waftpay/callbacks"
}'

# PRODUCTION
curl --request POST \
  --url https://api.waftpay.io/payments/v1/payouts \
  --header 'Authorization: Bearer <prod-access-token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Custom-Signature: <signature>' \
  --data '{
  "transaction": {
    "reference": "TXN213687756272201",
    "amount": 1000,
    "currency": "KES",
    "description": "Live payout",
    "service_code": "MPESAB2C",
    "timestamp": "2025-01-21T12:30:10Z"
  },
  "originator": {
    "msisdn": "2547XXXXXXXX",
    "channel": "USSD",
    "country": "KE"
  },
  "recipient": {
    "reference": "INVLIVE01",
    "account": "2547YYYYYYYY"
  },
  "callback_url": "https://merchant.example.com/waftpay/callbacks"
}'

​

Credentials & keys

• Maintain separate consumer keys/secrets and signing keys per environment.
• Keep private keys server‑side only and rotate regularly.
• Enforce least privilege: ensure the Production client has access only to the services it needs.

See Authentication and Signing Requests for how to generate and rotate RSA‑2048 PEM keys and how to compute X-Custom-Signature.

​

Webhooks

• Use distinct webhook endpoints per environment, e.g.:
  • Sandbox → https://staging.example.com/waftpay/callbacks
  • Production → https://merchant.example.com/waftpay/callbacks
• Endpoints must be HTTPS and return a fast 2xx to acknowledge.
• Verify the webhook signature using the same signing scheme used for requests.

​

Behavioural differences

• Limits & throughput: Sandbox is throttled and may have lower throughput than Production.
• Third‑party integrations: In Sandbox, payouts and collections are simulated and will not move real funds.
• Errors: Error shapes and codes are identical across environments (see Errors).

​

Best practices

• Treat Production credentials and keys as secrets; keep them out of client apps and repos.
• Log the environment, request_id, and extended error code for every call.
• Use idempotency on POSTs and ensure transaction.reference is unique per attempt.
• Run end‑to‑end tests in Sandbox before promoting changes to Production.
• Monitor webhooks separately per environment and alert on delivery failures.

​

See also

• Authentication - obtain a consumer-credentials token: /api-reference/auth/auth-token
• Signing Requests - compute and send X-Custom-Signature: /api-reference/signatures/signature-generate
• Errors - interpret extended error codes: /errors