POST https://mybundlepay.com/ng/api/v1/merchant/customers

Merchant Customer Creation

This endpoint allows merchants to create a dedicated merchant wallet/customer using the customer's BVN.

Once successfully created, the customer receives a dedicated virtual account which can be used for collections.

Merchant customers are stored securely and linked to your business.

KEY USAGE POLICY

Important: Always begin your integration using your test_secret_key.

  • Use test_secret_key during development.
  • Use secret_key only in production.
  • Test requests return simulated responses.
  • Live requests create real merchant customers.
  • Each successful live request deducts ₦100 from your API Wallet.
  • Duplicate BVNs are rejected in Live Mode.
Important: Always complete testing before switching to Live.

HEADERS

Authorization * Bearer Token

Pass your secret_key or test_secret_key as the Bearer token.

Content-Type *

application/json

IP WHITELIST

For security reasons, all requests must originate from a whitelisted IP.

The API automatically checks:

  • Remote IP Address

If your IP address has not been added inside your dashboard, the request will be rejected.

BODY PARAMETERS

Customer BVN. Must contain exactly 11 digits.

Customer First Name.

Customer Last Name.

Customer phone number. Example: 08012345678

Only these four fields are required to create a Merchant Customer. 

<?php

$curl = curl_init();

curl_setopt_array($curl, [

CURLOPT_URL => "https://mybundlepay.com/ng/api/v1/merchant/customers",

CURLOPT_RETURNTRANSFER => true,

CURLOPT_CUSTOMREQUEST => "POST",

CURLOPT_POSTFIELDS => json_encode([

"bvn" => "12345678901",

"firstName" => "John",

"lastName" => "Doe",

"phoneNumber" => "08012345678"

]),

CURLOPT_HTTPHEADER => [

"Authorization: Bearer {secret_key}",

"Content-Type: application/json"

]

]);

$response = curl_exec($curl);

curl_close($curl);

echo $response;

?>



const axios = require('axios');

const data = {

bvn: "12345678901",

firstName: "John",

lastName: "Doe",

phoneNumber: "08012345678"

};

axios.post(

"https://mybundlepay.com/ng/api/v1/merchant/customers",

data,

{

headers:{

Authorization:"Bearer {secret_key}",

"Content-Type":"application/json"

}

}

)

.then(response=>{

console.log(response.data);

})

.catch(error=>{

console.log(error.response.data);

});
POST https://mybundlepay.com/ng/api/v1/merchant/customers
Headers 


Authorization: Bearer {secret_key}

Content-Type: application/json
Raw JSON Body 


{

"bvn":"12345678901",

"firstName":"John",

"lastName":"Doe",

"phoneNumber":"08012345678"

}
Tip: Use your test_secret_key while developing. Only switch to your Live Secret Key after your integration has been fully tested.

Sample Request 



{

"bvn":"12345678901",

"firstName":"John",

"lastName":"Doe",

"phoneNumber":"08012345678"

}

Request Validation

  • BVN is mandatory.
  • BVN must contain exactly 11 digits.
  • firstName is mandatory.
  • lastName is mandatory.
  • phoneNumber is mandatory.
  • Authorization header is mandatory.
  • Content-Type must be application/json.
  • Your IP must be whitelisted.
  • Live requests deduct ₦100 from your API Wallet.
  • Duplicate BVNs are rejected in Live mode.

SUCCESS RESPONSES

Test Mode Response

When you send your test_secret_key, the API does not create a real merchant customer and no API balance is deducted. 


{
    "status":"success",
    "message":"Merchant customer created successfully (Sandbox).",
    "data":{
        "accountName":"John Doe",
        "accountNumber":"1000001511",
        "bank":"Rubies MFB",
        "accountBalance":0,
        "charges":0,
        "responseCode":"00",
        "responseMessage":"Completed successfully"
    }
}
Live Mode Response

When using your Live Secret Key, a real merchant customer is created, stored in your account and your API wallet is charged. 


{
    "status":"success",
    "message":"Merchant customer created successfully (Livebox).",
    "data":{
        "accountName":"John Doe",
        "accountNumber":"1000001512",
        "bank":"Rubies MFB",
        "accountBalance":0,
        "charges":100,
        "responseCode":"00",
        "responseMessage":"Completed successfully"
    }
}

Response Fields

Field Description
status Indicates whether the request succeeded or failed.
message Human readable response.
accountName Customer account name.
accountNumber Virtual account number assigned to the customer.
bank Bank issuing the virtual account.
accountBalance Current wallet balance.
charges API fee deducted for creating the customer. Test Mode returns 0. Live Mode returns 100.
responseCode Rubies response code.
responseMessage Official response from Rubies.

Merchant Customer Record

After a successful Live request, MyBundlePay automatically stores the merchant customer information. 


{
    "customer_id":"BUS0000000311",
    "account_name":"John Doe",
    "account_number":"1000001512",
    "bank":"Rubies MFB",
    "account_balance":0,
    "status":"ACTIVE"
}
Note: Merchant Customers created using Test Keys are not saved in the database and do not deduct API balance.

Common Error Responses

Missing Authorization Token

Returned when the Authorization header is not supplied. 


{
    "status":"failed",
    "code":"TOKEN_REQUIRED",
    "message":"Authorization token is required."
}
Invalid Secret Key

Returned when the supplied Secret Key does not belong to any business. 


{
    "status":"failed",
    "code":"INVALID_TOKEN",
    "message":"Invalid secret key provided."
}
IP Not Whitelisted

Returned when the request originates from an IP that has not been whitelisted. 


{
    "status":"failed",
    "code":"IP_NOT_WHITELISTED",
    "message":"Your IP is not authorized for API access.",
    "ip":"102.89.75.216"
}
Blocked IP Address 

{
    "status":"failed",
    "code":"IP_BLOCKED",
    "message":"Your IP has been blocked from API access.",
    "ip":"102.89.75.216"
}
IP Status Not Allowed 

{
    "status":"failed",
    "code":"IP_STATUS_NOT_ALLOWED",
    "message":"Your IP status does not permit API access.",
    "ip":"102.89.75.216"
}
Invalid Secret Key 

{
    "status":"failed",
    "message":"Invalid secret key",
    "data":null
}
Invalid Token Format

Your Secret Key must begin with either:

  • sec-test-
  • sec-live- 

{
    "status":"failed",
    "message":"Invalid token format"
}
Business Not Found 

{
    "status":"failed",
    "message":"Business not found."
}
Wallet Not Found 

{
    "status":"failed",
    "message":"Wallet not found."
}
Insufficient API Balance

Your API Wallet balance must be greater than or equal to ₦100. 


{
    "status":"failed",
    "message":"Insufficient API balance."
}
BVN Already Used

A Merchant Customer has already been created using this BVN. 


{
    "status":"failed",
    "code":"BVN_ALREADY_USED",
    "message":"This BVN has already been used."
}
Validation Errors

Returned when one or more required parameters are missing or invalid. 


{
    "message":"The given data was invalid.",
    "errors":{
        "bvn":[
            "The bvn field is required."
        ],
        "firstName":[
            "The firstName field is required."
        ],
        "lastName":[
            "The lastName field is required."
        ],
        "phoneNumber":[
            "The phoneNumber field is required."
        ]
    }
}
Rubies API Error

Returned when Rubies rejects the request or their service is unavailable. 


{
    "status":"failed",
    "message":"Unable to create merchant customer.",
    "error":"Service temporarily unavailable."
}
Internal Server Error

Returned when an unexpected error occurs. 


{
    "status":"failed",
    "message":"Something went wrong. Please try again later."
}
Developer Note: Handle responses using the code field whenever it is present instead of relying only on the message text. This provides more reliable error handling for production integrations.

API Charges

Environment Charge
Sandbox (Test Secret Key) ₦0.00
Live (Secret Key) ₦100.00 per Merchant Customer

The API charge is deducted automatically from your API Wallet only after a successful customer creation.

Test Environment vs Live Environment

Feature Test Key Live Key
Creates Merchant Customer No Yes
Stores Customer No Yes
Deduct API Charge No Yes
Checks Duplicate BVN No Yes
Returns Sample Response Yes No

Best Practices

  • Always test your integration using your test_secret_key.
  • Store the customer's virtual account number.
  • Always verify your API Wallet balance before switching to Live.
  • Handle every API response using the status and code fields.
  • Never expose your Secret Key inside frontend applications.
  • Always send requests from a whitelisted IP address.
  • Validate BVN before submitting requests from your application.

Security Recommendations

  • Keep your Secret Keys confidential.
  • Do not embed Secret Keys inside JavaScript or mobile applications.
  • Rotate your API keys regularly.
  • Whitelist only trusted server IP addresses.
  • Use HTTPS for every request.
  • Do not log customer BVNs in plaintext.
  • Ensure sensitive customer information is encrypted at rest.
  • Monitor your API Wallet balance frequently.

Go Live Checklist

Rate Limits

To ensure platform stability, excessive requests may be temporarily throttled.

Avoid repeatedly submitting the same BVN.

Implement retry logic using exponential backoff instead of sending continuous requests.

Integration Notes

  • Merchant Customers are created only when using a Live Secret Key.
  • Duplicate BVNs are rejected in Live Mode.
  • Sandbox requests are simulated and are not stored.
  • Every successful Live request deducts ₦100 from the merchant's API Wallet.
  • The returned virtual account can immediately begin receiving payments.
  • Store the returned Customer ID and Account Number for future wallet operations.
Merchant Customer API

This endpoint enables businesses to instantly create dedicated merchant customers with virtual accounts for collections.

For the best experience, complete all testing in Sandbox before switching to Live. Ensure your API Wallet is funded, your server IP is whitelisted, and your application properly handles all API responses.