Getting Started

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.

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",  
  "prefillData": {  
    "successRedirectUrl": "<https://yourapp.com/success">,  
    "failureRedirectUrl": "<https://yourapp.com/failed">,  
    "cancelRedirectUrl": "<https://yourapp.com/cancelled">,  
    "method": "momo"  
  }  
}

Below is an example of the response:

{  
  "success": true,  
  "message": "Transaction created successfully",  
  "data": {  
    "transactionId": "zxcvbnmfdffdffdf",  
    "paymentSdkLink": "https://pay.wearecashless.com/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 Cashless-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 URLs you specified in the prefillData object:

• 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 method parameter in the prefillData object. 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",  
  "prefillData": {  
    "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