Community hosted payment gateway

E-Commerce
#8

Wow! Amazing job Marcelus! Seems to be a better alternative, which we can improve and use for the others!

1 Like
#9

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/

3 Likes
#10

I hope @Akta86 returns back soon and continue.

1 Like
#11

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.

2 Likes
#12

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).
4 Likes
#13

awesome I will test!

3 Likes
#14

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…

2 Likes
#15

Yes there is a static IP (I send it to you in private).
@kovach, could you help with other plugins ?

#16

@Marcelus yes I could, I just have to manage my very limited free time…
After magento we can check other plugins…

1 Like
#17

Nice to see you back here! :slight_smile:thank you very much for Magento Bro!
All of our devs hard work should be gifted!

1 Like
#18

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 :ok_hand:

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

image
image1101×242 9.18 KB

4 Likes
#19

@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.

1 Like
#20

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 :sweat_smile:

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).

1 Like
#21

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.

3 Likes
#22

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.
3 Likes
#23

@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:

  1. The param in the API route example shows sellerAddress but it should be only ‘seller’.

    image
    image1142×92 6.58 KB

  2. 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.

  3. This is just cosmetic but I think there is a character error ‘currency’ doesn’t show in the example right here:

    image
    image1167×68 7.01 KB

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.

2 Likes
#24

Every day, we learn somthing new :slight_smile:

&curren is " ¤ " in html code. I hade to change it to &amp;currency between the <pre> tag.

About the simple or double URL encoding, I was to happy to see that it’s solving it self.
:sweat_smile: But only at half…

  • By using the query string (?expected, &currency…) 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.

:point_right: Also great for testing ! :muscle: 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.

2 Likes
#25

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.

#26

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:

3 Likes
#27

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

1 Like