1. Sandbox
BNW CORE SERVICE
  • Card Vaulting
    • Create a card vault session
      POST
  • Fee Lookups
    • Compute fees for a transaction
      POST
  • Intent Action Status Lookups
    • Look up the status of an intent action
      GET
  • Payment Intents
    • Create a payment intent
      POST
    • Cancel a payment intent
      PATCH
    • List payment intents
      GET
    • Retrieve a payment intent
      GET
  • Intent Actions
    • Create an intent action
      POST
    • Advance an intent action to the next step
      PATCH
    • Retrieve the authentication session for a pending redirect action
      GET
  • Accounts
    • Create a new account
      POST
    • List accounts
      GET
    • Close an account
      DELETE
    • Update an account
      PATCH
    • Retrieve an account
      GET
    • Retrieve an account's daily payout limit status
      GET
  • API Keys
    • Create an API key
      POST
    • List API keys
      GET
    • Update an API key
      PATCH
    • Retrieve an API key
      GET
    • Revoke an API key
      DELETE
    • Rotate an API key's secret
      POST
  • App Setting Values
    • Delete an app setting value
    • Retrieve an app setting value
    • List app setting values
    • Create or update an app setting value
  • Entities
    • Create an entity
    • List entities
    • Close an entity
    • Update an entity
    • Retrieve an entity
    • Set the selected entity
    • Retrieve public metadata for the authenticated entity
    • Create an entity sandbox session
    • Retrieve one of your entities, including your membership
    • List my entities
  • Counterparties
    • Create a counterparty
    • List counterparties
    • Update a counterparty
    • Retrieve a counterparty
  • Maker Checker Approver Groups
    • Create a maker-checker approver group
    • List maker-checker approver groups
    • Deactivate a maker-checker approver group
    • Update a maker-checker approver group
    • Retrieve a maker-checker approver group
  • Bulk Payout Intent Actions
    • Create bulk payout intent actions
    • Retrieve a bulk payout intent action batch
    • Preview bulk payout intent actions
  • Payout Intent Action Retries
    • Retry a failed payout intent action
  • Payout Intent Actions
    • Create a payout intent action
    • List payout intent actions
    • Retrieve a payout intent action
  • Payout Intents
    • Create a payout intent
    • List payout intents
    • Retrieve a payout intent
    • Edit a payout intent
    • Cancel a payout intent's active schedule
    • Edit a payout intent's active schedule
    • Cancel a payout intent
  • Virtual Cards
    • Create a virtual card
    • List virtual cards
    • Update a virtual card
    • Retrieve a virtual card
  • Maker Checker Action Decisions
    • Record a decision on a maker-checker action
  • Maker Checker Actions
    • Retrieve a maker-checker action's status
    • List maker-checker actions
    • Withdraw a maker-checker action
  • Payment Pages
    • Create a payment page
    • List payment pages
    • Delete a payment page
    • Edit a payment page
    • Retrieve a payment page
    • Retrieve a published payment page by slug
  • Invoices
    • Create an invoice
    • List invoices
    • Retrieve an invoice
    • Edit an invoice
    • Retrieve an invoice as a PDF
    • Download a public invoice as a PDF
    • Retrieve a public invoice by invoice number
    • Send a reminder for an invoice
    • Send or resend an invoice
  • Entity Data
    • Retrieve the data submission checklist for an entity
    • Submit entity data for KYC requirements
    • List entity data
    • Review and decide on entity data submission
  • Unified Verifs
    • Proxy a DELETE request to the Verification API
    • Proxy a GET request to the Verification API
    • Proxy a PATCH request to the Verification API
    • Forward a POST request to the Verification API
  • Identity Session
    • List identity sessions
    • Complete the MFA step of a pending login session
    • Request a login MFA challenge or one-time-passcode
  • Identity Sessions
    • Terminate all active sessions for an identity
    • Terminate an identity session
  • Entity Sandboxes
    • Create an additional named entity sandbox
    • Delete an entity sandbox
    • Rename an entity sandbox
  • Identity Mfa
    • Passkeys
    • Enroll a new MFA method for the authenticated identity
    • List MFA methods for the authenticated identity
    • Retrieve an identity MFA method
    • Advance or transition the state of an existing MFA method
  • Auth
    • Log in with email and password
    • Register a new identity
    • Request an email verification link
    • Verify an email address
    • Request a password reset
    • Complete a password reset with a one-time token
    • Change the authenticated identity's password
    • Confirm a pending email address change
    • Request a change of the authenticated identity's email address
    • Resend an identity-confirmation email
    • Confirm a phone number change for the current identity
    • Request a phone number change for the current identity
  • Virtual Card Actions
    • Perform an action on a virtual card
  • ACLs
    • List all ACL definitions
  • Account Transfers
    • Create an account transfer
    • List account transfers
    • Retrieve an account transfer
  • ACL Roles
    • List all ACL roles
  • Counterparty Instruments
    • Add a bank account to a counterparty
    • List counterparty instruments
    • Remove a counterparty's bank account
  • Currency Conversion Quotes
    • Create a currency conversion quote
  • Entity Access
    • Change a team member's role on an entity
    • Remove a member's access to an entity
    • List an entity's team members
  • Entity Access Invites
    • Accept an entity access invitation
    • Invite a new member to an entity
    • List entity access invites
    • Revoke an entity access invite
  • Entity Ownership Transfers
    • Transfer ownership of an entity
  • Identity
    • Update the authenticated identity's name
    • Retrieve the authenticated identity
  • Money Action Confirmations
    • Confirm a money-moving action with PIN (and, where required, an authenticator code)
  • Payout Intent Action Returns
    • Record a payout intent action as returned
  • Payout Intent Action Status Logs
    • List a payout intent action's status history
  • Payout Intent Schedule Actions
    • Apply an action to a payout intent's schedule
  • Sandbox
    • Credit test money into an entity's sandbox wallet
      POST
    • Reset a shadow entity's sandbox
      POST
    • Get or create the sandbox identity for the authenticated identity
      POST
    • Provision a sandbox identity and master API key
      POST
    • Exchange the sandbox master API key for a login session
      POST
    • Fund an entity's test wallet with sandbox test money
      POST
  • Transactions
    • Retrieve a transaction
    • List transactions
  • Virtual Card Activity
    • List a virtual card's activity
  • Virtual Card Sessions
    • Create a virtual card viewing session
  • Virtual Card Topups
    • Top up a virtual card
  • Virtual Card Transaction Callbacks
    • Handle an inbound virtual card transaction callback
  • Virtual Card Withdrawals
    • Withdraw funds from a virtual card
  • Schemas
    • ErrorResponse
    • SuccessResponse
    • AccountBalance
    • Account
  1. Sandbox

Get or create the sandbox identity for the authenticated identity

POST
/identity-sandboxes
Ensures the currently authenticated identity has a linked sandbox identity and master sandbox API key pair, creating them if they do not already exist.
Under normal operation, sandbox identities are provisioned automatically in the background when a live identity is created. This endpoint exists as a self-serve backfill for identities that existed before sandbox mode was enabled, or whose automatic provisioning job never ran.
The target identity is always the caller's own identity, taken from the authenticated bearer token (identity_id) — this endpoint accepts no request body and cannot be used to provision a sandbox for another identity.
The operation is idempotent: if a sandbox identity already exists for the caller, its existing credentials are returned unchanged and no new sandbox identity or keys are created. Otherwise, a new sandbox identity is registered on the sandbox server (with a generated sandbox_email) and a new sandbox master API key pair is generated and persisted. In both cases the response is 201 Created and has the identical shape.
The returned secret_key is a sandbox (test-mode) secret key. It is shown in plaintext here because it is a test credential with no access to live funds or data, but it should still be stored securely by the caller, as it authenticates requests to the sandbox server.

Request

Authorization
JWT Bearer
Add the parameter
Authorization
to Headers
Example:
Authorization: ********************
or

Responses

🟢201
application/json
The sandbox identity was found (already provisioned) or newly provisioned, and its credentials are returned.
Bodyapplication/json

🟠401
🟠404
🔴500
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST '/identity-sandboxes' \
--header 'Authorization: Bearer <token>'
Response Response Example
201 - Success
{
    "message": "Identity sandbox retrieved successfully",
    "status": "success",
    "data": {
        "identity_id": "01HQZR2BKPFQ8MXJVT3G7LWNE",
        "sandbox_email": "01HQZR9F3K2M7XCJQD5T8YABCD@sandbox.flutterwave.com",
        "public_key": "FLWSANDPUBK_TEST-8f2a1c7d9e4b4f6a8c1d2e3f4a5b6c7d-X",
        "secret_key": "FLWSANDSECK_TEST-3a4b5c6d7e8f9012345678901234abcd-X"
    }
}
Modified at 2026-09-30 00:29:30
Previous
Reset a shadow entity's sandbox
Next
Provision a sandbox identity and master API key
Built with