English | فارسی

JS-Basic-Example-Payment

A simple, educational sample for integrating with the PayPing payment gateway using Node.js — with zero external dependencies (plain Node.js only).

This project is built on PayPing API v3 (the v3/pay routes).

Payment Flow (v3)

1. The user fills in the form on the home page (email, mobile, name, amount, and description).
2. POST /payment → the server creates a payment order by calling POST api.payping.ir/v3/pay. The response contains a paymentCode and a ready-to-use url, so the user is redirected straight to that url.
3. After the bank gateway flow finishes, PayPing sends the result to your returnUrl (the /verify route) as a POST form:
   • status: 1 means successful, 0 means not paid
   • errorCode: the returned error code — empty on success
   • data: a JSON string containing clientRefId, paymentCode, paymentRefId (tracking code), amount, gatewayAmount, cardNumber, and cardHashPan
4. If status equals 1, the server finalizes the transaction by calling POST api.payping.ir/v3/pay/verify and shows the result.

Important: If verify is not called within 10 minutes after the payment, the payment becomes invalid and the paid amount is returned to the payer.

Project Structure

├── server.js      # The whole app: form, payment creation, and verification
├── package.json
├── README.md      # English documentation
└── README.fa.md   # Persian (فارسی) documentation

Route	Method	PayPing API equivalent (v3)	Description
/payment	POST	POST /v3/pay	Create payment and redirect to the returned url
/verify	POST	POST /v3/pay/verify	Receive the gateway result and verify the transaction

Prerequisites

• Node.js v18 or later (for the built-in fetch)
• An API token from the PayPing panel (Developers section → Tokens)

Getting Started

# Linux / macOS
PAYPING_TOKEN=your-token node server.js

# Windows (PowerShell)
$env:PAYPING_TOKEN="your-token"; node server.js

# or with npm
npm start

Then open http://localhost:3000 in your browser.

Configuration (Environment Variables)

Variable	Default	Description
PAYPING_TOKEN	—	Your token from payping.ir (required)
PORT	3000	Server port
RETURN_URL	http://localhost:3000/verify	The URL the user is sent back to after payment; use your own domain in production

Production example:

PAYPING_TOKEN=xxxx RETURN_URL=https://domain.com/verify PORT=80 node server.js

PayPing API v3 Notes

• Besides paymentCode and url, the create-payment response includes amounts: amount (the payment order amount), gatewayAmount (the final amount the payer sees — it may be higher depending on your fee scenario), plus payerWage/businessWage fees and paypingVat.
• The verify response returns full transaction details: amount, masked card number, clientRefId, payment date, and fees.
• Special verify statuses:
  • 409 with metaData.code = 110 → the transaction has already been verified; no need to verify again.
  • 202 or 502 → verification is still being processed; call verify again.
• Optional create-payment fields you can add if needed: nationalCode, isReversible (enables refunds for up to 30 minutes after verify), and isBlocked (blockable payment for post-payment splitting via the share/unblock services).

Production Notes

• Never commit your token; always use environment variables.
• Always determine and validate the amount on the server side; trusting a client-submitted amount is dangerous. For simplicity, this sample reads the amount from the form, appends it to the returnUrl, and compares it with the amount sent back by PayPing — in a real project, read it from your invoice/database instead.
• Per the official docs: after a successful callback, compare the amount and clientRefId sent by PayPing with your own database and abort the process on any mismatch (this comparison is implemented in the sample).
• It is recommended to use an invoice number as clientRefId and store the verify result along with paymentRefId in your database for traceability.
• This sample is for educational purposes only; use HTTPS in production and apply the necessary security measures (rate limiting, logging, etc.).

License

GPL-3.0 — matching the original repository.