Invoice Ninja gateway

Overview

The MakePay Invoice Ninja gateway adds a native crypto payment option to the Invoice Ninja client portal. It creates a hosted MakePay checkout and uses Invoice Ninja's payment service to allocate confirmed payments to invoices.

Using the hosted service? Follow the Invoice Ninja (cloud) guide to connect through Bookkeeping without installing a PHP driver.

Requirements

Use self-hosted Invoice Ninja v5, PHP 8.2 or later and invoices in your intended currency, such as EUR or USD. Custom drivers cannot be installed in Invoice Ninja's hosted service. The first version supports hosted checkout and signed callbacks; refunds are manual and recurring token billing is unavailable.

The driver follows the upstream BTCPay, Custom and BaseDriver interfaces. See the upstream reference and the validation record for the exact version tested.

Install the gateway

Back up your Invoice Ninja application and database. Download the repository, then run its installer with your Invoice Ninja path:

php scripts/install.php /path/to/invoiceninja

The installer copies the driver and portal views, registers MakePay in the native gateway list and adds two compatibility guards to app/Models/Gateway.php, saving a backup. Repeat the installer after an Invoice Ninja update replaces these files. Review the repository README for restoration instructions.

Connect MakePay

1. Configure settlement in the MakeCrypto company.
2. Create a company API key with makepay:payment-links:read and makepay:payment-links:write.
3. In Invoice Ninja, open Settings > Payment Settings > Configure Gateways > Create, select MakePay, and enable its Crypto payment method.
4. Enter companyId, apiKeyId, apiKeySecret and webhookSecret. Invoice Ninja stores these in the encrypted company gateway configuration.
5. Run the connection test and save the gateway. Keep clients' intended invoice currency. It is sent as fiatCurrency; the settlement token is configured separately in MakeCrypto.

Configure webhooks

Set the MakePay company's callback URL to Invoice Ninja's native webhook endpoint:

https://your-ninja-domain/payment_webhook/COMPANY_KEY/COMPANY_GATEWAY_ID

Copy the saved gateway's Webhook URL from its Overview screen. It includes the Invoice Ninja company key and the hashed ID of this specific company gateway, not the global gateway definition ID. The signing secret must match the MakePay company's webhook secret. Use separate MakePay companies when Wix and Invoice Ninja need different callbacks.

Checkout and payment confirmation

The portal shows the invoice amount and a Continue to MakePay action. The server derives the total from Invoice Ninja's payment hash, including configured fees; browser-submitted totals are ignored. Repeated requests reuse the stored link.

A signed completed notification must match the stored link, amount, currency and gateway. It creates a native payment and updates the invoice balance. Returning from checkout alone never marks an invoice paid. Duplicate deliveries reuse the payment already attached to the hash.

PDF and email payment buttons

Add a Pay with MakePay button to an invoice PDF, invoice email or reminder using the repository's PDF and email guide and ready-to-use HTML examples.

• PDF: open Settings > Invoice Design > Customize & Preview, copy your design and insert the PDF button fragment after the totals in its Body. Save and select the custom design. The template prints a fallback payment URL and hides the button if the PDF sanitizer removes its link.
• Email: open Settings > Templates & Reminders, select Invoice or an enabled reminder, and insert the corresponding HTML example. Enable Attach PDF if you also want the custom invoice attached.
• Receipt: enable Online Payment Notifications and customize the Payment email template. A completed verified MakePay callback uses Invoice Ninja's normal payment receipt; duplicate deliveries do not generate a second receipt.

The examples use $view_url to open the current invoice, where the customer selects Crypto / MakePay. Invoice Ninja's $payment_link and $payment_button use its first available gateway; use those for direct MakePay checkout only after checking that MakePay is the first/only available option. Configure your mail transport and public HTTPS application URL, then test the received email and downloaded PDF before sending to clients.

Test locally

The repository contains protocol tests and a native integration test for a disposable, migrated Invoice Ninja instance:

php tests/protocol.php
php tests/integration.php /path/to/local/invoiceninja

Native tests use MySQL and Invoice Ninja's own models and payment allocation service, with a simulated MakePay API. No funds are transferred. Test a controlled real MakePay payment separately before enabling this gateway for customers.

Troubleshooting

• Gateway missing after an upgrade: rerun the installer and clear application caches.
• Invalid connection: check encrypted credential fields, company scopes and settlement settings.
• Creation pending: inspect MakePay for the matching ninja_ payment hash before clearing a reservation. The API request may have succeeded despite a timeout. See the README recovery procedure.
• Callback rejected: check the company key, hashed gateway ID, matching secret, UID, fiat currency and amount.
• Temporary processing failure: fix the Invoice Ninja error and replay the signed delivery; the callback returns 503 so MakePay can retry.
• Refund: complete it in MakePay, verify settlement and record it manually in Invoice Ninja.