Merchant API Documentation (BluPay)
Overview
The Merchant API allows registered merchants to log in, retrieve an API key, request
payment, make payments and re-query transaction statuses and fetch transactions. The
API uses standard HTTP methods and responses are provided in JSON format.
Base URL
Staging: https://staging-api.blupayafrica.com/api
Live: https://api.blupayafrica.com/api
Authentication
● Merchants must log in using their email and password to retrieve their API key.
● API key and merchant ID are required for creating and querying transactions.
● Each API key is unique and can only be retrieved once per merchant.
Endpoints
1. Login
● Description: This endpoint allows registered merchants to log in using their email
and password.
POST /auth/login/partner-bank-name
NOTE: Replace partner-bank-name with your partner bank name, e.g blupenguin
Request Headers:
Content-Type: application/json
Request Body:
{
"email": "merchant@example.com",
"password": "yourpassword",
“userType”: “merchant” NOTE: User type is always merchant
}
Response:
Success (200 OK)
{
"message": "Login successful",
“data”: {
"token": "jwt_token_here"
},
}
2. Fetch API Key
● Description: Merchants can use this endpoint to retrieve their API key. This can
only be done once.
GET /merchants/apikey/issue
NOTE: Merchant API key can only be retrieved once!
Request Headers:
Authorization: Bearer {jwt_token}
Response:
Success (200 OK):
{
"apiKey": "your_unique_api_key"
}
3. Register Webhook
● Description: Merchants can use this endpoint to register a webhook. This
webhook will receive updated transaction status after a transaction has been
performed.
PATCH /merchants/webhook/register
NOTE: Merchant webhook should be registered before any transaction is performed!
Request Headers:
Authorization: Bearer {jwt_token}
Request Body:
{
"webhookUrl": "https://your-webhook-url",
}
Response:
Success (201 CREATED)
4. Create Transaction
● Description: Allows merchants to create a new transaction.
● Endpoint:
POST /transactions
Request Headers:
X-API-KEY: {api_key}
X-MERCHANT-ID: {merchant_id} - the merchant_id here is the merchant uuid
X-IDEMPOTENCY-KEY: {a unique identifier for each transaction}
Content-Type: application/json
Request Body:
{
"merchantId": "BLU428039",
"amount": "1.20",
"customer": {
"mobileNumber": "233244304915",
"name": "test customer",
"email": "testemail@customer.com"
},
"processor": "mtn",
"currency": "GHS",
"description": "this is a description"
}
NOTE:
The MerchantId in the request body above is your merchant code. E.g BP000001
Processor can either be mtn, telecel or airteltigo
Currency is GHS
Response:
Success (201 CREATED)
{
"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"
}
}
5. Fetch Transaction
● Description: Allows merchants to fetch transaction status.
● Endpoint:
GET /transactions/:transactionRef
Request Headers:
X-API-KEY: {api_key}
X-MERCHANT-ID: {merchant_id}
Content-Type: application/json
Response:
Success (200 OK)
{
"status": "success",
"message": "Request successful",
"data": {
"transactionStatus": "pending",
"transactionReference": "BPGL2CMX5I49",
}
}
6. Merchant Cashout
● Description: Allows merchants to send money to a momo wallet.
POST /transactions/cashout
Request Headers:
X-API-KEY: {api_key}
X-MERCHANT-ID: {merchant_id}
X-IDEMPOTENCY-KEY: {a unique identifier for each transaction}
Content-Type: application/json
Request Body:
{
"customers": [
{
"amount": "1.00",
"mobileNumber": "233533841583",
"name": "firstname lastname",
"email": "name@email.com",
"processor": "mtn",
"description": "Payout"
}
],
"currency": "GHS"
}
NOTE:
The Processor can either be mtn, vodafone or airteltigo
Currency is GHS
Response
● Success (200 OK)
{"status":"success","message":"Request successful","data":{"registeredTranx":[{}]}}
Error Handling
Common HTTP response codes used by the API:
● 200 OK: The request was successful.
● 201 Created: The transaction was successfully created.
● 400 Bad Request: The request was invalid.
● 401 Unauthorized: The user needs to log in or the credentials are invalid.
● 403 Forbidden: The merchant is not allowed to retrieve the API key again.
● 404 Not Found: The resource (e.g., transaction) was not found.
Security
● All API calls must include a valid API key and merchant ID for authentication.
● The API key is confidential and should be securely stored by the merchant.
For more information or support, please contact our API team at
[tech@theblupenguin.com]
