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).
Already 2 weeks, but here is a beta version of the BTCZ open-source payment gateway! 
thank you very much for Magento Bro!
