Skip to content

Latest commit

 

History

History
220 lines (164 loc) · 6.66 KB

README.md

File metadata and controls

220 lines (164 loc) · 6.66 KB
Raw

BTCz-Pay (v0.2.1)

Self-hosted Node.js BitcoinZ payment gateway. Provides REST API (microservice). Process BitcoinZ payments on your end, securely, with no comission.

Request payments (invoicing), check payments (whether invoice is paid), receive callbacks if payment is made (client and server side).

Required

Installation

Clone & install project:

git clone https://github.com/MarcelusCH/BTCz-Pay && cd BTCz-Pay
npm install
cp config.js.dev config.js

Install & configure Couchdb:

sudo apt-get install couchdb
curl -s -X PUT http://localhost:5984/_config/admins/User_Name -d '"Pass_Word"'
curl -u User_Name -X PUT localhost:5984/btczpay

Edit config.js:

  • Point it to a your Couchdb database
  • Point it to a BitcoinZ Core RPC server
  • Add tmp wallet with founds for speed payment (disabled)
  • Update email params

Running

nodejs btcz-pay.js
nodejs worker1.js
nodejs worker2.js
nodejs worker3.js
nodejs worker4.js
nodejs worker5.js

(For production use pm2)

Open http://localhost:2222 in browser, you should see the website sample. That's it, ready to use.

License

MIT

Author

Marcelus (BTCZ community)

TODO

  • Aggregate funds on final (aggregational) address.
  • TBD

API

GET /api/request_payment/:expect/:currency/:message/:sellerAddress/:customerMail/:ipnPingback/:cliCallbackSuccess/:cliCallbackError/:SpeedSweep/:secret

Create a request to pay, supported currencies: BTCZ, USD, EUR, CHF, GBP, RUB. Non-btcz currency is converted to btcz using current rate from coinmarketcap.com.

Returns a json document with QR code to be displayed to the payer, and a unique address for that particular payment (you can use it as invoice id).

Message will be displayed to the client (for example, you can write "Payment for goods"). Seller and customer - system field, here you can write the application that created the request and the payer id.

Keep Seller field private, it is also used for payouts.Callback_url will be requested once the invoice is paid.

The ipnPingback (URL) parameter is never returned to the client. This URL is sent from server side, only once the check_result.state = 5 (success) or check_result.state = 2 (expired), and it could also send some key pare info.

The SpeedSweep parameter is to allow a speed payment (without confirmation). 0=disabled / 1=enabled The founds are taken from a tmp wallet that as to be created and stocked before.

The secret parameter is the secret phrase returned for the IPN pingback.

Example full router path:

http://localhost:2222/api/request_payment/0.005/BTCZ/wheres%20the%20money%20lebowski/t1VYSo8VtpKMm1SUwp1KJHbqrtfqj7tgpaE/test@test.com/https%253A%252F%252Fwww.google.com/https%253A%252F%252Fwww.google.com/https%253A%252F%252Fwww.google.com/0/01234abcd

(By using full router path, all parameters are mandatory)

Example with query string:

http://localhost:2222/api/request_payment/?expect=0.005&currency=BTCZ&message=wheres%20the%20money%20lebowski&seller=t1VYSo8VtpKMm1SUwp1KJHbqrtfqj7tgpaE&customerMail=test@test.com&ipnPingback=https%3A%2F%2Fwww.google.com&cliSuccessURL=https%3A%2F%2Fwww.google.com&cliErrorURL=https%3A%2F%2Fwww.google.com&SpeedSweep=0&secret=01234abcd

Expanded:

http://localhost:2222/api/request_payment/?
     expect=0.005&
     currency=BTCZ&
     message=wheres%20the%20money%20lebowski&
     seller=t1VYSo8VtpKMm1SUwp1KJHbqrtfqj7tgpaE&
     customerMail=test@test.com&
     ipnPingback=https%3A%2F%2Fwww.google.com&
     cliSuccessURL=https%3A%2F%2Fwww.google.com&
     cliErrorURL=https%3A%2F%2Fwww.google.com&
     SpeedSweep=0&
     secret=01234abcd

(By using query string, some parameters are optional )

Parameters definition:

  • expect = Mandatory - The expected amount to pay.
  • currency = Mandatory - The currency code (supported: BTCZ, BTC, USD, EUR, CHF, GBP, RUB).
  • seller = Mandatory - The seller BTCz address.
  • ipnPingback = Mandatory - The IPN URL to get (from server side) once paid or expired.
  • message = Optional - An optional message.
  • customerMail = Optional - The customer eMail
  • cliSuccessURL = Optional - The URL to redirect browser on success.
  • cliErrorURL = Optional - The URL to redirect browser on expired.
  • SpeedSweep = Optional - Use speed checkout (0=disabled / 1=enabled), default is 0.
  • secret = Optional - The secret phrase that is appended to IPN call. If not set, the gateway generate a random one.

JSON result:

{
  "id":"c5e9631d-b107-4022-8de5-ae9f0efd03af",
  "secret":"01234abcd",
  "address":"t1gwku8spbCFUodyJ26njknnDxeZGM8hVmm",
  "link":"bitcoinz:t1gwku8spbCFUodyJ26njknnDxeZGM8hVmm?amount=14.77818972&message=Hello",
  "qr":"http://localhost:2222/generate_qr/bitcoinz%3At1gwku8spbCFUodyJ26njknnDxeZGM8hVmm%3Famount%3D14.77818972%26message%3DHello",
  "qr_simple":"http://localhost:2222/generate_qr/bitcoinz:t1gwku8spbCFUodyJ26njknnDxeZGM8hVmm?amount=0.005"
}

GET /api/check_payment/:id

Check payment by a unique invoice number returned by the "request_payment.id" call. Only state 2 (expired/err) and 5 (success) return a callback URL.

Example

http://localhost:2222/api/check_payment/f22c44cb-e26a-4022-864f-00f0d523d48a

JSON result:

{
  "generated":"t1gwku8spbCFUodyJ26njknnDxeZGM8hVmm",
  "btcz_expected":14.77818972,
  "speed_sweep_fee":5,
  "btcz_actual":0,
  "btcz_unconfirmed":0,
  "currency":"USD",
  "amount":0.01,
  "timestamp_start":1537815608394,
  "timestamp_now":1537816142575,
  "timestamp_stop":1537816808394,
  "state":0,
  [optional] "successURL":"https://mysite_or_IP/result/?Hello=1",
  [optional] "errURL":"https://mysite_or_IP/result/?Hello=0"
}

(the speed_sweep_fee is in %)

States:

0=Initialized
1=Accepted
2=Expired
5=Success

GET /invoice/:id

Open/return the invoice template info with Qr code (as iframe).

Example

http://localhost:2222/invoice/f22c44cb-e26a-4022-864f-00f0d523d48a

IPN Pingback

On success paid or expired, the gateway pingback to the defined ipnPingback url set by the request_payment/ call. The secret and the state is appended.

Pingback url example

https://yourDomaine.com/yourPath/?and=yourParam&secret=01234abcd&state=5

or

https://yourDomaine.com/yourScript.php?secret=01234abcd&state=2

eCommerce Plugin

UPDATES