Payment Instruments

Payment instruments are approved payout or receipt destinations attached to a party. They let users select a verified destination during payment workflows instead of typing phone numbers, bank accounts, or wallet references directly on operational forms.

Open Payments & Settlement -> Setup -> Payment Instruments.

Workspace Reference

Area	What The User Does
Main table	Reviews party, channel, destination label, currency, default status, verification status, active status, and approval status.
New Payment Instrument	Opens the instrument form for a party-owned payout or receipt destination.
Edit	Updates labels, defaults, status, or other editable details according to policy.
Verify	Runs available provider or bank validation where the channel supports it.
Approve	Makes the instrument available for controlled workflows where approval is required.
Deactivate	Stops the destination from being used for new payments while keeping history.

Operating Principle

The party record is the source of truth.

Payment instruments should normally be created from existing party data:

• party phone or contact records for mobile money
• party bank-account records for bank payouts
• party wallet records where wallet identifiers exist
• party details for cash or cheque payout allowance

The instrument is the controlled payment layer on top of those records. It adds channel, currency, verification, approval, default status, and routing context.

Why Instruments Exist

Payment instruments solve three problems:

Problem	How Instruments Help
Users repeatedly type payment details	Users select an approved party destination instead.
Wrong phone or bank account is used	Verification and approval happen before batch execution.
Audit needs a payout snapshot	The instrument keeps the reviewed destination used by the workflow.

The party contact or bank account remains the editable master data. The instrument records that the selected party destination is allowed for a payment channel.

Instrument Creation Flow

1. Click New Payment Instrument.
2. Select the party.
3. Select the payment channel.
4. Select an existing party contact, bank account, wallet reference, or channel-appropriate source.
5. Review the derived details.
6. Complete the instrument label.
7. Run verification where available.
8. Save the instrument.
9. Approve or activate the instrument according to policy.

Users should not create instruments by manually typing a new phone number or bank account if that detail does not exist on the party record. Update the party first, then create the instrument.

Important instrument fields:

Field	Required	Meaning
Party	Yes	Person or organisation that owns the payment destination.
Payment Channel	Yes	Cash, bank, mobile money, wallet, cheque, card, or internal transfer rail.
Currency	Recommended	Currency supported by the destination or workflow.
Source Contact, Bank Account, Wallet, or Cash Allowance	Channel-dependent	Party-owned record used to derive the destination.
Instrument Label	Recommended	Human-readable label users see when selecting the destination.
Default Instrument	No	Marks the preferred destination for that party, channel, and currency.
Verification Status	Required by policy where available	Shows whether provider or bank validation has confirmed the destination.
Active Status	Yes	Controls whether the destination can be selected for new payment workflows.

Channel-Specific Behavior

Channel	Expected Source And Details
Mobile Money	Select a party phone/contact. The system suggests the provider rail from the number prefix and validates the account holder where provider validation is available.
Bank Transfer	Select a party bank account. The instrument inherits account number, account name, bank, branch, and currency from the party bank record.
Cash	Select the party and define that cash payout is allowed. Bank, provider, and account-number fields should not be required unless the business uses a cash pickup reference.
Wallet	Select or resolve the party wallet reference. The wallet and currency must match the intended workflow.
Cheque	Use party/payee details and optional bank or delivery information where the process requires it.
Card	Usually used for inbound receipts or refunds. Store only approved token or masked references where applicable, never raw card numbers.
Internal Transfer	Use the approved internal wallet, bank, or clearing destination configured for the party or organisation.

Mobile Money Verification

For mobile money instruments, the selected party phone should be validated before use where the provider supports account-holder validation.

The verified result should show:

• selected phone number
• provider rail, such as Airtel Money or MTN MoMo
• returned account-holder name
• active or inactive result where supplied
• verification status

If the returned account name does not match the party, users should stop and review the party contact before approving the instrument.

Provider Rail Suggestion

Provider rail should be suggested from configured phone-prefix mappings.

Examples:

• Airtel Money for Airtel-controlled Uganda prefixes.
• MTN MoMo for MTN-controlled Uganda prefixes.

Users should still review the suggestion, especially for ported or exceptional numbers where the provider result may differ from the prefix expectation.

Default Instruments

A party can have a default instrument for a channel. This helps users choose the normal payout destination quickly.

Default does not mean “skip review”. Users should still check:

• party name
• channel
• currency
• destination detail
• provider rail
• verification status

Approval And Status

Common statuses include:

Status	Meaning
Pending Verification	Destination has been captured but not yet verified.
Active	Available for selection where approval rules allow it.
Inactive	Retained for history but not used for new payments.
Approved	Reviewed and available for controlled workflows.
Returned or Rejected	Sent back for correction.

Payment batch lines should normally use only active, approved, verified instruments.

Accounting Note

The payment instrument does not choose the GL account.

The instrument identifies the approved party destination. Accounting is resolved from the payment channel, batch type, posting rule, funding setup, and accounting tags.

For example, a mobile money instrument controls which phone number receives funds, while the accounting setup controls whether the credit side uses tenant wallet, provider float, bank account, cash account, or another configured funding account.

Common Mistakes

Mistake	Better Practice
Typing a phone number directly into an instrument instead of maintaining the party contact.	Update the party contact first, then create the instrument.
Creating duplicate instruments for the same destination.	Use default status and labels instead of duplicates.
Approving an unverified mobile money destination.	Validate the account holder before approval.
Using one instrument across incompatible channels.	Create channel-specific instruments.
Treating instrument label as account-holder proof.	Use provider or bank verification where available.

Related Guides

• Payment Channels
• Payment Batches
• Parties