Orientation

Sandbox & credentials

Once onboarding is done, your Waffy account manager sends you everything you need to make the first API call. This page covers what's in that package and how sandbox differs from production.

What you receive

Sandbox access — an isolated environment with its own users and contracts. Nothing in sandbox touches real money.
Two credential pairs — one for each OAuth grant type:
- client_id + client_password → used on the client_credentials grant to obtain an app_token (for user sign-up and linking).
- admin_email + admin_password → used on the password grant to obtain a user_token (for contracts, settlement, balance, withdrawals).
Two grants, two scopes: app_token is your org's machine identity — used for system-level calls like registering a new user. user_token is your admin account's identity — used for anything that touches contracts or moves money.
A webhook signing secret — used to HMAC-verify inbound webhooks so you can trust the payload came from Waffy.
A pre-configured payment-method set — the subset of methods enabled on your org at onboarding (Mada, Visa, Mastercard, Apple Pay, STC Pay, Tabby, Tamara, Neo, manual bank transfer). The hosted checkout displays only the ones that are on for you.

There's a third token — customer_token

The two credential pairs above give you app_token and user_token. There is also a customer_token — obtained at payment time using each payer's own credentials. You do not receive it at onboarding, and you don't manage it yourself: Waffy's hosted checkout acquires it automatically when the buyer initiates payment.

If you don't have these yet, you're not onboarded yet — reach out to your Waffy account manager to get started.

Environments

Aspect	Sandbox	Staging	Production
Base API URL	`dev-api.waffyapp.com`	`stg-api.waffyapp.com`	`api.waffyapp.com`
Auth URL	`dev-auth.waffyapp.com`	`stg-auth.waffyapp.com`	`auth.waffyapp.com`
Webhook URL	Configured by Waffy at provisioning. Contact your account manager to change.	Same mechanism.	Confirmed with Waffy before go-live.
Payments	Simulated.	Simulated or real.	Real. Real money moves.
Webhooks	Fire on every state change, same payload shape.	Same.	Same.
Approval required	No.	No.	Yes — compliance review + Waffy's readiness checklist.

Use the same code across all environments

The only thing that changes between environments is the base URLs and the credential set. Your request shapes, response schemas, and webhook payloads are identical. Gate environments via WAFFY_BASE_URL / WAFFY_AUTH_URL.

Org configuration