> For the complete documentation index, see [llms.txt](https://docs.iynxdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iynxdev.com/premium-addons/invoice/configuration.md).

# Configuration

## <mark style="color:blue;">Introduction</mark>

The Invoice addon is configured through `invoice.json5` in your `configuration/` folder. This file controls your PayPal credentials, invoice defaults, partial payment rules, and logging behavior.

***

## <mark style="color:blue;">Quick Start</mark>

1. Add your PayPal REST API `client_id` and `client_secret`
2. Set `is_live` to `false` for sandbox or `true` for live
3. Configure your merchant and invoice defaults
4. (Optional) Enable webhooks and add your PayPal webhook ID

***

## <mark style="color:blue;">Full Example</mark>

```json5
{
	config: {
		paypal: {
			paypal_client: {
				client_id: "",
				client_secret: "",
				is_live: false,
				webhooks: {
					enabled: false,
					webhook_id: "",
				},
			},

			merchant: {
				business_name: "Test Business",
				email_address: "",
				website_url: "https://example.com",
				logo_url: "",
				additional_notes: "",
			},

			invoice: {
				fee_in_percent: 5,
				currency_code: "USD",
				note: "",
				terms_and_conditions: "Your terms and conditions",
			},

			minimum_payment: {
				enabled: true,
				minimum_in_percent: 50,
			},

			settings: {
				allow_partial_payments: false,
			},

			logs: {
				invoice_created: true,
				invoice_paid: true,
				invoice_cancelled: true,
				invoice_refunded: true,
			},
		},
	}
}
```

***

## <mark style="color:blue;">PayPal Client</mark>

### <mark style="color:yellow;">Creating a PayPal Application</mark>

You must have a **PayPal Business** account to generate API credentials for live payments.

1. Open the PayPal Developer Portal: [Developer Portal](https://developer.paypal.com/developer/applications/)
2. Create an app for **Sandbox** (testing) or **Live** (production)
3. Copy the **Client ID** and **Secret** into `paypal.paypal_client.client_id` and `paypal.paypal_client.client_secret`
4. Set `is_live` to `true` for live credentials, or `false` for sandbox

***

### <mark style="color:yellow;">paypal.paypal\_client</mark>

**client\_id**

* PayPal REST API client ID

**client\_secret**

* PayPal REST API client secret

**is\_live**

* `false` = sandbox environment
* `true` = live production environment

### <mark style="color:yellow;">paypal.paypal\_client.webhooks</mark>

**enabled**

* Enable PayPal webhook verification and automatic status updates

**webhook\_id**

* PayPal webhook ID used to validate incoming webhook signatures

***

## <mark style="color:blue;">Merchant Details</mark>

### <mark style="color:yellow;">paypal.merchant</mark>

**business\_name**

* Store or business name shown on invoices

**email\_address**

* Primary PayPal email used for receiving payments

**website\_url**

* Website shown on invoices

**logo\_url**

* Optional logo image URL shown on the PayPal invoice page

**additional\_notes**

* Extra notes shown to the customer on invoices

***

## <mark style="color:blue;">Invoice Defaults</mark>

### <mark style="color:yellow;">paypal.invoice</mark>

**fee\_in\_percent**

* Percentage fee added to the invoice total

**currency\_code**

* Default invoice currency (e.g. `USD`, `EUR`, `GBP`)

**note**

* Optional note attached to each invoice

**terms\_and\_conditions**

* Terms shown at the bottom of each invoice

***

## <mark style="color:blue;">Partial Payments</mark>

### <mark style="color:yellow;">paypal.settings</mark>

**allow\_partial\_payments**

* Allow customers to pay in multiple transactions

### <mark style="color:yellow;">paypal.minimum\_payment</mark>

**enabled**

* Enforce a minimum payment amount

**minimum\_in\_percent**

* Minimum payment as a percentage of the invoice total

***

## <mark style="color:blue;">Logging</mark>

### <mark style="color:yellow;">paypal.logs</mark>

Enable or disable logging per event. Logs are posted to the `paypal_invoice_logs` channel.

* **invoice\_created**
* **invoice\_paid**
* **invoice\_cancelled**
* **invoice\_refunded**

***

## <mark style="color:blue;">Webhook Notes</mark>

If you enable webhooks, configure PayPal to send invoice events to:

```
http://<host_ip>:<web_api_port>/api/paypal
```

Make sure your Athena Web API is reachable from PayPal and that the webhook ID matches `paypal.paypal_client.webhooks.webhook_id`. **Important:** Ensure you select *only* the invoice events to be sent when configuring the webhook in PayPal.