HivePay with n8n (no code)

Three ready-made workflows in docs/n8n/. Import them, fill in two values, and your site can take KBZ Pay / Wave Pay / card / USDT / bank-slip payments and credit the buyer — without writing a webhook handler.

You need from the HivePay operator: the base URL (https://pay…), your project's API key (hp_live_…), and — once the first workflow is live — you give them your webhook URL.

1. One credential, used by every workflow

n8n → Credentials → New → Header Auth

• Name: HivePay API key
• Header name: Authorization
• Header value: Bearer hp_live_… (the word Bearer, a space, then the key)

2. Receiving payments (do this first)

1. Workflows → Import from file → hivepay-payment-webhook.json.

2. Open Look up the payment: change https://www.hivepay.asia to your HivePay URL; under Credential for Header Auth pick HivePay API key.

3. Open Credit the user (replace me). It receives:

   Field	Meaning
   userId	the id you sent when the payment was created
   credits	how many credits to give (creditAmount)
   creditName	e.g. HCoin
   reference	HivePay's payment id, HP-… — store it
   amountMMK	what was paid
   orderId	your order id, if you sent one in metadata

   Replace this node with your real action, for example:

   • Google Sheets → Append row to a "credits" sheet, or
   • Postgres / MySQL → Insert into your credits table, or
   • HTTP Request to your own site's "add credits" endpoint.

4. Activate the workflow (toggle top-right). Open the HivePay webhook node and copy the Production URL — it looks like https://your-n8n/webhook/hivepay.

5. Send that URL to the HivePay operator: "please set this as the webhook URL on our project."

Not paid (mark the order) receives failed / expired / cancelled events with failureReason. Connect it to whatever marks the attempt as failed on your side, or leave it. One order can have several attempts (a buyer who switches wallets on the hosted page cancels the first), and a "failed" for an abandoned attempt can arrive after the "paid" — so never flip an order you've already credited back to failed.

Why it re-checks with HivePay

The workflow doesn't trust the incoming message; it asks HivePay GET /api/v1/payments/<reference> and only continues if HivePay says PAID. That needs no cryptography and cannot be faked: an attacker would have to know both your API key and a real paid reference. (Developers can add the signature check from INTEGRATION.md §7 in a Code node if they prefer.)

Why "Skip if already credited" matters

HivePay retries when your workflow is down and can resend on request. Every retry carries the same reference. That node remembers references it has passed (n8n 1.64 or newer) so a retry never credits twice. On an older n8n, delete the node and instead look the reference up in your sheet/table first.

3. Sending the buyer to HivePay's top-up page (easiest)

1. Import hivepay-hosted-topup.json; in Create top-up link set your HivePay URL and pick the credential. On Hosted top-up set Authentication → Header Auth so only your site can call it. Activate and copy its Production URL.

2. From your site / bot, POST:

   { "userId": "member_42", "displayName": "Khant", "orderId": "3f1c9e2a-…", "returnUrl": "https://movierecap.example/wallet" }
   

   Optional: "packageId": "starter" to pin a package, "provider": "KBZPay" to pre-select a wallet.

3. The reply is { "url": "https://pay…/topup/cs_…", "sessionId": "…", "expiresAt": "…" }. Send the buyer to url — a redirect, a button, or a link in a Telegram message. HivePay handles the rest and brings them back to returnUrl?ref=HP-…&status=PAID.

4. The first workflow (Section 2) credits them when the payment lands. Nothing else to build.

3b. Starting a payment with your own screens

1. Import hivepay-start-topup.json; in Create the payment set your URL and pick the credential.

2. On Start top-up set Authentication → Header Auth with a secret of your choosing so only your site can call it. Activate, copy its Production URL.

3. From your site / bot / form, POST JSON to that URL:

   { "userId": "member_42", "packageId": "starter", "provider": "KBZPay", "orderId": "3f1c9e2a-…" }
   

   • packageId — a package from your project's catalogue (ask the operator, or call GET /api/v1/payment-methods). Or send amountMMK instead.
   • provider — KBZPay, AYAPay, WavePay, CBPay, Visa, … ; "gateway": "MANUAL" for a bank/wallet transfer with a slip; "gateway": "NOWPAYMENTS" for USDT.
   • orderId — make one per checkout attempt (a UUID when the buyer clicks "top up") and send the same one again if you retry. It stops double charges.

4. The reply tells you what to show:

   { "reference": "HP-…", "status": "PENDING", "kind": "QR", "qrCode": "0002010102…", "checkoutUrl": null, "manual": null, "amountMMK": 5000, "creditAmount": 1100, "expiresAt": "…" }
   

   • kind: "QR" → turn qrCode into a QR image (any QR generator; in n8n an HTTP Request to a QR-image API works) and show it with the amount.
   • kind: "REDIRECT" or "INVOICE" → send the buyer to checkoutUrl.
   • kind: "MANUAL" → show manual.account (name, number, QR image, instructions).

5. The buyer pays; the first workflow fires and credits them. To show "paid" on screen, poll GET https://pay…/api/v1/payments/<reference> (with the credential) every few seconds until status isn't PENDING.

3c. Checking it works: the developer portal

Open https://pay…/portal and sign in with the same API key. Webhooks shows your n8n URL as an endpoint with its health, a Send test event button (it sends a fake payment.paid marked test: true; the workflow's first step recognises it and stops cleanly, so nothing is credited), and every delivery with the exact JSON your workflow received and what it answered. If n8n was down, press Replay on any row.

3d. Skip the link entirely: the public Top Up page

Turn on Public Top Up storefront in the portal (Settings) and buyers can go to https://pay…/topup, pick your site, enter their username and pay — you don't send anyone anywhere. So a typo can't top up a stranger, give H Pay a lookup URL: import hivepay-user-lookup.json, point Find the account at your members sheet/table — match what the buyer typed against username, user id and email columns (the placeholder just accepts every id), activate it, and paste its Production URL into Account lookup URL. H Pay signs each lookup with your webhook secret; the workflow's verify step is the same look it up, don't trust it idea — it only ever returns whether an id exists and a display name, nothing sensitive.

4. Movie Recap: what to wire

• userId = the member's id in Movie Recap. Whatever you send here is what comes back as userId in the first workflow — that's how the credit finds the right member.
• Credit the user = however Movie Recap stores balances today (sheet, database, or an endpoint on the site). Add credits to that member and record reference so support can look it up.
• Packages — tell the operator the bundles you sell (e.g. starter = 1000 HCoin + 100 bonus for 5,000 MMK); they're set on your project and priced server-side, so the site never sends a price.

5. Testing without real money

Ask the operator for a HivePay instance in mock mode. Then:

1. Mint a link with the hosted workflow and open it — pick a wallet on the page, or start a payment with the "own screens" workflow → either way you get an HP-… reference (the hosted page shows it under the QR; the session's payment.reference has it too).

2. Tell HivePay to pretend the buyer paid — in n8n, an HTTP Request node (or curl):

   POST https://pay…/api/dev/dinger/simulate
   { "reference": "HP-…", "status": "SUCCESS" }
   

3. Watch the first workflow run in Executions: Is it PAID? → true → your credit action runs once.

4. Run the simulate call again with the same reference — nothing should be credited a second time. (Send "status": "FAIL" on a fresh payment to see the failed branch.)

When it all works, ask the operator to switch your project to the live instance and repeat step 1 with a real 500 MMK payment.