UnionPally Billing Module Guide
A Guide to Understanding How UnionPally Charges Your Association for Its Services
What Is the Billing Module?
The Billing Module is the system that tracks and manages what your association owes UnionPally for services consumed — primarily SMS notifications sent on your behalf.
When UnionPally sends SMS messages for your association (for example, bulk announcements or automated transaction alerts), those messages cost money. The Billing Module records every cost, groups them by month, and deducts them from your association's dedicated billing wallet.
This guide explains how those charges work, where you can see them, and what you need to do to keep your billing wallet funded.
Key Concepts
Before diving in, here are the terms used throughout this guide:
| Term | What It Means |
|---|---|
| Billing Profile | Your association's account within the billing system. Created automatically when your association is set up. |
| Billing Wallet | The internal wallet that UnionPally draws from to pay for services used by your association. Also called the unionpally_billing wallet. |
| Collection Wallet | The wallet that holds funds collected from your members via bank transfers. Also called the member_payment_collection wallet. |
| Bill | A monthly summary of all charges your association incurred during one calendar month. |
| Bill Item | A single charge entry inside a Bill — one per notification event that was billed. |
| Prepaid Charge | A charge that is deducted from your billing wallet immediately at the time of the action (e.g., sending a bulk SMS campaign). |
| Postpaid Charge | A charge that is recorded during the month and then settled automatically at the start of the following month. |
| Transfer to Billing | The action of moving funds from your Collection Wallet into your Billing Wallet to cover costs or maintain a positive balance. |
| Billing Debt | A negative balance in your Billing Wallet — meaning more has been spent than what was loaded into the wallet. |
How Charges Work
There are two types of charges the system applies to your association.
Prepaid Charges (Immediate Deduction)
Prepaid charges apply to user-initiated bulk SMS campaigns — situations where an admin or scheduled process triggers a batch of messages to be sent at once.
How it works:
- You or a scheduled task triggers a bulk SMS send.
- The system calculates the total cost of the campaign.
- The system checks your Billing Wallet balance.
- If your balance is sufficient, the cost is deducted from the Billing Wallet immediately, and the messages are sent.
- If your balance is not sufficient, the request is rejected. The SMS is not queued or sent until you top up your Billing Wallet.
A prepaid charge is always recorded as settled immediately. There is no pending state.
Postpaid Charges (Monthly Aggregation)
Postpaid charges apply to transactional SMS messages — individual automated messages the system sends on your behalf, such as payment confirmations, levy reminders, or other system-generated alerts.
Because these messages can happen many times throughout the month in small increments, charging for each one in real time would be inefficient. Instead:
- Every transactional SMS sent during the month is tracked.
- On the 1st day of the following month, the system automatically aggregates all transactional SMS costs for the previous month.
- A single Bill Item is created for the total, and the amount is deducted from your Billing Wallet.
A postpaid charge starts with a pending status until the end-of-month settlement runs. After settlement, it becomes settled. If a technical error occurs during settlement, it is marked failed and will need to be reviewed.
Your Billing Wallet
Your association has a dedicated Billing Wallet that is separate from your Collection Wallet (which holds member levy payments).
Why Two Wallets?
The two wallets serve different purposes and are kept separate:
| Wallet | Purpose |
|---|---|
| Collection Wallet | Holds funds collected from your members. These funds belong to your association. |
| Billing Wallet | Holds funds reserved to pay for UnionPally services. Drawn from to pay charges. |
This separation ensures that member levy payments are never automatically used to cover service costs without a deliberate action from an admin.
Can the Billing Wallet Go Negative?
Yes. For postpaid charges, the Billing Wallet is allowed to go below zero. This is by design — it is a credit arrangement for automated transactional messages that are essential to your association's operations.
When the Billing Wallet has a negative balance (a billing debt), the system automatically restricts payouts from your Collection Wallet to protect your association's ability to settle the debt. See the section on Collection Wallet Restrictions below.
Keeping Your Billing Wallet Funded
You are responsible for keeping your Billing Wallet funded to cover bulk SMS costs. If the balance drops to zero or becomes negative, bulk SMS sends will be blocked until you top it up.
To add funds, use the Transfer to Billing action described later in this guide.
Monthly Bills
Each calendar month, the system generates a Bill for your association that groups all charges for that period.
Bill Status
A Bill's status is derived from the status of its individual Bill Items:
| Status | What It Means |
|---|---|
| Open | At least one Bill Item for the month is still pending (postpaid charges not yet settled). |
| Settled | All Bill Items for the month have been successfully settled. |
| Failed | At least one Bill Item failed to settle and none are still pending. Action may be needed. |
Bill Total
The Total Amount shown on a Bill is the sum of all Bill Items for that month, regardless of whether they have been settled or are still pending. It represents the full cost for that period.
Viewing Your Bills
- Log in to your UnionPally account.
- Go to the Billing section for your association.
- You will see a paginated list of monthly bills, from most recent to oldest.
- Click any Bill to see its individual Bill Items.
Who can view bills: Association exco and admins.
Bill Items
Each Bill is made up of one or more Bill Items. Each Bill Item links one specific notification (an SMS event) to the charge applied for it.
Bill Item Fields
| Field | What It Shows |
|---|---|
| Charge Type | Whether the charge is prepaid or postpaid. |
| Amount | The cost of this specific notification event. |
| Status | pending, settled, or failed. |
| Notification | The specific notification record this charge is linked to. |
| Withdrawal | The wallet withdrawal record that executed the payment (linked once the charge is settled). |
Transferring Funds to the Billing Wallet
When your Billing Wallet balance is low or negative, you can move funds from your Collection Wallet to your Billing Wallet.
When to Do This
- Before running a bulk SMS campaign, to ensure sufficient balance.
- After receiving a notification that your Billing Wallet has gone negative due to postpaid charges.
- Proactively, to maintain a comfortable buffer.
How to Transfer
- Go to the Wallets section.
- Click "Transfer to Billing".
- Enter the amount you want to move.
- Confirm the action.
The funds are moved immediately from your Collection Wallet to your Billing Wallet. A withdrawal record is created on the Collection Wallet and a deposit record is created on the Billing Wallet.
Who can do this: Users with full wallet permissions.
Note: You must have sufficient funds in your Collection Wallet to complete the transfer. The system will reject the transfer if the amount requested is not available.
Collection Wallet Restrictions
To protect your association, the system applies a restriction on payouts from your Collection Wallet when your Billing Wallet has a negative balance (billing debt).
How the Restriction Works
The system calculates your maximum safe payout using this logic:
Billing Debt = max(0, -(Billing Wallet Balance))
Maximum Safe Payout = Collection Wallet Balance - Billing Debt
Example:
Collection Wallet Balance: ₦500,000
Billing Wallet Balance: -₦30,000 (billing debt of ₦30,000)
Billing Debt: ₦30,000
Maximum Safe Payout: ₦500,000 - ₦30,000 = ₦470,000
In this example, if you try to pay out more than ₦470,000 from the Collection Wallet, the system will block the withdrawal with an error message similar to:
"Withdrawal locked: outstanding billing balance must be covered."
To unlock the full Collection Wallet balance, transfer at least ₦30,000 to the Billing Wallet first.
Summary: What Admins Need to Do
| Task | When to Do It | How to Do It |
|---|---|---|
| Check Billing Wallet balance | Regularly, and before sending bulk SMS | Go to Billing section, view wallet |
| Top up Billing Wallet | When balance is low or zero, or to clear a billing debt | Use "Transfer to Billing" |
| View monthly bills | At the end of each month to review service costs | Go to Billing > Bills list |
| View individual bill items | When reviewing a specific charge or investigating an issue | Click a Bill to see its items |
Frequently Asked Questions
Why was my bulk SMS request rejected?
Your Billing Wallet did not have enough balance to cover the cost of the campaign. Transfer funds to your Billing Wallet and try again.
Why is my Collection Wallet showing a lower payout limit than my actual balance?
Your Billing Wallet has a negative balance (billing debt). The system reserves the debt amount to ensure it can be covered. Transfer the outstanding amount to your Billing Wallet to restore your full payout capacity.
What happens if a postpaid charge fails to settle?
The Bill Item is marked as failed. The Bill status will show failed as well. Contact UnionPally support if a settlement failure is not resolved automatically.
Is the Billing Profile something I need to create?
No. A Billing Profile is automatically created for your association at the time your association is set up. You do not need to do anything to enable it.
Can I see which SMS messages each charge is linked to?
Yes. Each Bill Item is linked to a specific Notification record. You can see this connection when viewing the details of a Bill Item.
How often are postpaid charges settled?
Postpaid charges are settled automatically on the 1st of each month, covering all transactional SMS sent during the previous calendar month.