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:
(: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.
: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)
(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:
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:
:id = The gateway “id” generated abow.
It return a JSON string like that with the status info about the gateway:
(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.
: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).