Payments

Overview

The Payments toolkit lets your WhatsApp agent collect money during a conversation and lets your team manage the payment lifecycle from the dashboard. It covers checkout, mobile money prompts, payment verification, refunds, payouts, settlements, disputes, and customer receipts.

Use Payments when you want to:

• Request payment after a customer confirms an order or service.
• Send a checkout link or mobile money payment prompt.
• Confirm whether a payment succeeded before continuing.
• Send one WhatsApp receipt message with a PDF receipt attached and a short summary in the caption.
• Review transaction history.
• Issue refunds with proper permission.
• Request payouts to the merchant settlement account where supported.
• Reconcile settlements and disputes.

Access Payments from Dashboard -> Payments. The menu appears after the Payments toolkit is installed and your user has permission to view it.

Dashboard map

The Payments area has these sections:

Visual guide: Settings page

Open Payments -> Settings. The page is grouped into four practical sections.

The save button is at the top-right of the settings page. Logo uploads are staged first; save the settings after uploading so the new logo becomes active.

Setting up Payments

Step 1: Install the toolkit

1. Go to Integrations.
2. Install Payments.
3. Grant Payments to the WhatsApp instances that should collect money.
4. Give finance or admin users permission to manage payment settings.

Installing Payments makes it available to the organization. Granting it to an instance makes the payment tools available to that instance's agent.

Step 2: Complete the business profile

Open Payments -> Settings -> Business Profile.

Fill in:

• Business Name - The public merchant name.
• Contact Email - The email your team uses for billing or payment support.
• Contact Phone - The phone number your team uses for billing or payment support.
• Business Description - A short explanation of what the business sells.

Use the legal or customer-facing business name where possible. It helps customers recognize receipts and helps finance teams reconcile payment records.

Step 3: Upload the receipt logo

In Receipt Logo, upload a PNG, JPG, or WebP image. Use a logo with enough contrast to appear clearly on receipts.

The logo is used for standalone payment receipts. If the receipt belongs to an E-Commerce order, the E-Commerce store logo can override this logo because order receipts belong to the store profile.

Step 4: Add receipt thank-you text

Add a short line such as:

Thank you for shopping with Matuzo Home & Kitchen.

This appears in the receipt footer. Keep it short so it fits cleanly in PDF receipts and WhatsApp previews.

Step 5: Connect the settlement account

In Settlement Details, choose the bank and enter the account number.

When you save:

1. The system sends the bank and account number to the payment network for verification.
2. If the account exists, the verified account name is returned.
3. The merchant payment account becomes connected.
4. Future successful collections can be associated with that merchant settlement profile.

If the account cannot be verified, the settings are saved as a draft. Draft mode is useful while testing fictional merchant details, but live settlement and payout workflows require a verified account.

The account name is resolved by the payment network. KasiLabs does not ask the AI to guess account names, and it does not treat a typed business name as proof that a settlement account exists.

Step 6: Choose the default collection flow

In Payment Preferences, select the default flow:

For M-Pesa STK-style testing, choose Direct Mobile Money. The agent will request payment using the configured mobile money flow when the customer confirms the amount.

How payment verification works

When a customer is asked to pay, the system creates a payment reference. That reference is the source of truth.

The agent should not continue a paid workflow just because the customer says "I have paid" or sends a screenshot. The system waits for confirmation from the payment network and then updates the transaction record.

After confirmation:

1. The transaction status becomes successful.
2. If the payment belongs to an E-Commerce order, the order is marked paid.
3. A PDF receipt is generated.
4. The customer receives one WhatsApp document message: the PDF receipt plus a short text summary as the caption.
5. Fulfillment or service access can continue.

If confirmation does not arrive, the transaction remains pending, failed, or expired depending on the final payment result.

Receipts

Successful payments send one receipt message:

The PDF is the canonical receipt. The caption is only a summary so customers do not receive duplicate receipt messages.

Receipts include:

• Merchant name.
• Receipt number.
• Order or payment reference.
• Paid date and time.
• Payment method.
• Customer details where available.
• Items, services, quantities, unit prices, and totals.
• Discounts, delivery fees, and total paid where applicable.

Product receipts can include product images. Service receipts do not include product images; they show service name, description, duration, and price.

Payments with E-Commerce

When Payments and E-Commerce work together:

1. E-Commerce creates the cart or order.
2. Payments requests and verifies the payment.
3. Successful payment marks the order as paid.
4. The receipt uses E-Commerce store branding when available.
5. The order moves to fulfillment or service handling.

Use Payments -> Settings for standalone payment branding and settlement. Use E-Commerce -> Settings for order receipt branding, delivery rules, service rules, and store profile.

Transactions

Open Payments -> Transactions to review payment attempts.

Each record shows:

• Reference.
• Customer contact.
• Payment flow or channel.
• Status.
• Amount.
• Merchant net amount.
• Creation time.

Common statuses:

Refunds

Refunds should be permission-controlled.

Recommended flow:

1. Customer asks for a refund.
2. Support reviews the order and payment context.
3. Support escalates or creates a refund request.
4. Finance or a manager confirms the amount and reason.
5. A user with refund permission issues the refund.
6. The customer receives an update.

Do not give all support agents refund permission. Most teams should separate customer communication from money movement.

Payouts

Payouts move available funds to a configured destination where supported by your payment setup.

Before requesting payouts:

• Complete Payments -> Settings.
• Verify the settlement account.
• Give payout permission only to finance or owners.
• Confirm your business is ready for live settlement.

Open Payments -> Payouts to request or review payouts. A payout request may require additional confirmation depending on your account setup. If the destination account is not verified, payout requests should not be treated as live-ready.

Settlements

Settlements help finance teams reconcile collected payments against money that has been settled or made available.

Open Payments -> Settlements to review:

• Settlement date.
• Gross amount.
• Fees.
• Effective amount.
• Status.

Use this page for accounting checks, not for customer support conversation alone.

Disputes

Disputes are payment challenges reported through the payment network.

Open Payments -> Disputes to review status and required response. Keep evidence factual and only include details relevant to the dispute.

Permissions

Recommended payment permissions:

See Permissions & RBAC for the full access model.

Tips

Use clear payment reasons

Good examples:

• Order MAT-2026-0510-0041
• Legal consultation - 60 minutes
• Appliance repair deposit

Do not trust screenshots

Screenshots are not payment confirmation. Always check the transaction status.

Keep settlement details accurate

Wrong bank or account details can leave the merchant account in draft mode or block payout readiness.

Separate order and payment ownership

E-Commerce owns fulfillment. Payments owns money status, refunds, settlements, and payouts.

Next steps

• E-Commerce - Sell products and services through WhatsApp
• Permissions & RBAC - Control employee access and sensitive actions
• Integrations - Install and grant toolkits