Skip to main content

Sandbox account setup (App + API keys)

Developers commonly confuse:

  • Sandbox App account provisioning (Developer Portal)
  • Business api_key used by the Payments API (POST /payments/request)
  • Direct Account API access (/account/*)
  • MFA / OTP / “sign into the app first” requirements

This page clarifies what each step is for, and what to do when something fails.

TL;DR​

  • You do not need Account API access to use normal Payments API checkout.
  • Portal-created sandbox app accounts do not grant Account API access to your project.
  • If you call /account/* without approval, you’ll get 403 with PW_ACCOUNT_ACCESS_REQUIRED.
  • For end-to-end sandbox testing (push notifications / payment delivery), the sandbox user must sign into the Sandbox PayWise App at least once.
  • Sandbox App OTP default: 123456.

1) Create sandbox app accounts (Developer Portal)​

Use the Developer Portal to create:

  • a sandbox personal test account (consumer-style testing)
  • a sandbox business test account (receives payments)

Open:

  • https://sandbox-dashboard.paywise.co/sandbox-setup

These accounts are provisioned by PayWise for sandbox testing only and are scoped to your selected developer project.

Important: this is not direct Account API access​

Creating accounts in the portal uses a server-only provisioning key on the backend. It does not change your project’s Account API approval state.

If you try to call /account/* directly using your project’s pw-subscription-key without approval, wrappers returns:

  • HTTP 403
  • errorCode: PW_ACCOUNT_ACCESS_REQUIRED

2) Install + sign into the Sandbox PayWise App​

Install the sandbox APK and sign in using the credentials shown in the portal.

  • Sandbox app install instructions: /getting-started/sandbox-app

Why app sign-in matters​

For sandbox end-to-end testing, push notifications and payment-request delivery may require the sandbox user to have a valid, recently-established app session. Creating the account alone is not always enough.

OTP / MFA expectations (Sandbox)​

  • Default sandbox OTP for Sandbox App in-app prompts: 123456

This 123456 default is for Sandbox App OTP prompts only. It does not apply to PayWise Identity / admin portal MFA (for example authenticator-app TOTP during sign-in).

If you are stuck in MFA:

  • Confirm you’re on sandbox (sandbox-identity.paywise.co, sandbox-dashboard.paywise.co).
  • Confirm your device time is correct (OTP codes can fail if your clock is skewed).
  • If the portal says “account created” but the app can’t sign in, contact PayWise support/admin for an account reset.

3) Where the business api_key comes from (Payments API)​

Payments API uses two keys:

  • pw-subscription-key goes in the request header (all API calls).
  • api_key goes in the JSON body for Payments endpoints like POST /payments/request.

For sandbox business accounts created in the Developer Portal:

  • the business api_key is shown in the portal credentials modal/response
  • it may also be visible/minted in the Sandbox App under Settings → API (where supported)

4) Do you need Account API access?​

You need Account API access only if your integration must call direct Account endpoints such as:

  • POST /account/account_session
  • POST /account/personal_account
  • POST /account/business_account
  • GET /account/transaction_history
  • GET /account/balance

Most Payments API integrations do not need this.

What PW_ACCOUNT_ACCESS_REQUIRED means​

It means your project is not approved for Account API access. It is not related to whether a sandbox app account exists.

Fix:

  • Request Account API approval from PayWise (Access Center / support workflow), then retry.

5) Common issues checklist​

  • Push notification not received: user hasn’t signed into the Sandbox App yet, or is signed into the wrong account/environment.
  • OTP keeps failing: wrong device time, wrong environment, or MFA is locked/stuck.
  • PW_ACCOUNT_ACCESS_REQUIRED: expected unless your project is explicitly approved for Account API.
  • Sandbox vs production mismatch: sandbox api_key does not work in production, and production api_key does not work in sandbox.

For a symptom → cause → fix table (including PW_ACCOUNT_ACCESS_REQUIRED and environment mismatches), see:

  • /getting-started/troubleshooting