> ## Documentation Index
> Fetch the complete documentation index at: https://developer.quickei.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ERPNext

> Accept Quickei QR payments on ERPNext invoices

Accept Quickei payments on your ERPNext Sales Invoices with automatic Payment Entry creation and reconciliation.

## Requirements

| Requirement | Version                        |
| ----------- | ------------------------------ |
| ERPNext     | v15+                           |
| Frappe      | v15+                           |
| Quickei     | Merchant account with API keys |

## Installation

<Steps>
  <Step title="Install the app">
    Install the Quickei POS app in your ERPNext instance:

    ```bash theme={null}
    bench get-app https://github.com/appdevsx/quickei-erpnext.git
    bench --site your-site.local install-app quickei_pos
    bench migrate
    ```
  </Step>

  <Step title="Configure settings">
    Go to **Quickei Settings** doctype and enter:

    * **Client ID** — Your merchant API client ID
    * **Client Secret** — Your merchant API secret
    * **API Base URL** — `https://quickei.io/merchant-api/pos/v1`

    Click **Test Connection** to verify.
  </Step>

  <Step title="Set up the webhook">
    Configure the webhook URL in your Quickei Merchant Dashboard:

    ```
    https://your-erpnext.com/api/method/quickei_pos.api.webhook.handle
    ```
  </Step>
</Steps>

## How It Works

1. When a **Sales Invoice** is submitted, a Quickei payment order is created via the POS API
2. A **QR code** and/or **payment link** is generated and attached to the invoice
3. The customer pays using the Quickei app or payment page
4. A **webhook** fires → the app creates a **Payment Entry** and reconciles the invoice automatically

## Webhook Events

| Quickei Event         | ERPNext Action                          |
| --------------------- | --------------------------------------- |
| `pos.order.paid`      | Create Payment Entry, mark invoice Paid |
| `pos.order.expired`   | Log expiry, no action                   |
| `pos.order.cancelled` | Log cancellation                        |
| `pos.order.refunded`  | Create reverse Payment Entry            |

## Webhook Verification

The app verifies the `X-Quickei-Signature` header on every webhook:

```python theme={null}
import hmac, hashlib

expected = hmac.new(
    client_secret.encode(),
    payload_bytes,
    hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected, signature):
    frappe.throw("Invalid webhook signature")
```

## Payment Mode

The app creates a **Payment Mode** called `Quickei QR` during installation. All Payment Entries use this mode for easy filtering and reporting.

<Tip>
  Use the **Payment Reconciliation** tool in ERPNext to verify that all Quickei payments are properly matched to invoices.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="bench get-app fails">
    Ensure `git` is installed and your server can reach GitHub. If using a private repo, configure SSH keys or use HTTPS with a personal access token.
  </Accordion>

  <Accordion title="Webhook returns 403">
    Check that the webhook URL is correct and uses HTTPS. Verify that the `X-Quickei-Signature` matches — ensure the secret in ERPNext matches the one in the Quickei dashboard.
  </Accordion>

  <Accordion title="Payment Entry not created automatically">
    Check the ERPNext error log for details. Ensure the Sales Invoice exists and is in **Submitted** state. Verify the payment journal is configured in Quickei Settings.
  </Accordion>
</AccordionGroup>