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

Provision a sandbox identity and master API key

POST
/sandbox-registrations
Creates a shadow sandbox identity, a dummy password-based auth credential, and a sandbox master API key pair on behalf of a real (live) identity that just registered on the live server. This endpoint is called server-to-server by the live server's own provisioning job immediately after a live identity is created — it is not called directly by end users or client applications.
This endpoint only exists, and only ever runs, on a server configured in sandbox mode (IS_SANDBOX_SERVER). Calling it against a live server fails with a 500 APPLICATION_ERROR.
The created identity is always type: user, status: active (no email verification or welcome email is sent), and is linked back to the caller's live identity via external_reference, which must be unique — attempting to register the same external_reference twice fails with 409 DUPLICATE_RECORD. The generated master API key is always minted in the test environment with wildcard (*) ACL access, and its plaintext secret_key is returned in the response body because sandbox keys have no access to real funds or data.
The entire operation (identity creation, auth credential creation, API key creation) runs inside a single database transaction: if any step fails, all of it is rolled back and no partial sandbox identity is left behind.

Request

Authorization
Body Params application/jsonRequired

Examples

Responses

🟢201
application/json
The sandbox identity, auth credential, and master API key were provisioned successfully.
Bodyapplication/json

🟠400
🟠401
🟠409
🔴500
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/sandbox-registrations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Acme Corp (Sandbox)",
    "sandbox_email": "01hqzr9f3k2m7xcjqd5t8yabcd@sandbox.flutterwave.com",
    "external_reference": "01hqzr2bkpfq8mxjvt3g7lwne"
}'
Response Response Example
201 - Success
{
    "message": "Sandbox registration created successfully",
    "status": "success",
    "data": {
        "identity_id": "01JBTX3F7K2Q8N5R1M9YV4H6WD",
        "sandbox_email": "01hqzr9f3k2m7xcjqd5t8yabcd@sandbox.flutterwave.com",
        "public_key": "pk_test_8f2a1c7d9e4b4f6a8c1d2e3f4a5b6c7d",
        "secret_key": "sk_test_3a4b5c6d7e8f9012345678901234abcd5e6f7a8b9c0d1e2f3a4b5c6d7e8f9012"
    }
}
Modified at 2026-09-30 00:29:30
Previous
Get or create the sandbox identity for the authenticated identity
Next
Exchange the sandbox master API key for a login session
Built with