BTCZ Open-source Payment Gateway

Creating a gateway

• API ROUTE:

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

• GET Example full router path:

  https://pay.btcz.app/api/request_payment/0.005/BTCZ/wheres%20the%20money%20lebowski/t1VYSo8VtpKMm1SUwp1KJHbqrtfqj7tgpaE/[email protected]/https%253A%252F%252Fwww.google.com/https%253A%252F%252Fwww.google.com/https%253A%252F%252Fwww.google.com/0/01234abcd

• GET Example with query string:

  https://pay.btcz.app/api/request_payment/?expect=1.235&currency=BTCZ&message=wheres%20the%20money%20lebows[email protected]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:

  https://pay.btcz.app/api/request_payment/?
    expect=0.005&
    currency=BTCZ&
    message=wheres%20the%20money%20lebowski&
    seller=t1VYSo8VtpKMm1SUwp1KJHbqrtfqj7tgpaE&
    [email protected]&
    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
  

• Notes:
  • By using full router path, all parameters are mandatory.
  • By using query string, some parameters are optional.
  • The SpeedSweep can only be used up to 1000 BTCz.
  • If the secret is not set, the gateway will generate a 20 bytes hex string.
  • Encode the URL's to awoid routing issue:
  • Simple URL encoding by using GET with query string.
  • Double URL encoding by using GET with full router path.
• 
  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.
• 
  Sample JSON Response:

  {
    "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=14.77818972"
  }
  

• Invoice URL template:

  https://pay.btcz.app/invoice/4d30ed16-d729-4ee5-aeaa-d6787e79b90c

Fetching Data from Existing Gateway

• API ROUTE:

  /api/check_payment/:id

• GET Example:

  https://pay.btcz.app/api/check_payment/4d30ed16-d729-4ee5-aeaa-d6787e79b90c

• Sample Response:

  {
    "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] "tx": {"tx":"TX Hex string","broadcast":{"result":"broadcast Hex string","error":null,"id":"621680ed-ae85-4db3-bd84-58d5ed2edff8"}}}
    [optional] "success_callback_url":"https://mysite_or_IP/result/?Hello=1",
    [optional] "err_callback_url":"https://mysite_or_IP/result/?Hello=0"
  }
  

• Notes:
  • The [optional] are depending on the state.
  • The speed_sweep_fee is in %. (5% for speed checkout, no extra fee for standard checkout)
  • Use the "id" from the request_payment/ call JSON return.

Other Informations

• States explained
  • 0: Awaiting payor to continue
  • 1: Awaiting payment
  • 2: Gateway expired
  • 5: Payment & IPN Pingback completed
• 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.

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

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

• More:
  • You will only receive a callback URL in the JSON with states 2-errURL and 5-successURL
  • Standard tx fee: 0.0001
  • TX confirmation count: 2
  • State 2 and 5 execute the :ipnPingback URL (on server side)