Wow! Amazing job Marcelus! Seems to be a better alternative, which we can improve and use for the others!
Yes, itās a base of work for every developer (or coder) that would like us the BTCz as payment method. There is still a lot to doā¦
I also integrate a currency converter API get method:
https://pay.btcz.app/api/get_btcz_rate
that return a json like:
{"USD":0.000627064909881,"EUR":0.0005327016739824692,"CHF":0.0006050235782986825,"BTC":9.686039165599868e-8}
Iām checking to get up to 10 currencyās refreshed every 12 minutes (now itās only 4 refreshed once per hour).
Itās will maybe help for the Fiat Converter project:
https://forum.btcz.rocks/t/btcz-to-fiat-price-converter-android-app/629/
So far Iāve created a payment gateway using the Gateway form on the main site. I think it works so far with only one thing:
The pingback didnāt seem to send any information - I had netcat listening on my pingback address and all I got was:
GET / HTTP/1.1
host: 149.28.202.159:9005
Connection: close
I havenāt tested the GET API yet, but the only thing that seems to be missing is a āsuccess_urlā to send the payer back to the merchant site.
I just updated the code, pingback URLās should now work. I manage the return URL as follow:
- :srvPingback - Only executed on server side (never return back this value) once success.
- :cliPingbackSuccess - Returned URL once success.
- :cliPingbackError - Returned URL if fail (expired or error).
awesome I will test!
is there static ip of the server? so we can use it as extra protection for pingback checkā¦
i will test it soon with my magento 2 btcz extensionā¦
Yes there is a static IP (I send it to you in private).
@kovach, could you help with other plugins ?
@Marcelus yes I could, I just have to manage my very limited free timeā¦
After magento we can check other pluginsā¦
Nice to see you back here! thank you very much for Magento Bro!
All of our devs hard work should be gifted!
Version 0.1.2 (beta) online
Updates
- Almost instant payment checkout integration (5-8 sec)
I use a temporary address, already having funds, to transfer the payment of the buyer to the sellerās wallet without waiting for confirmation of the blockchain. Limited to 100 BTCz. - Added payment amount in the QR code
- Added unconfirmed amount in the invoice template
- Added RUB and GBP currencies support
- The currencies are now updated 2 time per hour (instead of 1 per hour)
Since https://pro.coinmarketcap.com/ updated the free account to 333 calls per day, Iām also able to provide (in the actual demo) 2 more currencies and more rate refresh. - Show gateway usage statistics (total gateway, expired, paid)
Information about the instant checkout
The instant payment checkout is NOT without risks! In the case of a chain fork or any other transaction ārollbackā, the buyer will lost the founds. We have also to think about this and other possible issues.
For the demo, I added a āSpeed Pay Feeā of 5%. Again, this is only for test proposes and everyone can fork this project and change it to free (or more). I added this fee more to test possibilities to get a return of investment for a service. I will not get rich with this and I do not want to scam people.
Iām open for any discussion about how to improve this functionality
Here a small demo on Youtube:
(I am not talented in video production, I do only a screen recording)
Need todo
- [ ] Better explanation of the API usage
- [ ] Youtube presentation (more professional than actual)
- [ ] Test check list with 20-50 users and analyze the output logs
- [ ] FAQ page
- [ ] Buyer, Seller, Admin stats/login (with 2 factor Auth. by eMail, like https://btcz.me)
- [ ] Otherā¦
Stats at 13-OCT-2018 11:45
@Marcelus awesome work!
I got around to testing it again - it looks like āpingbackā url is actually āsuccessURLā which means that is the URL that its going to after the payment completes.
SuccessURL vs. Pingback
SuccessURL = redirect after payment completes
PingbackURL = IPN (instant payment notification) URL is the URL that the seller points to so they can update the details about their buyers balance/purchase. It should POST details like that āstatusā etc.
Iāve not tested the GET API yet, but Iām about to test it now to see what the :cliPingbackSuccess and :cliPingbackError payload looks like.
Tx for feedback.
I will update the API documentation (with some example) in a couple of days.
To clarify a little the actual usage of the API, bellow some explication how I proceed it with the WP-Woocommerce Plugin.
To create a gateway
I make a request_payment/
GET call on the API as following:
https://pay.btcz.app/api/request_payment/:amount/:currency/:message/:seller_address/:customer_email/:srvPingback/:cliPingbackSuccess/:cliPingbackError/0
(:parameters are the gateway info to use for personnalisation)
:srvPingback
= The URL that the gateway GET once itās paid with success (state 5).
In WP-Woocommerce, I manage it like $srvPingbackUrl = $order->get_checkout_order_received_url();
URL that contain the secret phrase like https://theDomain.com/order/32/?WP_key=333fffabc So that the order can be updated.
:cliPingbackSuccess
and :cliPingbackError
= URL for the client redirection on success (state 5) and on error/expired (state 2)
The ending 0 param is for spped checkout or standard (1=speed)
Example:
https://pay.btcz.app/api/request_payment/2/USD/Hello/t1KhD2unS3KUjcVsANs5ySfxTVE9KTv6K4t/email%40test.test/http%3A%2F%2Fmysite.com%3A2222%2Fapi%2Ftest/http%3A%2F%2Fwww.worldartstamps.com/http%3A%2F%2Fbtcz.app/0
(The URL have to be encoded 2 time to awoid routing issue, I work on this)
It return a JSON string like that with the basic info about the gateway:
{
"id":"8bb30551-1eb9-4e5a-a056-5dd6e20dfe5b",
"address":"t1QuAwjsMb7654YhTPpYEfAvJygfdLN2FFJ",
"link":"bitcoinz:t1QuAwjsMb7654YhTPpYEfAvJygfdLN2FFJ?amount=3993.58593111&message=Hello",
"qr":"https://pay.btcz.app/generate_qr/bitcoinz%3At1QuAwjsMb7654YhTPpYEfAvJygfdLN2FFJ%3Famount%3D3993.58593111%26message%3DHello",
"qr_simple":"https://pay.btcz.app/generate_qr/bitcoinz:t1QuAwjsMb7654YhTPpYEfAvJygfdLN2FFJ?amount=3993.58593111"
}
The important param is the āidā. You will need it for retrieving the gateway status. On this stage, all information like the asked amount, currency, exchange rate, the 3 URL, seller address, ā¦ , are stored in the database. a new payment address (with QR) is generated that can be retrieved by query of the āqr_simpleā param : https://pay.btcz.app/generate_qr/bitcoinz:t1QuAwjsMb7654YhTPpYEfAvJygfdLN2FFJ?amount=3993.58593111
At this stage, a invoice is generated that can be show on this URL (with the id after invoice/):
Fetching Data from Existing Gateway
I make a check_payment/
GET call on the API as following:
https://pay.btcz.app/api/check_payment/:_id
:id
= The gateway āidā generated abow.
Example:
https://pay.btcz.app/api/check_payment/8bb30551-1eb9-4e5a-a056-5dd6e20dfe5b
It return a JSON string like that with the status info about the gateway:
{
"error":"gateway expired",
"generated":"t1QuAwjsMb7654YhTPpYEfAvJygfdLN2FFJ",
"btcz_expected":3993.58593111,
"btcz_actual":0,
"btcz_unconfirmed":0,
"currency":"USD",
"amount":2,
"timestamp_start":1540315982934,
"timestamp_now":1540317938657,
"timestamp_stop":1540317782934,
"state":2,
"err_callback_url":"http://btcz.app"
}
(in this example with an error: gateway expired)
You can GET this API URL (with the id) as many time as needed. in this case, the :srvPingback URL (with secret key) will never fire up. The :srvPingback URL only fire up on success (state 5). On success, this JSON string contain the "successURL":"https://mysite_or_IP/result/
param instead of err_callback_url param.
Important: The :srvPingback
(set in the gateway creation) is never returned in any JSON string. It fire up a GET to the set URL only once the invoice is paid. I only tested it in WordPress with this plugin : https://github.com/MarcelusCH/BTCz-Pay/blob/master/plugin/woocommerce3.4/wp-content/plugins/BTCz-gateway/btcz.php
So, I hope itās more clear
To answer you, @cryptorex, I donāt think itās needed to āPingbackā any other information. Because we know all needed info by the check_payment/
call. And normally the online store, like in Woocommerce, all this info are already linked with the sercret key (Woocommerce_CheckOut_URL / ?WP_key=xyz123). Once this URL is fetched, it should update all the staff ?
But I can append some info after the :srvPingback
URL like: &id=xxxx-xxxx-xxxxxx-xxxxxx&paid_amound=1234 ā¦ Is it really needed ?
Actually, the gateway send nothing back by expired gateway (excepting for client redirection).
Yeah Iām having trouble explaining what I mean.
Basically, payment gateways are supposed to fire off a ānotificationā to the merchant when payment completes or expires - merchants donāt typically keep running API calls to check status of payments.
This is called IPN (Instant Payment Notification). So for example the merchant has an API endpoint that receives a payload from the gateway that tells them a few different things like: status, amount paid, custom field, secret.
This process is called pingback - cause it āpings backā the merchant on completion or expiration. Does that make sense?
I believe you are confusing āPingbackā with āReturnURLā. They are different things. ReturnURL redirects the person after error/complete.
Pingback is the URL to the merchants API endpoint that waits for the status information to be āpinged backā to it.
Thanks @cryptorex for the explications about IPN pingback (in discord, the other night).
I updated all the staff by adding the secret key generated by the gateway, and the return of it in the JSON by the request_payment/ call. I also append it to the IPN pingback URL as following (paid and expired):
https://yourDomaine.com/yourPath/?and=yourParam&secret=01234abcd&state=5
or
https://yourDomaine.com/yourScript.php?secret=01234abcd&state=2
I also updated the web site with the new informations, could you please have a look in the API description if itās understandable: https://pay.btcz.app/
I took this opportunity to make some parameters optional (like the secret, it can be specified, but if not, it will be generated by the gateway).
List of updates (v0.1.3)
- Added secret phrase return in JSON by request_payment/ call.
- Added invoice state and secret param in IPN pingback.
- added IPN pingback by expired state=2.
- Manage optional parameters by query string (?) instead of router path (/).
- Solved double url encoding issue.
- Rewrite of some code parts.
- Updated Web UI API explication with examples.
- Added website icon.
@Marcelus great work once again!
Iāve tested ipn pingback and it works perfectly as expected!
API instructions only few things I found that could be misleading but is very minor:
-
The param in the API route example shows sellerAddress but it should be only āsellerā.
-
Do we still have to urlencode two times? Iām still doing it twice and I think its still required but you removed that NOTE that says we need to urlencode twice. If we donāt then I need to re-test.
-
This is just cosmetic but I think there is a character error ācurrencyā doesnāt show in the example right here:
Iāve moved one of my clients sites to testing the gateway in a live environment - I think its ready to start live testing so I"m doing that now. It seems to be working great.
Every day, we learn somthing new
¤ is " Ā¤ " in html code. I hade to change it to &currency
between the <pre>
tag.
About the simple or double URL encoding, I was to happy to see that itās solving it self.
But only at halfā¦
- By using the query string (?expected, ¤cyā¦) a simple URL encoding work.
- By using the full route path (/:expected/:currency/ā¦) a double URL encoding is needed.
(I have no idee wy!?)
I also updated as well the API route and notes info.
Also great for testing ! I will update the WP-woocommerce plugin, and soon itās done, I also move an WordPress test site to live too.
@everyone who owns or experiences with a website, you could do the same.
I will gladly support you regarding the use and integration (Discord or here) of the gateway in your site. In addition, all actions (gateway creation, cancellation, payment, pingback, ā¦) are logged in order to be able to analize them when necessary.
Just a small update (v0.1.3 beta):
- Added a Cubecart payment plugin (check topic here).
- Added postMessage(Callback URL) in invoice.html for cross-domain data transfer (iFrame->window.top).
The postMessage(Callback URL) can be listened by the top window by someting like:
window.addEventListener('message', function(event) {
if (~event.origin.indexOf('pay.btcz.app')) {
setTimeout(function() {
window.top.location.href = event.data;
}, 3000);
}
});
The next version will be a stable production gateway. I have first to build a new test&dev environment. It will be by mid-end November.
Gateway uptade to version 0.2.0 (production)
I just updated the pay.btcz.app gateway to a stable production version.
The main updates are:
- Added a FAQ page with also with explanation about BitcoinZ
- Added Getting started page with PHP code example
- Limit maximum opened gateway (expired and paid are not count) per client (IP) to max 30
- Added new currencies support : āUSDā, āEURā, āBTCā, āCHFā, āGBPā, āRUBā, āAUDā, āCADā, āZARā, āJPYā
- Automatic refund if more paid as expected or if only partially paid
- Added contact page with form.
- Some code rewrite.
You will notice that I added different links to existing sites about BitcoinZ, such as: btcz.me, the main site, the forum, etcā¦ I would be happy to get feedback about the FAQ page and in general.
I donāt tested the existing plugins but the API calls are same as before.
Enjoy this free service !
DEMO:
Woooow @Marcelus it looks like the best payment gateway what I have seen so far!
Really good job! Wish I could test it, but better wish FastTech gonna use it soon! <3