Universal Payment SDK

Overview

The Universal Payment SDK provides a flexible and localized payment experience for your customers. Instead of integrating multiple payment methods separately, you can use a single endpoint to accept payments via mobile money, bank transfers, cards, and other local payment options. The SDK handles the complexity of different payment gateways and presents customers with their preferred payment method based on their location and available options.

When To Use This

Use the Universal Payment SDK when you want Honeycoin to host the payment experience and present available local payment methods to your customer. This is the best default for checkout flows where you do not want to build separate UI for mobile money, bank transfer, cards, and OPay.

Use a direct collection endpoint instead when you already know the exact payment method and want to fully control the payment UI in your own application.

Happy Path

1. Create a payment session with the amount, charge currency, wallet currency, and your externalReference.
2. Redirect the customer to the returned paymentSdkLink.
3. Customer selects or completes the payment method in the hosted payment interface.
4. Listen for a webhook or query the transaction status.
5. Fulfill the order only after the transaction is successful.

1 - Initialize Payment Session

To initiate a payment collection using the Universal Payment SDK, send a request to the payment SDK endpoint with the required payment information.

Prefill Data Object (Optional)

{
  "amount": 5000,
  "chargeCurrency": "NGN",
  "walletCurrency": "USD",
  "externalReference": "order_9876",
  "customerId": "customer_123",
  "method": "momo",
  "successRedirectUrl": "https://yourapp.com/success",
  "failureRedirectUrl": "https://yourapp.com/failed",
  "cancelRedirectUrl": "https://yourapp.com/cancelled",
  "prefillData": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "+2348012345678"
  }
}

Below is an example of the response:

{
  "success": true,
  "message": "Transaction created successfully",
  "data": {
    "transactionId": "zxcvbnmfdffdffdf",
    "paymentSdkLink": "https://pay.honeycoin.app/sdk/transaction/zxcvbnmfdffdffdf"
  }
}

Note: Use the returned transactionId to track the transaction status. The paymentSdkLink is a unique URL that directs your customer to the payment interface.

2 - Redirect Customer to Payment Interface

Once the payment session is initialised, redirect your customer to the paymentSdkLink provided in the response. This link takes them to a secure Honeycoin-hosted payment interface where they can:

• Select their preferred payment method (mobile money, bank transfer, card, etc. )
• Enter their payment details
• Complete the transaction

The payment interface is:

• Localised - Displays in the customer's local language and currency
• Mobile-optimised - Works seamlessly on all devices
• Secure - Handles sensitive payment data securely
• Method-flexible - Shows only available payment methods for their location

3 - Handle Customer Redirects (Optional)

After the customer completes or cancels the payment, they will be redirected to one of the redirect URLs you specified on the request:

• Success: Customer is redirected to successRedirectUrl after successful payment
• Failure: Customer is redirected to failureRedirectUrl if payment fails
• Cancelled: Customer is redirected to cancelRedirectUrl if they cancel the transaction

Include the transactionId or externalReference as query parameters in your redirect URLs to identify the transaction:

https://yourapp.com/success?transactionId=zxcvbnmfdffdffdf
https://yourapp.com/failed?externalReference=order_9876
https://yourapp.com/cancelled?transactionId=zxcvbnmfdffdffdf

4 - Get Transaction Status

Always verify the payment status before providing value to your customer. Use the get transaction endpoint with either:

• The transactionId from the SDK initialisation response, or
• Your externalReference

Here's an example of transaction verification and response:

Success

{
  "success": true,
  "data": {
    "transactionId": "zxcvbnmfdffdffdf",
    "amount": 5000,
    "type": "deposit",
    "chargeCurrency": "NGN",
    "walletCurrency": "USD",
    "chargeStatus": "successful",
    "status": "SUCCESSFUL",
    "method": "momo",
    "fullTimestamp": "2025-09-06T14:30:44+03:00",
    "externalReference": "order_9876",
    "customerId": "customer_123"
  }
}

{
  "success": true,
  "data": {
    "transactionId": "zxcvbnmfdffdffdf",
    "amount": 5000,
    "type": "deposit",
    "chargeCurrency": "NGN",
    "walletCurrency": "USD",
    "chargeStatus": "failed",
    "status": "FAILED",
    "method": "momo",
    "fullTimestamp": "2025-09-06T14:35:44+03:00",
    "externalReference": "order_9876",
    "customerId": "customer_123"
  }
}

5 - Filter Payment Methods (Optional)

You can optionally restrict the payment methods available to your customer by specifying the top-level method parameter. This is useful when you want to:

• Offer only mobile money payments in certain regions
• Exclude specific payment methods based on your business logic
• Provide a streamlined experience for specific customer segments

Supported method filters:

• momo - Mobile money only
• bank - Bank transfers only
• card - Card payments only
• opay - OPay wallet only (NGN)

Example with method filtering:

{
  "amount": 5000,
  "chargeCurrency": "NGN",
  "walletCurrency": "USD",
  "externalReference": "order_9876",
  "method": "momo"
}

6 - Multi-Currency Transactions

The Universal Payment SDK supports multi-currency transactions, allowing you to charge customers in their local currency while settling funds in your preferred currency.

• chargeCurrency: The currency the customer sees and pays in (e.g. NGN)
• walletCurrency: The currency you receive in your wallet (e.g. USD)

The conversion is handled automatically at the current exchange rate. Example:

{
  "amount": 100000,
  "chargeCurrency": "KES",
  "walletCurrency": "USD",
  "externalReference": "order_5432"
}

In this example, the customer is charged 100,000 KES, and you receive the USD equivalent in your wallet.

Best Practices

• Always verify transaction status before providing value to your customer, even if you receive a webhook notification
• Use redirect URLs to guide customers back to your application after payment
• Store the transactionId and externalReference for reconciliation and support purposes
• Implement proper error handling for failed transactions and cancelled payments
• Use webhooks for real-time updates rather than continuously polling the status endpoint
• Test with different currencies and methods to ensure your integration handles all scenarios
• Include customerId when available to track customer payment history
• Use method filtering to provide a streamlined experience when appropriate