BluebulbAPI
    API reference/Sub-wallets
    POST

    Create a sub-wallet

    Rolling out
    POST{baseUrl}/api/sub-wallets

    Gives one of your customers their own NGN bank account number. Money paid into it is credited to your NGN balance.

    This endpoint is part of an API release that is still rolling out. Fields and endpoints marked Rolling out may not be available on your account yet.

    Authentication

    Send your API key and a request signature on every call. Requests must also come from an IP address on your allowlist — see Authentication.

    Headers

    x-api-key
    required
    string
    Your API key, <appId>.<secret>. See Authentication.
    X-Signature
    required
    string
    Base64 RSA-SHA256 signature of the request. See Request signing.
    X-Signature-Timestamp
    required
    string
    Unix time in milliseconds used in the signature. Must be within 5 minutes of Orbita's clock.
    Content-Type
    required
    string
    application/json, or multipart/form-data when the endpoint accepts a file.

    Body parameters

    label
    required
    string
    Your name for this customer. Used as the account name payers see.
    customerReference
    optional
    string
    Your own ID for this customer. Must be unique across your sub-wallets.
    bvn
    required
    string
    The customer's 11-digit BVN. Orbita verifies it and stores it encrypted; it's never returned.
    rcNumber
    required
    string
    The customer's CAC registration (RC) number.
    phoneNumber
    required
    string
    The customer's Nigerian mobile number, e.g. 08031234567. +234 and 234 prefixes are accepted.
    address
    required
    string
    The customer's street address.
    city
    required
    string
    The customer's city.

    Behaviour

    A sub-wallet has no balance of its own. Completed payments into it are credited to your NGN balance, so you can tell which customer paid you by the account they paid into.

    Orbita verifies the BVN and opens the account with a banking partner before responding, so the account number is in the response. The sub-wallet is normally active straight away; if it's pending, check it again with Refresh a sub-wallet's status.

    There's no idempotency key. To retry safely, send a customerReference: a second request with the same reference is rejected with 400, so a retry can't open a second account. If you get that error, find the sub-wallet with List sub-wallets and check its details match before treating the retry as successful.

    Each business can hold a limited number of sub-wallets (100 unless your limit has been changed). Deactivated sub-wallets count towards it.

    Response

    data is the new sub-wallet. Every response is wrapped in the standard envelope.

    id
    string (uuid)
    Sub-wallet ID.
    accountNumber
    string
    Bank account number your customer pays into.
    accountName
    string
    Account name payers see, taken from the label you sent.
    bankName
    string
    Bank the account is held at.
    bankCode
    string
    Bank code of that bank.
    currency
    string
    Always ngn.
    status
    string
    pending, active, inactive or deactivated. Only active sub-wallets credit payments. See Statuses.
    customerReference
    string | null
    Your reference for this customer, or null if you didn't send one.
    createdAt
    string (datetime)
    When the sub-wallet was created.

    Errors

    Errors specific to this endpoint:

    400
    Validation failed
    A field is missing or invalid. data.errors lists each problem.
    400
    You have reached the maximum of 100 sub-wallets for this business
    You already hold as many sub-wallets as your limit allows (message names the limit).
    400
    A sub-wallet with customer reference "CUST-1042" already exists
    customerReference is already used by one of your sub-wallets.
    400
    Could not verify the BVN provided. Please check the number and try again.
    The BVN couldn't be verified.
    400
    We couldn't provision an account number right now. Nothing was created and you weren't charged, please try again in a moment.
    The banking partner couldn't open the account — including when phoneNumber isn't a valid Nigerian mobile number.

    Plus the errors every endpoint can return — authentication, signing, rate limiting and server errors. See Responses & errors.