📂Configuration

Introduction

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.

---

Quick Start

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

---

Full Example

{
	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,
			},
		},
	}
}

---

PayPal Client

Creating a PayPal Application

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

1. Open the PayPal Developer Portal: Developer Portal

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

---

paypal.paypal_client

client_id

• PayPal REST API client ID

client_secret

• PayPal REST API client secret

is_live

• false = sandbox environment

• true = live production environment

paypal.paypal_client.webhooks

enabled

• Enable PayPal webhook verification and automatic status updates

webhook_id

• PayPal webhook ID used to validate incoming webhook signatures

---

Merchant Details

paypal.merchant

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

---

Invoice Defaults

paypal.invoice

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

---

Partial Payments

paypal.settings

allow_partial_payments

• Allow customers to pay in multiple transactions

paypal.minimum_payment

enabled

• Enforce a minimum payment amount

minimum_in_percent

• Minimum payment as a percentage of the invoice total

---

Logging

paypal.logs

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

• invoice_created

• invoice_paid

• invoice_cancelled

• invoice_refunded

---

Webhook Notes

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.