# mymi14s/frappe_paystack architecture

> Architecture diagram of the GitHub repository mymi14s/frappe_paystack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mymi14s/frappe_paystack
- Repository: https://github.com/mymi14s/frappe_paystack

## Overview

Frappe Paystack adds Paystack collection and payout bookkeeping to Frappe/ERPNext. The main workflow creates a payment log and checkout link, accepts a Paystack charge, then records the capture as a Payment Entry; webhook handling also supports refunds and settlement payouts. Separate branches cover POS, saved cards, subscriptions, customer self-service, reconciliation, and reporting. Edges follow README statements and visible source references; several feature implementations are unsampled, so their internals and unverified links are omitted.

Main entry points: [`frappe_paystack/api.py`](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/api.py) (Payment and webhook API), [`frappe_paystack/public/js/paystack_actions.bundle.js`](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/public/js/paystack_actions.bundle.js) (Desk payment actions), [`frappe_paystack/utils/payment_request.py`](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/payment_request.py) (Payment Request), [`frappe_paystack/frappe_paystack/doctype/paystack_payment_log/paystack_payment_log.py`](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/doctype/paystack_payment_log/paystack_payment_log.py) (Payment Log and booking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Payment collection"]
  node_gateway["Gateway settings"]
  node_desk["Desk payment actions"]
  node_pos["POS payment flow<br/>[pos_payment.py]"]
  node_webshop["Webshop checkout"]
  node_payment_request["Payment Request<br/>[payment_request.py]"]
  node_payment_log[("Payment Log and booking")]
  node_checkout["Checkout page"]
  node_checkout_route["Checkout route<br/>[index.py]"]
  node_api["Payment and webhook API<br/>[api.py]"]
  node_qr["Payment QR codes<br/>[qr.py]"]
end

subgraph group_operations["Payment operations"]
  node_saved_cards[("Saved authorizations")]
  node_refund[("Refund processing")]
  node_subscription["Subscription collection<br/>[subscription.py]"]
  node_portal["Customer payment portal<br/>[portal.py]"]
  node_portal_route["Portal route<br/>[index.py]"]
end

subgraph group_finance["Finance and reconciliation"]
  node_settlement["Payout settlement<br/>[settlement.py]"]
  node_sweep["Payment retry sweep<br/>[sweep.py]"]
  node_reconcile["Payment reconciliation<br/>[reconciliation.py]"]
  node_reconcile_api["Reconciliation API"]
  node_reconcile_page["Reconciliation page"]
end

subgraph group_insights["Reports and monitoring"]
  node_activity["Activity report"]
  node_other_reports["Payment and settlement reports"]
end

node_customer(("Customer"))
node_staff(("Desk and POS staff"))
node_paystack["Paystack"]

node_staff -->|"starts payment"| node_desk
node_desk -->|"requests payment"| node_payment_request
node_desk -->|"creates link"| node_api
node_desk -->|"shows QR"| node_qr
node_payment_request -->|"creates log"| node_payment_log
node_pos -->|"initializes charge"| node_api
node_webshop -->|"routes checkout"| node_payment_request
node_api -->|"records capture"| node_payment_log
node_api -->|"initializes transaction"| node_paystack
node_paystack -->|"sends webhook"| node_api
node_api -->|"sets callback"| node_checkout_route
node_customer -->|"pays"| node_checkout
node_checkout -->|"starts checkout"| node_api
node_checkout_route -->|"serves page"| node_checkout
node_api -->|"stores authorization"| node_saved_cards
node_desk -->|"charges saved card"| node_saved_cards
node_api -->|"processes refunds"| node_refund
node_api -->|"handles payout event"| node_settlement
node_subscription -->|"collects invoices"| node_payment_request
node_customer -->|"opens payments"| node_portal_route
node_portal_route -->|"loads payment data"| node_portal
node_payment_log -->|"retries capture"| node_sweep
node_reconcile_api -->|"runs checks"| node_reconcile
node_reconcile_page -.->|"requests reconciliation"| node_reconcile_api
node_staff -->|"reviews results"| node_reconcile_page
node_staff -->|"reviews activity"| node_activity
node_staff -->|"runs reports"| node_other_reports
node_gateway -.->|"provides settings"| node_api

click node_gateway "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/doctype/paystack_gateway_setting/paystack_gateway_setting.py"
click node_desk "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/public/js/paystack_actions.bundle.js"
click node_pos "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/pos_payment.py"
click node_webshop "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/public/js/paystack_cart_guard.bundle.js"
click node_payment_request "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/payment_request.py"
click node_payment_log "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/doctype/paystack_payment_log/paystack_payment_log.py"
click node_checkout "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/public/js/paystack_checkout.js"
click node_checkout_route "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/www/paystack-checkout/index.py"
click node_api "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/api.py"
click node_qr "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/qr.py"
click node_saved_cards "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/doctype/paystack_customer_authorization/paystack_customer_authorization.py"
click node_refund "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/doctype/paystack_refund_log/paystack_refund_log.py"
click node_subscription "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/subscription.py"
click node_portal "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/portal.py"
click node_portal_route "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/www/my-payments/index.py"
click node_settlement "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/settlement.py"
click node_sweep "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/sweep.py"
click node_reconcile "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/reconciliation.py"
click node_reconcile_api "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/reconciliation_api.py"
click node_reconcile_page "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/page/paystack_reconciliation/paystack_reconciliation.js"
click node_activity "https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/report/paystack_activity/paystack_activity.py"
click node_other_reports "https://github.com/mymi14s/frappe_paystack/tree/version-15/frappe_paystack/frappe_paystack/report"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_desk,node_pos,node_webshop,node_payment_request,node_payment_log,node_checkout,node_checkout_route,node_api,node_qr toneBlue
class node_saved_cards,node_refund,node_subscription,node_portal,node_portal_route toneAmber
class node_settlement,node_sweep,node_reconcile,node_reconcile_api,node_reconcile_page toneMint
class node_activity,node_other_reports toneRose
class node_customer,node_staff,node_paystack toneIndigo
```

## Components

### Payment collection

- [Gateway settings](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/doctype/paystack_gateway_setting/paystack_gateway_setting.py): `frappe_paystack/frappe_paystack/doctype/paystack_gateway_setting/paystack_gateway_setting.py`
- [Desk payment actions](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/public/js/paystack_actions.bundle.js): `frappe_paystack/public/js/paystack_actions.bundle.js`
- [POS payment flow](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/pos_payment.py): `frappe_paystack/utils/pos_payment.py`
- [Webshop checkout](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/public/js/paystack_cart_guard.bundle.js): `frappe_paystack/public/js/paystack_cart_guard.bundle.js`
- [Payment Request](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/payment_request.py): `frappe_paystack/utils/payment_request.py`
- [Payment Log and booking](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/doctype/paystack_payment_log/paystack_payment_log.py): `frappe_paystack/frappe_paystack/doctype/paystack_payment_log/paystack_payment_log.py`
- [Checkout page](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/public/js/paystack_checkout.js): `frappe_paystack/public/js/paystack_checkout.js`
- [Checkout route](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/www/paystack-checkout/index.py): `frappe_paystack/www/paystack-checkout/index.py`
- [Payment and webhook API](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/api.py): `frappe_paystack/api.py`
- [Payment QR codes](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/qr.py): `frappe_paystack/utils/qr.py`

### Payment operations

- [Saved authorizations](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/doctype/paystack_customer_authorization/paystack_customer_authorization.py): `frappe_paystack/frappe_paystack/doctype/paystack_customer_authorization/paystack_customer_authorization.py`
- [Refund processing](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/doctype/paystack_refund_log/paystack_refund_log.py): `frappe_paystack/frappe_paystack/doctype/paystack_refund_log/paystack_refund_log.py`
- [Subscription collection](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/subscription.py): `frappe_paystack/utils/subscription.py`
- [Customer payment portal](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/portal.py): `frappe_paystack/utils/portal.py`
- [Portal route](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/www/my-payments/index.py): `frappe_paystack/www/my-payments/index.py`

### Finance and reconciliation

- [Payout settlement](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/settlement.py): `frappe_paystack/utils/settlement.py`
- [Payment retry sweep](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/sweep.py): `frappe_paystack/utils/sweep.py`
- [Payment reconciliation](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/reconciliation.py): `frappe_paystack/utils/reconciliation.py`
- [Reconciliation API](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/utils/reconciliation_api.py): `frappe_paystack/utils/reconciliation_api.py`
- [Reconciliation page](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/page/paystack_reconciliation/paystack_reconciliation.js): `frappe_paystack/frappe_paystack/page/paystack_reconciliation/paystack_reconciliation.js`

### Reports and monitoring

- [Activity report](https://github.com/mymi14s/frappe_paystack/blob/version-15/frappe_paystack/frappe_paystack/report/paystack_activity/paystack_activity.py): `frappe_paystack/frappe_paystack/report/paystack_activity/paystack_activity.py`
- [Payment and settlement reports](https://github.com/mymi14s/frappe_paystack/tree/version-15/frappe_paystack/frappe_paystack/report): `frappe_paystack/frappe_paystack/report`

### Other components

- **Customer**
- **Desk and POS staff**
- **Paystack**

## Connections

- Desk and POS staff → Desk payment actions: starts payment (evidence: `README.md`)
- Desk payment actions → Payment Request: requests payment (evidence: `README.md`)
- Desk payment actions → Payment and webhook API: creates link (evidence: `frappe_paystack/api.py`)
- Desk payment actions → Payment QR codes: shows QR (evidence: `README.md`)
- Payment Request → Payment Log and booking: creates log (evidence: `README.md`)
- POS payment flow → Payment and webhook API: initializes charge (evidence: `README.md`)
- Webshop checkout → Payment Request: routes checkout (evidence: `README.md`)
- Payment and webhook API → Payment Log and booking: records capture (evidence: `frappe_paystack/api.py`)
- Payment and webhook API → Paystack: initializes transaction (evidence: `frappe_paystack/api.py`)
- Paystack → Payment and webhook API: sends webhook (evidence: `README.md`)
- Payment and webhook API → Checkout route: sets callback (evidence: `frappe_paystack/api.py`)
- Customer → Checkout page: pays (evidence: `README.md`)
- Checkout page → Payment and webhook API: starts checkout (evidence: `README.md`)
- Checkout route → Checkout page: serves page (evidence: `frappe_paystack/www/paystack-checkout/index.py`)
- Payment and webhook API → Saved authorizations: stores authorization (evidence: `frappe_paystack/api.py`)
- Desk payment actions → Saved authorizations: charges saved card (evidence: `README.md`)
- Payment and webhook API → Refund processing: processes refunds (evidence: `frappe_paystack/api.py`)
- Payment and webhook API → Payout settlement: handles payout event (evidence: `frappe_paystack/api.py`)
- Subscription collection → Payment Request: collects invoices (evidence: `README.md`)
- Customer → Portal route: opens payments (evidence: `README.md`)
- Portal route → Customer payment portal: loads payment data (evidence: `frappe_paystack/www/my-payments/index.py`)
- Payment Log and booking → Payment retry sweep: retries capture (evidence: `frappe_paystack/frappe_paystack/doctype/paystack_payment_log/paystack_payment_log.py`)
- Reconciliation API → Payment reconciliation: runs checks (evidence: `frappe_paystack/utils/reconciliation_api.py`)
- Reconciliation page → Reconciliation API: requests reconciliation
- Desk and POS staff → Reconciliation page: reviews results (evidence: `README.md`)
- Desk and POS staff → Activity report: reviews activity (evidence: `README.md`)
- Desk and POS staff → Payment and settlement reports: runs reports (evidence: `README.md`)
- Gateway settings → Payment and webhook API: provides settings
