API docs by Redocly

HoneePay Merchant API (1.0.0)

Download OpenAPI specification:

HoneePay Merchant API

HoneePay is a social money platform where friends connect, share expenses, and exchange money using simple @usernames. No more awkward bank transfers - just seamless social payments.

This API allows merchants to integrate HoneePay into their applications for accepting payments from HoneePay users. To use this merchant API, you need to have a HoneePay business account and have an API public and secret key.

Authentication

The API uses two types of authentication:

  • Public Key: For initializing payments (less sensitive operations)
  • Secret Key: For secure operations like completing payments and verifying transactions

Payment Flow

  1. Initialize a payment using public or secure key
  2. Get customer details using their HoneePay handle
  3. Complete the payment
  4. Verify the payment status

Initialize Payment with Public Key

Initialize a new payment transaction using your public API key. This endpoint creates a payment transaction that customers can complete using their HoneePay wallet. The public key authentication is suitable for client-side initialization where the secret key should not be exposed.

Use cases:

  • E-commerce checkout flows
  • Service payments
  • Digital product purchases

Next steps: After initialization, you'll need to collect the customer's HoneePay handle and proceed to get their details.

header Parameters
Content-Type
string
Example: application/json
X-API-Key
string
Example: {{public_key}}
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
text/plain
{
    "statusCode": 200,
    "data": {
        "transaction_id": "adb107dd-00e3-4f48-873b-8396e2dfd37e",
        "reference": "MRC_LOJRWJM6Q5E5",
        "amount": 100.5,
        "currency": "NGN",
        "description": "Payment for product order #12345",
        "status": "pending",
        "merchant_name": "Updated Business Name",
        "created_at": "2026-03-17T09:36:35.000000Z",
        "expires_at": "2026-03-17T10:06:35.000000Z",
        "next_step": "customer_details_required",
        "authorization_url": "https://pay.honeepay.com/MRC_LOJRWJM6Q5E5"
    },
    "message": "Transaction initialized successfully. Customer details required for payment."
}

Initialize Payment with Secret Key

Initialize a new payment transaction using your secret API key. This provides enhanced security for payment initialization and is recommended for server-to-server communication. The secret key authentication ensures that only your backend can initiate payments.

Use cases:

  • Server-side payment processing
  • Subscription billing
  • High-value transactions
  • Automated payment systems

Security: Always use this endpoint from your backend server, never from client-side code.

Authorizations:
noauthAuth
header Parameters
Content-Type
string
Example: application/json
X-API-Secret
string
Example: {{secret_key}}
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
text/plain
{
    "statusCode": 200,
    "data": {
        "transaction_id": "7e224e1c-d8bc-46ed-ad85-a6080c5f1fe3",
        "reference": "MRC_SJKOBIZPTIP5",
        "amount": 250.75,
        "currency": "USD",
        "description": "Premium subscription payment",
        "status": "pending",
        "merchant_name": "Updated Business Name",
        "created_at": "2026-03-17T09:38:33.000000Z",
        "expires_at": "2026-03-17T10:38:33.000000Z",
        "next_step": "customer_details_required",
        "authorization_url": "https://pay.honeepay.com/MRC_SJKOBIZPTIP5"
    },
    "message": "Transaction initialized successfully. Customer details required for payment."
}

Get Customer Payment Details

Retrieve customer information and wallet balance for a specific transaction using their HoneePay handle. This endpoint validates the customer's account and checks if they have sufficient funds to complete the payment.

Information returned:

  • Customer profile (name, email, HoneePay handle)
  • Wallet balance and currency
  • Sufficient funds check
  • Next payment step guidance

Payment flow decisions:

  • If has_sufficient_balance: true → Ready for payment
  • If has_sufficient_balance: false → Customer needs to fund wallet

Use cases:

  • Pre-payment validation
  • Customer wallet balance display
  • Payment flow decision making
Authorizations:
noauthAuth
path Parameters
transaction_reference
required
string
Example: MRC_PSQTRAREVQEF
header Parameters
Content-Type
string
Example: application/json
X-API-Key
string
Example: {{public_key}}
X-API-Secret
string
Example: {{secret_key}}
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "customer_honeypay_handle": "mike"
}

Response samples

Content type
text/plain
Example
{
    "statusCode": 200,
    "data": {
        "transaction_id": "adb107dd-00e3-4f48-873b-8396e2dfd37e",
        "reference": "MRC_LOJRWJM6Q5E5",
        "amount": "100.50",
        "currency": "NGN",
        "customer": {
            "honeypay_handle": "mike",
            "user_id": 1,
            "email": "mike@yopmail.com",
            "name": "mike"
        },
        "wallet": {
            "balance": null,
            "currency": "NGN",
            "has_sufficient_balance": false,
            "balance_shortfall": 100.5
        },
        "next_step": "insufficient_funds",
        "message": "Customer needs to fund wallet before payment"
    },
    "message": "Customer details retrieved successfully"
}

Verify Payment Transaction

Verify the status and details of a completed payment transaction using the transaction reference. This endpoint provides comprehensive information about the payment including all metadata, participant details, and balance changes.

Verification details include:

  • Transaction status and timestamps
  • Amount and currency information
  • Customer and merchant details
  • Balance changes for both parties
  • Payment method used
  • Original metadata

Use cases:

  • Order fulfillment confirmation
  • Accounting and reconciliation
  • Customer support inquiries
  • Audit trail generation

Security: Requires secret API key authentication to ensure only authorized merchants can verify transactions.

path Parameters
transaction_reference
required
string
Example: MRC_PSQTRAREVQEF
header Parameters
X-API-Secret
string
Example: {{secret_key}}

Responses

Response samples

Content type
text/plain
{
    "statusCode": 200,
    "data": {
        "transaction_id": "eef8416f-568a-4135-abcb-d7c29d6b533e",
        "reference": "MRC_PSQTRAREVQEF",
        "amount": "500.50",
        "currency": "NGN",
        "description": "Payment for product order #12345",
        "status": "completed",
        "gateway_reference": "HONEYPAY_WALLET_PMWTXLMF",
        "payment_intent_id": null,
        "charges": "0.00",
        "processed_at": "2026-03-17T09:52:20.000000Z",
        "created_at": "2026-03-17T09:51:42.000000Z",
        "updated_at": "2026-03-17T09:52:20.000000Z",
        "metadata": {
            "order_id": "12345",
            "product_name": "Premium Widget",
            "merchant_id": "78025b78-3300-461e-ae7e-3290014c46c0",
            "business_name": "Updated Business Name",
            "redirect_url": "https://yourwebsite.com/payment-success",
            "callback_url": "https://yourwebsite.com/payment-callback",
            "payment_method": "honeepay_wallet",
            "step": "completed",
            "customer_honeypay_handle": "mike",
            "customer_user_id": 1,
            "customer_email": "mike@yopmail.com",
            "customer_name": "mike",
            "amount_paid": "500.50",
            "total_deducted": 500.5,
            "customer_balance_before": 899.5,
            "customer_balance_after": "399.00",
            "merchant_balance_before": 100.5,
            "merchant_balance_after": "601.00"
        },
        "merchant": {
            "merchant_id": "78025b78-3300-461e-ae7e-3290014c46c0",
            "business_name": "Updated Business Name",
            "business_email": "updated@business.com"
        }
    },
    "message": "Payment verification successful"
}

Get Transaction Status

Retrieve the current status of a payment transaction. This is a lightweight endpoint for quickly checking if a payment is pending, completed, or failed without retrieving the full transaction details.

Status information:

  • Current transaction status
  • Payment amount and currency
  • Creation and processing timestamps
  • Brief description
  • Current processing step

Use cases:

  • Real-time status updates
  • Payment progress tracking
  • Quick status checks
  • Dashboard displays

Performance: Use this endpoint for frequent status checks as it returns minimal data compared to the full verification endpoint.

path Parameters
transaction_reference
required
string
Example: MRC_PSQTRAREVQEF
header Parameters
X-API-Secret
string
Example: {{secret_key}}

Responses

Response samples

Content type
text/plain
{
    "statusCode": 200,
    "data": {
        "reference": "MRC_PSQTRAREVQEF",
        "amount": "500.50",
        "currency": "NGN",
        "status": "completed",
        "description": "Payment for product order #12345",
        "step": "completed",
        "created_at": "2026-03-17T09:51:42.000000Z",
        "processed_at": "2026-03-17T09:52:20.000000Z"
    },
    "message": "Transaction status retrieved successfully"
}

List Merchant Transactions

Retrieve a paginated list of all transactions for your merchant account. This endpoint provides comprehensive transaction history with filtering capabilities for accounting, reporting, and reconciliation purposes.

Features:

  • Pagination for large datasets
  • Status filtering (pending, completed, failed)
  • Customer information
  • Payment method details
  • Timestamps and amounts

Use cases:

  • Accounting and bookkeeping
  • Financial reporting
  • Customer payment history
  • Revenue analytics
  • Dispute resolution

Filtering options:

  • Filter by transaction status
  • Control page size and navigation
  • Sort by creation date (newest first)
query Parameters
status
string
Example: status=completed

Filter by transaction status

limit
integer
Example: limit=10

Number of transactions per page

page
integer
Example: page=1

Page number

header Parameters
Accept
string
Example: application/json
X-API-Secret
string
Example: {{secret_key}}

Responses

Response samples

Content type
text/plain
{
    "statusCode": 200,
    "data": {
        "data": [
            {
                "id": "eef8416f-568a-4135-abcb-d7c29d6b533e",
                "reference": "MRC_PSQTRAREVQEF",
                "amount": "500.50",
                "currency": "NGN",
                "description": "Payment for product order #12345",
                "status": "completed",
                "customer_honeypay_handle": "mike",
                "customer_email": "mike@yopmail.com",
                "payment_method": "honeepay_wallet",
                "charges": "0.00",
                "processed_at": "2026-03-17T09:52:20.000000Z",
                "created_at": "2026-03-17T09:51:42.000000Z"
            },
            {
                "id": "adb107dd-00e3-4f48-873b-8396e2dfd37e",
                "reference": "MRC_LOJRWJM6Q5E5",
                "amount": "100.50",
                "currency": "NGN",
                "description": "Payment for product order #12345",
                "status": "completed",
                "customer_honeypay_handle": "mike",
                "customer_email": "mike@yopmail.com",
                "payment_method": "honeepay_wallet",
                "charges": "0.00",
                "processed_at": "2026-03-17T09:49:51.000000Z",
                "created_at": "2026-03-17T09:36:35.000000Z"
            }
        ],
        "pagination": {
            "total": 2,
            "per_page": "10",
            "current_page": "1",
            "last_page": 1
        }
    },
    "message": "Merchant transactions retrieved successfully"
}