feat: Local Payments

[KerollesFathy]

• Added Paymob Payment Gateway
• Added M-PESA Payment Gateway

[maniamartial]

Documentation: Mpesa Express on Frappe Cloud

Overview

The Mpesa Express integration on Frappe Cloud enables seamless payment processing via the Mpesa platform. This guide outlines the configuration process, focusing on the Mpesa Settings doctype, which serves as the foundation for setting up and managing Mpesa payment credentials.

---

Mpesa Settings Doctype

The Mpesa Settings doctype is where you configure and manage the credentials and details necessary for Mpesa integration. These settings are specific to your Mpesa account and are provided by Mpesa after registering on their portal.

Key Fields in Mpesa Settings:

1. Team

   • Indicates the current team or partner responsible for configuring and managing the Mpesa settings.

2. Consumer Key

   • A unique identifier provided by Mpesa to authenticate API requests.

3. Consumer Secret

   • A secret key that pairs with the Consumer Key for secure authentication.

4. Till Number

   • A short code linked to your Mpesa account used for receiving payments.

5. Business Number

   • A number assigned to your business for payment processing, also known as a Paybill number.

6. Online Passkey

   • A key provided by Mpesa for encrypting and securing transactions.

Payment Gateway Doctype

The Payment Gateway doctype is used to configure the integration between Frappe Cloud and external payment providers, like Mpesa. It contains key fields and sections essential for selecting the appropriate configuration, setting up API credentials, and specifying taxes or charges for the integration.

---

Key Fields in Payment Gateway

1. Team

   • Indicates the partner or team currently responsible for the configuration of the gateway.

2. Gateway Setting

   • A dynamic link to the Gateway Controller. Selecting the Gateway Setting doctype allows the Gateway Controller to populate all available Mpesa settings, enabling the partner to choose the correct configuration for their integration.

• URL

  • The direct API endpoint that connects to the user’s site for creating invoices.

• API Key

  • A unique key provided for secure access to the API, used to authenticate requests.

• API Secret

  • A secret key that pairs with the API Key for enhanced security.

Taxes and Charges Section

This section allows partners to specify the tax and fee percentages applicable to transactions processed through the gateway.

• Tax Rate
  • In Kenya, this is commonly set to 16%, reflecting the VAT charged on most transactions. Partners should adjust this value according to their country’s tax requirements.

Team Doctype

New Fields in Team Doctype

1. Tax ID

   • Each partner or team responsible for payments must have a registered Tax ID. This field stores the Tax ID required for compliance and tax purposes.

2. Phone Number

   • This field records the most recent phone number used for processing payments. It ensures that the correct contact number is always available for transactions and verification purposes.

3. Partner Commission

   • It will store partners commission.

Mpesa Request Log

The Mpesa Request Log stores transaction request data after the STK push is made to the customer's phone. It tracks the progress of the transaction, from the initial request to the final status update. The log is crucial for monitoring and updating the transaction's lifecycle and integrates with the Mpesa Payment Record once the transaction is complete.

Key Fields in Mpesa Request Log

1. Service

   • Mpesa Express: Denotes the type of service used for the transaction request.
   • integration_request_service: Specifies the service used to initiate the transaction.

2. Is Remote Request?

   • is_remote_request: Boolean value indicating whether the request is coming from a remote server.

3. Status

   • Tracks the current status of the transaction:
     • Queued: The request is successfully sent to the user's phone for processing.
     • Complete: The transaction is completed by the user.
     • Cancelled: The user canceled the transaction.
     • Failed: The transaction failed due to non-action (e.g., phone turned off or timeout).

4. Request Headers

   • request_headers: Stores any HTTP request headers if provided (null in this case).

5. Request Data

   • data: Contains the payload sent to Mpesa, including transaction details like:
     • amount_with_tax: The total amount with tax.
     • cmd: Command type, such as "press.api.billing.request_for_payment."
     • partner: The partner initiating the request (e.g., "Administrator").
     • phone_number: The phone number of the customer.
     • request_amount: The requested payment amount.
     • sender: The phone number initiating the request (same as phone_number).
     • tax_id: The tax identification number of the business making the request.
     • team: The team handling the transaction.
     • transaction_limit: The maximum allowable amount for the transaction.

6. Response Output

   • output: Stores the response received from Mpesa after the transaction request is processed (null if no response yet).

7. Error

   • error: Holds any error message received during the transaction request (null if no error).

Mpesa Payment Record Doctype

The Mpesa Payment Record doctype logs successful payment transactions processed via Mpesa. This doctype is created automatically upon the completion of a successful transaction, allowing for comprehensive tracking and audit trails within Frappe.

Key Fields in Mpesa Payment Record

1. Team

   • Identifies the team or partner associated with the transaction.

2. Administrator

   • This field shows the administrator managing the transaction details.

3. Transaction Type

   • Specifies the type of Mpesa transaction. Commonly set to Mpesa Express for quick payments.

4. Trans Time

   • The exact timestamp of the transaction in YYYYMMDDHHMMSS format (e.g., 20240916181019).

5. Grand Total (Ksh)

   • The total transaction amount in the default currency, typically Kenyan Shillings (KES), including all charges.

6. Trans Amount (Ksh)

   • The specific amount processed through Mpesa, excluding additional fees or charges.

7. Amount (USD)

   • The transaction amount converted to USD for international reporting purposes.

8. Exchange Rate

   • The exchange rate applied during the transaction, used to convert amounts between KES and USD.

9. Submitted to Frappe

   • A field indicating whether the transaction data has been submitted to the Frappe system.

10. MSISDN

• The phone number (in E.164 format) of the customer initiating the transaction (e.g., 254740743521 for a Kenyan number).

11. Payment Partner

• The partner facilitating the transaction, often set to the Administrator.

12. Posting Date

• The date the transaction was logged in the system (e.g., 13-11-2024).

13. Posting Time

• The time the transaction was logged, typically in HH:MM:SS format.

14. Default Currency

• The default currency for the transaction, usually KES.

15. Balance Transaction

• A unique reference ID for the balance transaction, used for reconciliation (e.g., BT-2024-00129).

16. Local Invoice

• A URL link to the associated sales invoice document in Frappe, allowing for quick access to the original invoice from partners site. (e.g., https://demo.navari.co.ke/api/...).

Payment Partner Transfer Doctype (Under Development)

Frontend

Mpesa Payment Workflow on Billing (Frontend)

On the Billing section of the sidebar, when the user selects Add on Credit Available, the system checks if the partner is located in Kenya. If so, Mpesa becomes visible as a payment option.

Workflow Overview:

1. Select Partner:

   • The user selects the Partner for whom they have previously set up the Mpesa payment configuration.

2. Enter Amount:

   • The user enters the payment amount to be sent via Mpesa.

3. Initiate Payment:

   • The user clicks on Make Payment to Mpesa.
   • This triggers an STK push to the customer's phone for payment processing.

4. Dialog Interface:

   • The payment process is presented in a clean and simple dialog box for the user, ensuring an intuitive experience.

The workflow ensures seamless payment initiation via Mpesa, with a straightforward process for users in Kenya.

Mpesa Invoices Tab Overview

On the Mpesa Invoices tab, users can view all invoices associated with a specific Team (Customer), displaying all transactions that have ever been processed through Mpesa. This provides a comprehensive history of payments made by the team.

Key Features:

1. Invoice Display:

   • Once the Mpesa Invoices tab is selected, the system displays a list of all invoices tied to the selected Team (Customer). This list includes all Mpesa transactions ever completed.

2. Payment History:

   • Each transaction entry will show the invoice details, such as the amount, transaction status, and payment date.

3. Download Option:

   • After a successful payment, the user has the option to download the invoice. This functionality ensures that users can easily access and store proof of payment.

Partner Setup Workflow (Local Payment Setup)

On the left sidebar, just below the Billing section, there is a Partner option. By clicking on it, users are directed to a section where they can configure their payment settings, particularly for Mpesa or other payment gateways.

Key Steps:

1. Select Local Payment Setup:

   • After clicking on Partner in the sidebar, users will go to the Local Payment Setup tab.
   • This tab allows the user to configure payment settings related to Mpesa and other payment gateways.

2. Add Mpesa Settings:

-   On clicking **Add**, a dialog box appears where the user can fill in all the necessary **Mpesa details**, such as:
    -   **Consumer Key**
    -   **Consumer Secret**
    -   **Till Number**
    -   **Business Number**
    -   **Online Passkey**
-   These details are provided by Mpesa when the user has an active account on their platform.

3. Proceed to Payment Gateway Setup:
   

   • Once the Mpesa settings are filled, users proceed to set up the Payment Gateway.
   • The Payment Gateway configuration is dynamically linked to the Mpesa settings already provided.
   • The configuration ensures that the system automatically adapts based on the Mpesa settings, allowing the partner to enable Mpesa or any other payment gateway they wish to use.

4. Partner Payment Payout
   
   On the Local setup, partners can also create transactions from all the available payments they received from clients through their payment gateway, and submit them. Upon submission, it creates a Partner Payment POayout transaction and calculates the commission. Then it goes to the partner site and creates a related purchase invoice with the total net amount after commission.

[KerollesFathy]

🌍 Local Payment Integration: Paymob

📜 Core Doctypes Introduced:

1. 🗂️ Paymob Log:

   • Purpose: Tracks the initial payment intention
   • Fields:
     • 📌 event_type: Event type of the payment (e.g., intention).
     • 🤝 payment_partner: Link to the associated payment partner .
     • 💵 amount and actual_amount: Payment amount in different currencies, with exchange rate handling.
     • 🧩 payload: JSON field to store payload from Paymob's response.

2. 📄 Paymob Callback Log:

   • Purpose: Captures callback responses from Paymob for tracking transaction outcomes.
   • Fields:
     • 🔖 event_type: Type of event triggering the callback.
     • 🤝 payment_partner: Associated payment partner (read-only).
       • 🆔 transaction_id and Order ID: Unique identifiers for the payment transaction that comes from Paymob side.
     • 🧩 payload: JSON field to store raw callback data.

3. ➡️ Payment Partner Transaction:

   • Purpose: Maintains detailed transaction records, ensuring accountability and automated allocation.

   • Fields:

     • 🤝 payment_partner and payment_gateway: Links to the payment partner and gateway used.
     • 👨🏼‍💼team : who buys the credits
     • 💰 amount and actual_amount: Transaction amount, with currency and exchange rate details.
     • 🧩 payment_transaction_details: JSON field storing detailed transaction metadata.

   • On Submit: Allocate the amount to the Team

4. 🏦 Payment Gateway:

   • Purpose: Central configuration for all payment gateway integrations, enabling a flexible and scalable setup.
   • Fields:
     • 💳 gateway: Unique identifier for the payment gateway.
     • 🌐 url, api_key, and api_secret: Core credentials for gateway communication.
     • 💼 team and team_name: Links to the responsible team managing the gateway.
     • 💸 currency: Associated currency for transactions via the gateway.
     • 🧩 gateway_settings and gateway_controller
     • 🎨 integration_logo and ui_configuration_section: Support for branding and UI enhancements.
     • 📊 taxes_and_charges: Option to define applicable taxes and charges (percentage).

5. 🔐 Paymob Settings:

   • Purpose: Centralized configuration for securely managing API credentials and integration settings.
   • Fields:
     • 🔑 Credentials Section:
       • api_key, public_key, hmac, token, and secret_key: Securely store credentials for API communication.
     • 🌐 Payment Config:
       • iframe: IFRAME URL for embedding the Paymob payment page.
       • payment_integration: Integer value for Integration Number.

---

Paymob Workflow Overview:

1. User Initiation:

   • 🧾 Users navigate to the Billing Tab, specify the payment amount (e.g., $10 💵), and select the Paymob Payment Gateway.
   • 📜 Upon submission, the system logs the payment intention and redirects the user to a secure payment page (Paymob IFRAME).

2. Payment Processing:

   • 💳 Users enter payment details in the Paymob IFRAME and proceed with the transaction.
   • 🔁 Upon successful payment, the gateway triggers a callback.

3. Callback Handling and Allocation:

   • 📥 The system captures the callback response, validates the transaction, and records it using the appropriate doctypes:
     • 🗂️ Paymob Log: For logging payment intention and processing updates.
     • 📄 Paymob Callback Log: To track callback responses from Paymob, including transaction metadata.
     • 🔒 Payment Partner Transaction: To finalize the transaction details, including allocation of funds.

4. Gateway Configuration:

   • 🛠️ Paymob Settings: A central location to securely store and manage credentials required for Paymob API integrations.

5. Success Feedback:

   • ✅ Upon successful validation, the user is redirected to a success page confirming the payment.
   • 💼 The allocated funds are associated with the designated team.

---

[NagariaHussain]

Too big PR, maybe get MVP merged as soon as possible and then iterate with smaller PRs (for example, reports etc. can come in later).

@shadrak98 @BreadGenie