n8n-nodes-usdpay

Official USDPAY community nodes for n8n. Create USDT payment invoices, retrieve invoice status, and automate fulfilment from signed payment webhooks.

n8n is a workflow automation platform. USDPAY provides non-custodial USDT checkout and on-chain payment confirmation for TRC20, TON, and BEP20.

Installation

Before verification, install the package on a self-hosted n8n instance:

1. Open Settings → Community Nodes.
2. Select Install.
3. Enter n8n-nodes-usdpay.

After n8n verification, search for USDPAY directly in the node picker on supported n8n Cloud and self-hosted instances.

Credentials

Create a store in USDPAY Dashboard, then open Stores → API / Webhook.

Create the USDPAY API credential in n8n with:

• Secret API Key — the sk_live_... key used as a Bearer token.
• Webhook Secret — the signing secret used to verify incoming webhook bodies.

Both fields are stored in n8n credentials. They are never returned in node output.

Create an invoice

Use USDPAY → Invoice → Create.

Required fields:

• Amount — a decimal string such as 49.00.
• Idempotency Key — a stable value such as order-{{$json.id}}-create.

Optional fields include currency, order ID, network, expiry, callback URL, and return URL. Leave Network as Customer Chooses to let checkout present the store's enabled networks.

The node returns the invoice fields at the top level, so the next node can use {{$json.checkoutUrl}} directly.

Get an invoice

Use USDPAY → Invoice → Get and provide an inv_... invoice ID. The node returns the current invoice object and any checkout availability metadata returned by USDPAY.

USDPAY Trigger

The USDPAY Trigger starts a workflow for:

• Invoice Paid (invoice.paid)
• Invoice Expired (invoice.expired)
• All Events

The trigger verifies X-USDPAY-Signature with HMAC-SHA256 over the original raw request body and uses a timing-safe comparison. An invalid signature receives HTTP 401 and does not start the workflow.

Webhook setup

1. Add USDPAY Trigger to a workflow.
2. Copy its Production Webhook URL.
3. In USDPAY Dashboard, open Stores → API / Webhook.
4. Paste the URL into the webhook URL field and select the required events.
5. Activate the n8n workflow.

The output keeps the complete signed payload and adds convenient camel-case fields: event, idempotencyKey, and deliveryId.

Examples

Import the JSON files in examples:

• Create a USDT invoice and send the checkout link through Telegram.
• Append a row to Google Sheets when a USDT payment is received.
• Send a Gmail confirmation after a USDT payment is confirmed.

Security

• Keep the Secret API Key and Webhook Secret only in n8n credentials.
• Use a stable idempotency key for retries; do not generate a new value on every automatic retry.
• Fulfil an order only after a verified invoice.paid trigger.
• Store the webhook idempotencyKey under a unique constraint before fulfilment.
• Never treat a browser return URL as payment confirmation.

Development

pnpm install
pnpm run check
pnpm run scan
pnpm run dev

The package uses the official n8n-node tool and has no runtime dependencies.

Resources

• USDPAY n8n integration
• USDPAY Payment API
• USDPAY webhook documentation
• n8n community node documentation

License

MIT