# Table of Contents - [Quickstart | BluPay Africa Docs](#quickstart-blupay-africa-docs) - [Whitelist IP Address | BluPay Africa Docs](#whitelist-ip-address-blupay-africa-docs) - [Register Webhook | BluPay Africa Docs](#register-webhook-blupay-africa-docs) - [Make a Collection | BluPay Africa Docs](#make-a-collection-blupay-africa-docs) - [Get Wallet Balance | BluPay Africa Docs](#get-wallet-balance-blupay-africa-docs) - [Generate API Key | BluPay Africa Docs](#generate-api-key-blupay-africa-docs) - [Fetch a transaction | BluPay Africa Docs](#fetch-a-transaction-blupay-africa-docs) - [Determine MoMo Processor | BluPay Africa Docs](#determine-momo-processor-blupay-africa-docs) - [Make a Payout | BluPay Africa Docs](#make-a-payout-blupay-africa-docs) - [Webhook Signature Verification | BluPay Africa Docs](#webhook-signature-verification-blupay-africa-docs) - [Quickstart | BluPay Africa Docs](#quickstart-blupay-africa-docs) - [Register Webhook | BluPay Africa Docs](#register-webhook-blupay-africa-docs) --- # Quickstart | BluPay Africa Docs ![](https://blupay-africa.gitbook.io/blupay-africa-docs/~gitbook/image?url=https%3A%2F%2F1743777192-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FeqRTbEqNRFOylw3wtHjj%252Fuploads%252FoyJD0zDgNSl7IwCYqz4u%252Fportal-screenshot.png%3Falt%3Dmedia%26token%3D20fbd7ee-54ff-44b8-9415-a6e3d1051e91&width=768&dpr=3&quality=100&sign=9929fc47&sv=2) [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs#base-urls) Base Urls --------------------------------------------------------------------------------------- Staging -: https://staging-api.blupayafrica.com/api Live -: https://api.blupayafrica.com/api [NextGenerate API Keychevron-right](https://blupay-africa.gitbook.io/blupay-africa-docs/getting-started/generate-api-key) Last updated 6 months ago --- # Whitelist IP Address | BluPay Africa Docs Whitelist your IP address. This IP address is expected to be your server IP address (the origin of requests from your application to the BluPay API). NOTE: This step is not required in the `staging` environment. ![](https://blupay-africa.gitbook.io/blupay-africa-docs/~gitbook/image?url=https%3A%2F%2F1743777192-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FeqRTbEqNRFOylw3wtHjj%252Fuploads%252F150pfQ4x543KSlqPFWKR%252Fportal-screenshot2.png%3Falt%3Dmedia%26token%3D0821f971-4849-4113-b609-77c751ac7cf5&width=768&dpr=3&quality=100&sign=b962d8aa&sv=2) [PreviousGenerate API Keychevron-left](https://blupay-africa.gitbook.io/blupay-africa-docs/getting-started/generate-api-key) [NextRegister Webhookchevron-right](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/register-webhook) Last updated 6 months ago --- # Register Webhook | BluPay Africa Docs It is important to register your webhook. This serves as an outlet to receive transaction status after a transaction has been resolved. ![](https://blupay-africa.gitbook.io/blupay-africa-docs/~gitbook/image?url=https%3A%2F%2F1743777192-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FeqRTbEqNRFOylw3wtHjj%252Fuploads%252F7ckR5aw1JpSQXUayVY0p%252Fportal-screenshot4.png%3Falt%3Dmedia%26token%3Da8cdb14e-b9e5-435a-9314-0aa9410ca860&width=768&dpr=3&quality=100&sign=d2e98e24&sv=2) Ensure this is a POST endpoint and accepts responses from the BluPay API. Here is a sample response you will receive via webhook Copy // Some code "data": { "status": "successful", "statusMessage": {/** object contains response from telco **/} }, "transactionRef": "BP******", "clientTransactionRef": "your-own-transaction-ref", "createdAt": "2025-12-10T14:07:49.839Z", "customer": { "name": "John Doe", "email": "john-doe@nobody.io", "amount": "12029.00", "processor": "mtn", "description": "transaction description", "mobileNumber": "233******" }, "processor": "mtn", "reason": "reason for failure" || null } } [PreviousWhitelist IP Addresschevron-left](https://blupay-africa.gitbook.io/blupay-africa-docs/getting-started/ip-whitelisting) [NextWebhook Signature Verificationchevron-right](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/register-webhook/webhook-signature-verification) Last updated 3 months ago --- # Make a Collection | BluPay Africa Docs #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/make-collection#request-headers) Request Headers Copy "x-api-key": "xxxxxxx", "x-merchant-id": "xxxxxxxxxx", "x-idempotency-key": "xxxxxxxx", "Content-Type": "application/json" circle-info Use the API key that you generated and copied from the dashboard. The idempotency key should be a set of random strings; this should be unique for each collection request. For your Merchant ID, please contact your business relationship manager. circle-info POST - /transactions #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/make-collection#request-body) Request Body Copy { "merchantId": "BLU428039", "amount": "1.20", "customer": { "mobileNumber": "233244304915", "name": "test customer", "email": "testemail@customer.com" }, "processor": "mtn", "currency": "GHS", "clientTransactionRef": "TRXN12345", "description": "this is a description" } circle-info The merchant ID in the request body is different from the merchant ID in the request header. Merchant ID in the request body is sometimes referred to as Merchant Code. circle-info Processor can either be mtn, telecel, or airtel #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/make-collection#request-response) Request Response Copy { "status": "success", "message": "Request successful", "data": { "transactionStatus": "pending", "transactionReference": "BPGL2CMX5I49", "merchantCode": "BLU00004321", "merchantName": "the blu penguin", "customer": { "mobileNumber": "233533841583", "name": "test customer", "email": "testemail@customer.com" }, "amount": "4000.00", "processor": "mtn", "clientTransactionRef": "TRXN12345", } } circle-info To simulate a SUCCESSFUL collection on the staging environment, use "10.00" as the value ("amount") of your test collection [PreviousWebhook Signature Verificationchevron-left](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/register-webhook/webhook-signature-verification) [NextMake a Payoutchevron-right](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/make-payout) Last updated 3 months ago --- # Get Wallet Balance | BluPay Africa Docs #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/get-wallet-balance#request-headers) Request Headers Copy "x-api-key": "xxxxxxx", "x-merchant-id": "xxxxxxxxxx", "Content-Type": "application/json" circle-info Use the API key that you generated and copied from the dashboard. For your Merchant ID, please contact your business relationship manager. circle-info The merchant ID in the request body is different from the merchant ID in the request header. Merchant ID in the request body is sometimes referred to as Merchant Code. circle-info GET - /transactions/wallet/balance #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/get-wallet-balance#response) Response Copy { "status": "success", "message": "Request successful", "data": { "balance": "0.68" } } [PreviousFetch a transactionchevron-left](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/fetch-transaction) [NextDetermine MoMo Processorchevron-right](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/determine-processor) Last updated 5 months ago --- # Generate API Key | BluPay Africa Docs Log in to the merchant dashboard and generate/copy your API key from the `Developer` tab. If you have a developer integrating for your team, please create a developer account for this use case. NOTE: You can `re-issue` your API key if you suspect your current API key has been compromised. ![](https://blupay-africa.gitbook.io/blupay-africa-docs/~gitbook/image?url=https%3A%2F%2F1743777192-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FeqRTbEqNRFOylw3wtHjj%252Fuploads%252F150pfQ4x543KSlqPFWKR%252Fportal-screenshot2.png%3Falt%3Dmedia%26token%3D0821f971-4849-4113-b609-77c751ac7cf5&width=768&dpr=3&quality=100&sign=b962d8aa&sv=2) [PreviousQuickstartchevron-left](https://blupay-africa.gitbook.io/blupay-africa-docs) [NextWhitelist IP Addresschevron-right](https://blupay-africa.gitbook.io/blupay-africa-docs/getting-started/ip-whitelisting) Last updated 6 months ago --- # Fetch a transaction | BluPay Africa Docs #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/fetch-transaction#request-headers) Request Headers Copy "x-api-key": "xxxxxxx", "x-merchant-id": "xxxxxxxxxx", "Content-Type": "application/json" circle-info Use the API key that you generated and copied from the dashboard. For your Merchant ID, please contact your business relationship manager. circle-info The merchant ID in the request body is different from the merchant ID in the request header. Merchant ID in the request body is sometimes referred to as Merchant Code. circle-info GET - /transactions/:transactionReference #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/fetch-transaction#request-response) Request Response Copy { "status": "success", "message": "Request successful", "data": { "statusMessage": "Receiver is Invalid", "transactionStatus": "failed", "transactionReference": "BPGL2CMX5I49", "merchantCode": "BLU00004321", "merchantName": "the blu penguin", "customer": { "name": "customer name", "email": "customer@email.com", "mobileNumber": "233000000000", } "amount": "0.10", "processor": "mtn", "clientTransactionRef": "TRXN12345", } } [PreviousMake a Payoutchevron-left](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/make-payout) [NextGet Wallet Balancechevron-right](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/get-wallet-balance) Last updated 6 months ago --- # Determine MoMo Processor | BluPay Africa Docs #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/determine-processor#request-headers) Request Headers Copy "x-api-key": "xxxxxxx", "x-merchant-id": "xxxxxxxxxx", "Content-Type": "application/json" circle-info Use the API key that you generated and copied from the dashboard. For your Merchant ID, please contact your business relationship manager. circle-info The merchant ID in the request body is different from the merchant ID in the request header. Merchant ID in the request body is sometimes referred to as Merchant Code. circle-info GET - /transactions/determine-processor?mobileNumber=233204131000 #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/determine-processor#response) Response Copy { "status": "success", "message": "Request successful", "data": { "mobileNumber": "233204131000", "processor": "telecel" } } [PreviousGet Wallet Balancechevron-left](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/get-wallet-balance) Last updated 5 months ago --- # Make a Payout | BluPay Africa Docs #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/make-payout#request-headers) Request Headers Copy "x-api-key": "xxxxxxx", "x-merchant-id": "xxxxxxxxxx", "x-idempotency-key": "xxxxxxxx", "Content-Type": "application/json" circle-info Use the API key that you generated and copied from the dashboard. The idempotency key should be a set of random strings; this should be unique for each collection request. For your Merchant ID, please contact your business relationship manager. circle-info POST - /transactions/cashout #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/make-payout#request-body) Request Body Copy { "customers": [\ {\ "amount": "1.00",\ "mobileNumber": "233533841583",\ "name": "firstname lastname",\ "email": "name@email.com",\ "processor": "mtn",\ "clientTransactionRef": "TRXN12345",\ "description": "Payout"\ }\ ], "currency": "GHS" } circle-info Processor can either be mtn, telecel, or airtel #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/make-payout#request-response) Request Response Copy { "status": "success", "message": "Request successful", "data": {} } circle-info To simulate a SUCCESSFUL payout on the staging environment, use "10.00" as the value ("amount") of your test payout [PreviousMake a Collectionchevron-left](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/make-collection) [NextFetch a transactionchevron-right](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/fetch-transaction) Last updated 3 months ago --- # Webhook Signature Verification | BluPay Africa Docs #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/register-webhook/webhook-signature-verification#overview) Overview Blupay signs all webhook payloads with HMAC-SHA512. Use this to verify requests originating from BluPay. #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/register-webhook/webhook-signature-verification#setup) Setup 1. Configure webhook URL via API/dashboard 2. Store the returned `webhookSecret` securely (only shown once) #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/register-webhook/webhook-signature-verification#headers-sent) Headers Sent Copy | Header | Description | |--------|-------------| | `x-webhook-timestamp` | Unix timestamp (seconds) | | `x-webhook-signature` | `sha512={signature}` | #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/register-webhook/webhook-signature-verification#verification-steps) Verification Steps 1. Extract Headers 2. Full node.js Example Copy // 1. Extract Headers const timestamp = req.headers['x-webhook-timestamp']; const signature = req.headers['x-webhook-signature']; // 2. Compute Expected Signature const crypto = require('crypto'); function verifyWebhook(payload, timestamp, signature, secret) { const expected = crypto .createHmac('sha512', secret) .update(JSON.stringify(payload)) .digest('hex'); return signature === `sha512=${expected}`; } // 3. Validate Timestamp (Recommended) const MAX_AGE = 300; // 5 minutes const age = Math.floor(Date.now() / 1000) - parseInt(timestamp); if (age > MAX_AGE) { throw new Error('Webhook timestamp expired'); } #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/register-webhook/webhook-signature-verification#full-example-node.js-express) Full Example (Node.js/Express) Copy app.post('/webhook', express.json(), (req, res) => { const timestamp = req.headers['x-webhook-timestamp']; const signature = req.headers['x-webhook-signature']; const secret = process.env.BLUPAY_WEBHOOK_SECRET; // Validate timestamp const age = Math.floor(Date.now() / 1000) - parseInt(timestamp); if (age > 300) { return res.status(401).json({ error: 'Timestamp expired' }); } // Verify signature const expected = crypto .createHmac('sha512', secret) .update(JSON.stringify(req.body)) .digest('hex'); if (signature !== `sha512=${expected}`) { return res.status(401).json({ error: 'Invalid signature' }); } // Process webhook console.log('Verified webhook:', req.body); res.status(200).json({ received: true }); }); #### [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/register-webhook/webhook-signature-verification#security) Security * Store \`webhookSecret\` in a secure place (e.g env vars), never in code. * Always verify signature before processing a webhook response. * Respond with an immediate 200 response. Process the response asynchronously. * Rotate secret as often as you wish to or when you suspect a compromise. [PreviousRegister Webhookchevron-left](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/register-webhook) [NextMake a Collectionchevron-right](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/make-collection) Last updated 1 month ago --- # Quickstart | BluPay Africa Docs ![](https://blupay-africa.gitbook.io/blupay-africa-docs/~gitbook/image?url=https%3A%2F%2F1743777192-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FeqRTbEqNRFOylw3wtHjj%252Fuploads%252FoyJD0zDgNSl7IwCYqz4u%252Fportal-screenshot.png%3Falt%3Dmedia%26token%3D20fbd7ee-54ff-44b8-9415-a6e3d1051e91&width=768&dpr=3&quality=100&sign=9929fc47&sv=2) [hashtag](https://blupay-africa.gitbook.io/blupay-africa-docs/getting-started#base-urls) Base Urls ------------------------------------------------------------------------------------------------------- Staging -: https://staging-api.blupayafrica.com/api Live -: https://api.blupayafrica.com/api [NextGenerate API Keychevron-right](https://blupay-africa.gitbook.io/blupay-africa-docs/getting-started/generate-api-key) Last updated 6 months ago --- # Register Webhook | BluPay Africa Docs It is important to register your webhook. This serves as an outlet to receive transaction status after a transaction has been resolved. ![](https://blupay-africa.gitbook.io/blupay-africa-docs/~gitbook/image?url=https%3A%2F%2F1743777192-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FeqRTbEqNRFOylw3wtHjj%252Fuploads%252F7ckR5aw1JpSQXUayVY0p%252Fportal-screenshot4.png%3Falt%3Dmedia%26token%3Da8cdb14e-b9e5-435a-9314-0aa9410ca860&width=768&dpr=3&quality=100&sign=d2e98e24&sv=2) Ensure this is a POST endpoint and accepts responses from the BluPay API. Here is a sample response you will receive via webhook Copy // Some code "data": { "status": "successful", "statusMessage": {/** object contains response from telco **/} }, "transactionRef": "BP******", "clientTransactionRef": "your-own-transaction-ref", "createdAt": "2025-12-10T14:07:49.839Z", "customer": { "name": "John Doe", "email": "john-doe@nobody.io", "amount": "12029.00", "processor": "mtn", "description": "transaction description", "mobileNumber": "233******" }, "processor": "mtn", "reason": "reason for failure" || null } } [PreviousWhitelist IP Addresschevron-left](https://blupay-africa.gitbook.io/blupay-africa-docs/getting-started/ip-whitelisting) [NextWebhook Signature Verificationchevron-right](https://blupay-africa.gitbook.io/blupay-africa-docs/basics/register-webhook/webhook-signature-verification) Last updated 3 months ago ---