Payment Integration - Nodeloc Docs

Quick start

Integration flow

Create a payment app → get a Payment ID and Secret Key
User places an order → call the initiate payment API
Redirect to payment → the user logs in on NodeLoc and pays
Receive the callback → the browser redirects to your callback URL
Query status (optional) → actively query the payment result
Transfer to other users (optional) → call the transfer API to send the applicant’s points to a specified user

Create a payment app

Visit the management page

https://www.nodeloc.com/payment/applications

Creating a payment app requires Silver member (TL1) or above, and new apps must be approved by an admin before use.

Fill in the app info

Field	Description	Example
App name	Your website/store name	”My Online Store”
Website URL	Your website homepage	`https://example.com`
Callback URL	The URL that receives payment notifications	`https://example.com/payment/callback`
Description	App description (optional)	“Online store payment integration”

Save your keys

After creation, the following will be displayed:

Payment ID: pay_xxxxxxxxxxxxxxxxxx
Secret Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The Secret Key is shown only once — save it immediately!

Initiate payment

API endpoint

POST https://www.nodeloc.com/payment/pay/:payment_id/process

Request parameters

Parameter	Type	Required	Description
`amount`	Integer	Yes	Payment amount (points)
`description`	String	Yes	Transaction description
`order_id`	String	Yes	Your order number (unique identifier)
`signature`	String	Yes	HMAC-SHA256 signature

Signature algorithm

Prepare the parameters: amount, description, order_id
Sort by key name: arrange the parameters in alphabetical order
Build the string: in the format key1=value1&key2=value2&key3=value3
Compute the key: token_hash = SHA256(your_token) // your token is in the tk_xxx format
Generate the signature: signature = HMAC-SHA256(token_hash, param_string)

Important:

your_token is the token obtained when the app was created (format: tk_xxx...)
token_hash is the SHA256 hash of the token (64-character hex string)
Do not use the token directly as the HMAC key!

Signature parameter example:

amount=100&description=Purchase VIP membership&order_id=order_20251008_001

Response data

On success:

{
  "payment_url": "https://www.nodeloc.com/payment/pay/txn_xxx",
  "transaction_id": "txn_xxx",
  "status": "pending",
  "amount": 100
}

Redirect to payment

Redirect the user to the payment_url in the response. The user will:

Be automatically redirected to the login page (if not logged in)
Return to the payment page after logging in
Confirm the order and complete payment
Be redirected to your callback URL after a successful payment

Handle the callback

Callback method

Important: this is a browser GET redirect, not a server POST request!

After a successful payment, the user’s browser redirects to the callback URL you configured, with all parameters passed as a query string.

Callback parameters (URL query parameters)

Parameter	Type	Description
`transaction_id`	String	Transaction ID
`external_reference`	String	Your order number (i.e. `order_id`)
`amount`	Integer	Payment amount (points)
`platform_fee`	Integer	Platform fee (points)
`merchant_points`	Integer	Points actually received by the merchant
`status`	String	Transaction status (`completed`)
`paid_at`	DateTime	Payment time (ISO 8601)
`signature`	String	Callback signature (for verification)

Callback URL example

https://example.com/payment/callback?
  transaction_id=txn_xxx&
  external_reference=order_123&
  amount=100&
  platform_fee=5&
  merchant_points=95&
  status=completed&
  paid_at=2025-10-08T12:00:00Z&
  signature=abc123...

Verify the signature

You must verify the signature to prevent forged requests!

Verification steps:

Extract the signature parameter: get signature from the URL
Extract the other parameters: all parameters except signature itself
Sort by key name: arrange in alphabetical order
Build the string: in the format key1=value1&key2=value2...
Compute the signature: HMAC-SHA256(secret_key, param_string)
Compare signatures: the computed signature must exactly match the received one

Signature parameter example:

amount=100&external_reference=order_123&merchant_points=95&paid_at=2025-10-08T12:00:00Z&platform_fee=5&status=completed&transaction_id=txn_xxx

Process the order

After the signature verifies:

✅ Check idempotency: make sure the order hasn’t already been processed
✅ Verify the amount: confirm amount matches the order amount
✅ Update the order status: mark it as paid
✅ Execute business logic: deliver goods, activate services, etc.
✅ Show a confirmation page: display a payment success message to the user

Query status

If the callback fails or you need to actively confirm a payment status, use the query API.

API endpoint

POST https://www.nodeloc.com/payment/query/:payment_id

Request parameters

Parameter	Type	Required	Description
`transaction_id`	String	Yes	Transaction ID
`signature`	String	Yes	HMAC-SHA256 signature

Signature algorithm

Same as initiating payment:

Parameters: transaction_id
Build the string: transaction_id=txn_xxx
Signature: HMAC-SHA256(secret_key, param_string)

Response data

{
  "transaction_id": "txn_xxx",
  "status": "completed",
  "amount": 100,
  "platform_fee": 5,
  "merchant_points": 95,
  "description": "Purchase VIP membership",
  "external_reference": "order_123",
  "created_at": "2025-10-08T12:00:00Z",
  "updated_at": "2025-10-08T12:05:00Z",
  "paid_at": "2025-10-08T12:05:00Z",
  "expires_at": "2025-10-08T12:30:00Z",
  "expired": false,
  "error_message": null
}

Transaction statuses

Status	Description
`pending`	Waiting for the user to pay
`processing`	Payment being processed
`completed`	Payment successful
`failed`	Payment failed
`cancelled`	Cancelled
`refunded`	Refunded

Recommended use cases

Scheduled jobs checking the status of unpaid orders
Users actively querying order status
A fallback after callback failure

User transfer

Transfer points from the current payment app’s applicant to a specified NodeLoc user. Commonly used for external sites distributing rewards, prize draws, commission payouts, and similar scenarios.

The sender is fixed as the user who applied for the Payment app — you cannot transfer other people’s points. Make sure the applicant’s account holds enough points (including the fee).

API endpoint

POST https://www.nodeloc.com/payment/transfer/:payment_id

Request parameters

Parameter	Type	Required	Description
`to_user_id`	Integer	Yes	Recipient’s NodeLoc user ID
`to_username`	String	Yes	Recipient’s NodeLoc username (must belong to the same user as `to_user_id`)
`amount`	Integer	Yes	Number of points to transfer (excluding the fee)
`order_id`	String	Yes	Your order number (for idempotency; uniquely identifies this transfer)
`signature`	String	Yes	HMAC-SHA256 signature

Because user identity exists outside NodeLoc, to_user_id and to_username must both be correct and point to the same user; otherwise the request is rejected (this prevents transfers to the wrong account due to username changes or typos).

Fee rules

The fee is calculated automatically based on the applicant’s trust level (Trust Level), with rates following the discourse-points-service settings:

Trust level	Site setting	Default rate
TL0	`points_transfer_fee_rate_tl0`	10.0%
TL1	`points_transfer_fee_rate_tl1`	5.0%
TL2	`points_transfer_fee_rate_tl2`	2.0%
TL3	`points_transfer_fee_rate_tl3`	1.0%
TL4	`points_transfer_fee_rate_tl4`	0.5%

The TL-specific points_transfer_min_amount_tl{0..4} / points_transfer_max_amount_tl{0..4} limits also apply. Formula:

fee             = round(amount * fee_rate / 100)
total_deduction = amount + fee     // deducted from the applicant
recipient_gets  = amount           // received by the recipient

Signature algorithm

Prepare the parameters: to_user_id, to_username, amount, order_id
Sort by key name in alphabetical order
Build the string: key1=value1&key2=value2&...
Compute the signature: HMAC-SHA256(token_hash, param_string)
- token_hash = SHA256(your_token), same as initiating payment

Signature parameter example:

amount=100&order_id=transfer_20260425_001&to_user_id=123&to_username=alice

Idempotency

Transfers with the same payment_id + order_id are treated as the same transfer.
If the order is already completed, the original result is returned directly (no double charge).
If the order exists but its status is not completed, the request is rejected.

Response data

On success (200 OK):

{
  "success": true,
  "transaction_id": "txn_xxx",
  "order_id": "transfer_20260425_001",
  "status": "completed",
  "amount": 100,
  "fee": 5,
  "total_deduction": 105,
  "from_user_id": 42,
  "from_username": "merchant_owner",
  "to_user_id": 123,
  "to_username": "alice",
  "paid_at": "2026-04-25T12:15:00Z"
}

On failure (400 / 401):

{
  "success": false,
  "error": "Receiver id and username do not match"
}

Common errors

Error message	Description
`Invalid signature`	Signature error; regenerate it following the signature algorithm
`Invalid amount`	`amount` must be an integer greater than 0
`Receiver id and username do not match`	`to_user_id` and `to_username` do not match
`Cannot transfer to yourself`	The recipient cannot be the applicant
`Amount below minimum limit (X)`	Below the minimum limit for that TL
`Amount exceeds maximum limit (X)`	Above the maximum limit for that TL
`Insufficient balance (need X, have Y)`	Balance too low to cover `amount + fee`
`Transfer feature is disabled`	The site has disabled the transfer feature
`Order already exists with status ...`	The same `order_id` already exists and is not completed

Recommended use cases

External sites distributing rewards to NodeLoc users
Prize draws and event payouts
Commission and revenue-share settlement
Returning points to a specified user after acquiring them

Security recommendations

1. Protect your keys

❌ Don’t hardcode them in code
✅ Use environment variables or a key management service

2. Use HTTPS

✅ Production environments must use HTTPS
✅ The callback URL must be an HTTPS address

3. Verify signatures

✅ Verify the signature on all callback requests
✅ Reject requests when the signature doesn’t match

4. Prevent duplicate processing

✅ Check order status to prevent duplicate processing
✅ Use a unique order_id for transfers to guarantee idempotency
✅ Use database transactions to ensure atomicity

5. Verify amounts

✅ Verify that the callback amount matches the order amount
✅ Log and raise an alert when amounts don’t match

6. Verify the recipient

✅ Before transferring, confirm that to_user_id and to_username come from a trusted source
✅ Never transfer based on username alone — always validate the ID as well

7. Logging

✅ Log all payment/transfer-related operations
✅ Log all callback requests (including those that fail signature verification)

FAQ

Q: Signature verification fails?

Check the following:

Are the parameters sorted by key name in alphabetical order?
Is the parameter string in the key=value&key=value format?
Is the Secret Key correct?
Did you exclude the signature parameter itself when verifying?
Is the character encoding consistent (UTF-8)?

Q: Callback not received?

Possible causes:

The callback URL is configured incorrectly
The user closed the browser window
A network issue caused the redirect to fail

Solution: use the query API to periodically check order status

Q: How do I test?

Testing in a development environment:

Use a tool like ngrok to expose your local server
Create a test app on NodeLoc
Set the callback URL to the ngrok address
Create small-amount orders for testing

Q: Are refunds supported?

Automatic refunds are not currently supported; contact an admin for manual handling.

Q: Do orders expire?

Yes. Orders expire automatically after 30 minutes if unpaid.

Q: Can I transfer to any user?

Yes, as long as the to_user_id and to_username you provide are both correct and point to the same NodeLoc user. The sender is fixed as the user who applied for the Payment app — you cannot use this API to transfer other people’s points.

Q: What is the transfer fee?

The fee is calculated based on the applicant’s current trust level (TL0–TL4), corresponding to the site settings points_transfer_fee_rate_tl0 through points_transfer_fee_rate_tl4. The applicant is charged amount + fee; the recipient receives amount.

API reference

Initiate payment

URL: POST /payment/pay/:payment_id/process
Authentication: signature verification
Request: amount, description, order_id, signature
Response: payment_url, transaction_id, status, amount

Query status

URL: POST /payment/query/:payment_id
Authentication: signature verification
Request: transaction_id, signature
Response: full transaction info (see above)

User transfer

URL: POST /payment/transfer/:payment_id
Authentication: signature verification
Sender: fixed as the Payment app applicant
Request: to_user_id, to_username, amount, order_id, signature
Response: transaction_id, order_id, status, amount, fee, total_deduction, from_user_id, from_username, to_user_id, to_username, paid_at

Payment callback

Method: browser GET redirect
URL: the callback_url you configured
Authentication: signature verification
Parameters: transaction_id, external_reference, amount, platform_fee, merchant_points, status, paid_at, signature

EPay-compatible API (V2, RSA signatures)

If your system already integrates with an EPay (易支付) gateway, there is no need to rewrite it against the HMAC API above: NodeLoc serves the EPay V2 protocol directly — swap the gateway URL for NodeLoc and the currency becomes points. Anything that supports EPay (shops, card sellers, WHMCS modules, …) works as is.

Integration parameters

EPay setting	Value
Gateway URL	`https://www.nodeloc.com/payment/api` (the “EPay gateway URL” on the app card)
Merchant ID `pid`	the numeric “Merchant ID (EPay pid)” on the app card
Merchant private key	click “Generate RSA key pair” on the app card — the private key is shown once; or make your own pair and paste the public key into “Merchant RSA public key”
Platform public key	the “Platform RSA public key” on the app card, for verifying NodeLoc’s responses and callbacks
Exchange rate	set when creating the app: how many points one unit of your currency buys (default 1 CNY = 100 points). `money` on the API is converted at this rate
Sign type	`RSA` (SHA256WithRSA)

Signing follows EPay exactly: take every non-empty parameter except sign and sign_type, sort by name in ASCII order, join as k1=v1&k2=v2, sign with the merchant private key (SHA256WithRSA) and base64-encode. NodeLoc signs its responses and callbacks the same way with the platform private key; verify them with the platform public key. Every request carries a 10-digit timestamp in seconds; more than 5 minutes of drift is refused.

Endpoints

Endpoint	URL	Notes
Page-jump payment	`GET/POST /payment/api/pay/submit`	form redirect; the buyer lands on the NodeLoc pay page
Unified order	`POST /payment/api/pay/create`	returns `pay_type: "jump"` with the pay page as `pay_info`
Order query	`POST /payment/api/pay/query`	either `trade_no` or `out_trade_no`
Refund	`POST /payment/api/pay/refund`	full refunds only; `money` must equal the order amount
Close order	`POST /payment/api/pay/close`	closes an unpaid order
Merchant info	`POST /payment/api/merchant/info`	balance (points), today’s/yesterday’s order counts and takings

Parameter and response names match the EPay documentation, with these differences:

money is an amount in your currency (say "9.90"); NodeLoc converts it to points at the app’s rate (at the default 100 points per unit, 9.90 becomes 990 points), rounded to a whole number, and refuses anything under one point. Callbacks and queries echo the money you sent; the balance and takings in merchant info are converted back the same way. The platform fee comes out of the points the merchant receives.
type is echoed back as sent (alipay, wxpay or empty); method and device are ignored and pay_type is always jump.
Re-creating the same out_trade_no returns the same trade_no; creating one that is already paid answers code: 1.
buyer in a query is the paying user’s NodeLoc username.

V1 legacy API (MD5 signatures)

Many programs (card sellers, shops, WHMCS gateway modules, …) speak EPay V1: submit.php / mapi.php / api.php, signed with the merchant KEY by MD5 and without timestamps. NodeLoc serves that too, at the same gateway URL https://www.nodeloc.com/payment/api; the key is the “Merchant KEY (EPay V1 / MD5)” on the app card and can be reset at any time.

Endpoint	URL	Notes
Page-jump payment	`GET/POST /payment/api/submit.php`	`pid`, `type` (optional), `out_trade_no`, `notify_url`, `return_url`, `name`, `money`, `param`, `sign`, `sign_type=MD5`
API payment	`POST /payment/api/mapi.php`	answers `{ code: 1, trade_no, payurl }`; send the buyer to `payurl`
Single order	`GET /payment/api/api.php?act=order&pid=&key=&out_trade_no=`	or `trade_no`; `status` 1 means paid
Order list	`GET /payment/api/api.php?act=orders&pid=&key=`	`limit` (≤50), `page`
Merchant info	`GET /payment/api/api.php?act=query&pid=&key=`	balance converted to currency at the app’s rate
Refund	`POST /payment/api/api.php?act=refund`	`pid`, `key`, `trade_no`/`out_trade_no`, `money` (the full amount); as in V1, success is `code: 0`

MD5 signing: drop sign, sign_type and empty values, sort the rest by name in ASCII order, join as a=b&c=d (values not URL-encoded), append the merchant key and take the lowercase MD5. Notify and return callbacks for V1 orders carry pid, trade_no, out_trade_no, type, name, money, trade_status, param, sign, sign_type=MD5, signed the same way; answer the notify with success. One application can use V1 and V2 side by side: a request with sign_type=RSA is verified as V2, anything else as V1 MD5.

Payment notification

Once the buyer has paid:

Asynchronous notify: NodeLoc sends a GET to your notify_url with pid, trade_no, out_trade_no, api_trade_no, type, trade_status=TRADE_SUCCESS, addtime, endtime, name, money, param, buyer, timestamp, sign, sign_type. After verifying the signature your server must answer with the string success; otherwise NodeLoc retries after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours.
Synchronous return: the buyer’s browser is sent back to return_url with the same parameters.

Always verify sign and check that trade_status is TRADE_SUCCESS; fields may be added to callbacks in future, so include every non-empty parameter when verifying.

Happy integrating! 🚀

​Quick start

​Integration flow

​Create a payment app

​Visit the management page

​Fill in the app info

​Save your keys

​Initiate payment

​API endpoint

​Request parameters

​Signature algorithm

​Response data

​Redirect to payment

​Handle the callback

​Callback method

​Callback parameters (URL query parameters)

​Callback URL example

​Verify the signature

​Process the order

​Query status

​API endpoint

​Request parameters

​Signature algorithm

​Response data

​Transaction statuses

​Recommended use cases

​User transfer

​API endpoint

​Request parameters

​Fee rules

​Signature algorithm

​Idempotency

​Response data

​Common errors

​Recommended use cases

​Security recommendations

​1. Protect your keys

​2. Use HTTPS

​3. Verify signatures

​4. Prevent duplicate processing

​5. Verify amounts

​6. Verify the recipient

​7. Logging

​FAQ

​API reference

​Initiate payment

​Query status

​User transfer

​Payment callback

​EPay-compatible API (V2, RSA signatures)

​Integration parameters

​Endpoints

​V1 legacy API (MD5 signatures)

​Payment notification

Quick start

Integration flow

Create a payment app

Visit the management page

Fill in the app info

Save your keys

Initiate payment

API endpoint

Request parameters

Signature algorithm

Response data

Redirect to payment

Handle the callback

Callback method

Callback parameters (URL query parameters)

Callback URL example

Verify the signature

Process the order

Query status

API endpoint

Request parameters

Signature algorithm

Response data

Transaction statuses

Recommended use cases

User transfer

API endpoint

Request parameters

Fee rules

Signature algorithm

Idempotency

Response data

Common errors

Recommended use cases

Security recommendations

1. Protect your keys

2. Use HTTPS

3. Verify signatures

4. Prevent duplicate processing

5. Verify amounts

6. Verify the recipient

7. Logging

FAQ

API reference

Initiate payment

Query status

User transfer

Payment callback

EPay-compatible API (V2, RSA signatures)

Integration parameters

Endpoints

V1 legacy API (MD5 signatures)

Payment notification