Frappe Moyasar Payments

Technical Integration & Deployment Guide

Reusable Moyasar hosted-checkout integration for Frappe Web Forms and custom Frappe documents.

Documentation version 0.1.1

Frappe Framework 15 / 16  •  ERPNext 15 / 16 (optional)  •  Payments app 0.0.1  •  Frappe Cloud private benches

Purpose

This guide explains the supported payment flow, deployment steps, configuration, security model, callback endpoints, verification behavior, and development checks for the Frappe Moyasar Payments integration.

Scope boundary

Version 0.1 focuses on payment collection and verification. It does not create Sales Invoices, Customers, Payment Entries, or General Ledger entries.

Contents

1. Introduction and Scope
2. Compatibility and Prerequisites
3. Core Capabilities
4. Payment Architecture and Lifecycle
5. Installation on Frappe Cloud
6. Gateway and Web Form Configuration
7. Example Scenario: Course Registration - SAR 299.00
8. Security Model
9. Callback and Return Endpoints
10. Verification, Reuse, and Idempotency
11. Development and Integration Testing
12. Operational Notes and Limitations
13. Version History

Appendix A. CRM Lead Payment Field Reference

Appendix B. Go-Live Checklist

1. Introduction and Scope

Frappe Moyasar Payments is a reusable integration that connects Frappe payment-enabled Web Forms and custom Frappe documents to Moyasar hosted checkout. The integration is designed to keep payment credentials and verification logic on the server while allowing end users to complete payment through the hosted provider flow.

Moyasar is used here as the external payment gateway/provider. Frappe initiates the checkout, records each checkout attempt, verifies the payment directly with Moyasar, and then updates the relevant payment status information in Frappe.

1.1 Intended audience

• Frappe and ERPNext implementation teams.

• Frappe developers maintaining payment-enabled Web Forms or custom documents.

• System Managers responsible for gateway configuration and deployment.

• QA teams validating checkout, callback, duplicate-payment, and verification behavior.

1.2 Release scope

Hosted payment collection: Included - through Moyasar hosted checkout.

Server-side payment verification: Included - paid status, amount, currency, provider ID, and metadata.

Checkout attempt tracking: Included - stored in Moyasar Payment.

Duplicate / repeat callback handling: Included - idempotent processing.

Automatic Sales Invoice creation: Not included.

Automatic Customer creation: Not included.

Automatic Payment Entry creation: Not included.

General Ledger posting: Not included.

Important

A verified Moyasar payment is a payment-status event. Accounting documents and ERPNext ledger postings remain outside this release scope and must be handled separately if required.

2. Compatibility and Prerequisites

Frappe Framework: Version 15 / 16

ERPNext: Version 15 / 16 - optional

Payments app: Version 0.0.1

Deployment: Frappe Cloud private benches

Moyasar credentials: A valid test or production secret key, configured only in Frappe settings

2.1 Version 0.1.1 compatibility note

Version 0.1.1 supports Frappe v15 and v16. It also includes a compatibility repair for Frappe v15 environments where the Payments submit override is active while the core Web Form controller remains cached. This repair is intended to keep the standard Web Form payment flow working reliably in that condition.

3. Core Capabilities

• Registers Moyasar as a Frappe Payment Gateway.

• Creates hosted Moyasar invoices from the standard Frappe Web Form payment flow.

• Stores every checkout attempt in the Moyasar Payment DocType.

• Verifies payment status on the server before treating a transaction as paid.

• Validates the expected amount, currency, provider ID, and metadata against Moyasar.

• Handles repeat callbacks safely without processing the same successful payment twice.

• Reuses an active checkout instead of generating unnecessary duplicate checkouts.

• Blocks a second payment after the referenced transaction has already succeeded.

• Optionally updates standard Moyasar summary fields on the referenced Frappe document.

• Adds payment summary fields to CRM Lead when that DocType is available.

4. Payment Architecture and Lifecycle

The integration uses a hosted checkout model. Frappe is responsible for initiating the transaction and verifying the final result; the customer completes the payment in the provider-hosted checkout experience.

High-level flow

Web Form / Custom Document -> Frappe Backend -> Moyasar Hosted Checkout -> Callback / Webhook / Return -> Server-side Verification -> Record Update

1. Payment request - A Web Form or custom Frappe document supplies the transaction amount, currency, description, and source-document context.

2. Checkout creation - The Frappe backend creates a hosted Moyasar invoice, or reuses an existing active checkout when appropriate.

3. Attempt tracking - The checkout attempt is stored in Moyasar Payment for traceability.

4. Customer payment - The customer completes the payment through the Moyasar hosted checkout.

5. Signal received - Moyasar callback/webhook and the browser return flow can signal that the payment flow has progressed.

6. Server verification - Frappe retrieves the invoice directly from Moyasar and validates the payment result.

7. Record update - The verified result is written to Moyasar Payment and optional summary fields on the source document.

8. Duplicate protection - Subsequent callbacks or payment attempts are handled idempotently and do not create a second successful payment.

5. Installation on Frappe Cloud

1. Add the GitHub repository containing frappe_moyasar_payments to the private bench.
2. Ensure the official payments app is available on the same bench.
3. Deploy the bench and install frappe_moyasar_payments on the required site.
4. Log in as System Manager and open Moyasar Settings.
5. Enable the gateway, select Test Mode for validation, and enter a newly generated Moyasar test secret key.
6. Optionally configure a Moyasar dashboard webhook using the webhook URL displayed in Moyasar Settings, and use the same shared secret on both sides.

Credential handling

Never place the Moyasar secret key in source files, client-side JavaScript, documentation screenshots, chat messages, or version control. Enter it only through the encrypted password field in Frappe settings.

6. Gateway and Web Form Configuration

6.1 Moyasar Settings

Open Moyasar Settings as System Manager and configure the gateway for the target site. During implementation and QA, use Test Mode with a newly generated test secret key. Production credentials should only be introduced after successful testing and an approved go-live process.

6.2 Web Form Payments tab

For each Frappe Web Form that should collect payment, configure the Payments tab as follows:

• Enable Accept Payment.

• Select Moyasar as the payment gateway.

• Select the transaction currency.

• Enter a fixed amount, or enable Amount Based On Field when the value must come from a document field.

Reusable gateway design

The amount and description are supplied by the calling Web Form or document. They are not global gateway settings, allowing the same Moyasar configuration to serve multiple forms and use cases.

6.3 Source-document summary fields

When CRM Lead is installed, the integration can update the following payment summary fields after successful server-side verification:

custom_moyasar_payment_status — Stores the verified payment status.

custom_moyasar_invoice_id — Stores the Moyasar invoice identifier.

custom_moyasar_payment_id — Stores the provider payment identifier.

custom_moyasar_paid_amount — Stores the verified amount paid.

custom_moyasar_paid_at — Stores the verified payment timestamp.

custom_seat_reserved — Updates the course-registration seat reservation state after successful payment.

7. Example Scenario: Course Registration - SAR 299.00

The following scenario demonstrates a practical use of the integration for a paid course-registration Web Form that creates or references a CRM Lead.

7.1 Scenario configuration

Use case: Online course registration

Source document: CRM Lead

Payment method: Moyasar hosted checkout

Currency: SAR

Amount: SAR 299.00

Payment mode: Fixed amount in Web Form Payments tab

Post-payment action: Update Moyasar summary fields and seat reservation status after verified payment

7.2 End-to-end example

1. A participant opens the course-registration Web Form, enters the requested registration details, and submits the form.
2. Frappe reads the payment configuration and requests a checkout for SAR 299.00 using Moyasar.
3. The integration stores the checkout attempt in Moyasar Payment and redirects the participant to the hosted checkout.
4. The participant completes payment on the Moyasar-hosted page.
5. A callback, optional global webhook, or browser return brings the transaction back into the application flow. None of these signals is treated as proof of payment by itself.
6. The Frappe backend fetches the transaction directly from Moyasar and verifies that the payment is paid and that the expected amount, currency, provider ID, and metadata are correct.
7. After successful verification, Moyasar Payment is marked with the verified result and the CRM Lead payment summary fields are updated, including the seat-reservation field.
8. If the user refreshes the return page or Moyasar sends the callback again, the integration handles the event idempotently and does not create a second successful payment.
9. If the same source document attempts to start payment again after success, the integration blocks the second payment.

7.3 Expected business result

Successful verified payment: CRM Lead reflects the verified Moyasar payment summary and seat reservation state.

Repeated callback: No duplicate success processing; the existing payment result is reused.

Active unpaid checkout already exists: The active checkout can be reused rather than creating another checkout.

Payment already successful: A second payment attempt is blocked.

Browser return received without verified provider status: The return is not accepted as proof of payment; server-side verification remains required.

8. Security Model

Secret storage: The Moyasar secret key is stored in an encrypted Frappe Password field.

Backend-only provider access: Only backend code calls Moyasar with the secret key.

Untrusted redirect/callback data: Callback payloads and browser redirects are not accepted as proof of payment.

Direct provider verification: The application retrieves the invoice directly from Moyasar before completing the payment state.

Callback token protection: Per-checkout callback links use a random token; only its SHA-256 digest is stored.

Log hygiene: Authorization headers and secrets are never written to transaction logs.

Return URL restriction: Return URLs are restricted to the current Frappe site.

Key rotation requirement

If a test or production secret has ever been shared in chat, email, a ticket, a screenshot, or source control, regenerate the key before configuring the site.

9. Callback and Return Endpoints

The integration exposes separate endpoints for per-checkout paid notifications, an optional global Moyasar webhook, and the browser return flow.

Per-checkout paid notification: /api/method/frappe_moyasar_payments.api.invoice_callback

Global Moyasar webhook (optional): /api/method/frappe_moyasar_payments.api.webhook

Browser return endpoint: /api/method/frappe_moyasar_payments.api.payment_return

9.1 Endpoint responsibilities

These endpoints are entry points into the payment flow, not independent sources of truth. The integration completes the transaction only after backend verification against Moyasar. This design reduces the risk of treating a forged browser redirect or callback payload as a successful payment.

10. Verification, Reuse, and Idempotency

10.1 Server-side verification checks

• Paid status returned by Moyasar.

• Amount matches the expected transaction amount.

• Currency matches the configured transaction currency.

• Provider payment/invoice identifiers match the stored checkout context.

• Metadata matches the expected Frappe transaction context.

10.2 Idempotent processing

Payment providers can retry webhooks or callbacks, and users can refresh a return page. The integration therefore treats repeated signals as repeat processing of the same transaction rather than as new transactions. Once a successful payment is recorded, repeated events should resolve to the existing result.

10.3 Active checkout reuse and second-payment protection

When a valid active checkout already exists for the same payment request, the integration can reuse that checkout. After a verified success, a new payment for the same referenced transaction is blocked to reduce accidental double payment.

11. Development and Integration Testing

11.1 Pure-Python test suite

The pure-Python checks do not require a running Frappe bench. Run:

python -m unittest discover -s tests -v

11.2 Frappe integration test

For end-to-end testing, install the application on a Frappe v15 or v16 development site with the supported Payments app and validate the full checkout, callback, provider verification, and source-document update flow.

11.3 Recommended acceptance tests

Gateway registration: Moyasar appears as a selectable payment gateway.

Fixed-amount checkout: Configured SAR amount is passed correctly to the hosted checkout.

Amount based on field: Document field amount is used when that option is enabled.

Successful payment: Verified provider result updates Moyasar Payment and source summary fields.

Failed / unpaid transaction: Source document is not marked as paid.

Repeated callback: No duplicate successful processing occurs.

Active checkout: Existing active checkout is reused where applicable.

Second payment after success: New checkout is blocked.

Tampered return/callback data: Unverified client payload does not create a paid state.

Secret/log review: No secret key or authorization header appears in logs.

12. Operational Notes and Limitations

• Version 0.1 is intentionally limited to payment collection and verification.

• ERPNext accounting records are not created automatically by this release.

• The optional global webhook is not required for the basic hosted checkout flow when the per-checkout callback and return mechanisms are sufficient for the implementation.

• The Web Form or calling document remains responsible for supplying the transaction amount and description.

• Payment state should always be based on direct provider verification, not on front-end success messages or redirect parameters.

• Use Test Mode during implementation and switch to production credentials only after the acceptance checklist has passed.

Implementation responsibility

If the business process requires Sales Invoices, Payment Entries, Customer creation, or ledger posting, implement those as a separate, explicitly controlled ERPNext workflow after payment verification.

13. Version History

0.1: Initial payment-collection and verification release: gateway registration, hosted invoice creation, Moyasar Payment tracking, server-side verification, idempotent callbacks, active-checkout reuse, duplicate-payment protection, and optional source-document summary updates.

0.1.1: Supports Frappe v15 and v16 and includes the Frappe v15 compatibility repair for environments where the Payments submit override is active but the core Web Form controller remains cached.

Appendix A. CRM Lead Payment Field Reference

custom_moyasar_payment_status — Verified payment state. Updated only after server-side verification.

custom_moyasar_invoice_id — Moyasar invoice reference. Provider invoice identifier.

custom_moyasar_payment_id — Moyasar payment reference. Provider payment identifier.

custom_moyasar_paid_amount — Verified amount paid. For the course example: SAR 299.00.

custom_moyasar_paid_at — Verified paid timestamp. Provider-confirmed payment time.

custom_seat_reserved — Registration seat-reservation state. Updated after verified payment in the course-registration use case.

Appendix B. Go-Live Checklist

[ ] Application installed on the intended Frappe v15 / v16 site.

[ ] Official Payments app present on the same bench.

[ ] Moyasar gateway enabled and configured.

[ ] Fresh production secret key stored only in the encrypted Frappe Password field.

[ ] Test keys previously shared in chat, email, source control, or screenshots have been regenerated.

[ ] Web Form Accept Payment enabled, with Moyasar and the correct currency selected.

[ ] Fixed amount or Amount Based On Field configuration verified.

[ ] Success, unpaid, retry, duplicate-callback, active-checkout, and second-payment scenarios tested.

[ ] CRM Lead summary fields confirmed where CRM Lead is part of the use case.

[ ] Optional global webhook configured with the same shared secret on both sides, if used.

[ ] Logs reviewed to confirm authorization headers and secrets are not written.

[ ] Business team understands that accounting documents and GL entries are outside v0.1 scope.

End of Technical Integration Guide