Payments gateway

Obyte can accept Byte payments for you and notify you when the Bytes have arrived to your account. There is also an easy-to-setup Wordpress/Woocommerce plugin.

Requirements

• A Obyte light wallet to provide us with your merchant Obyte address (you do not need to run the heavy full wallet, we are running it for you). Download the wallet from https://obyte.org.

• If you want to use our Woocommerce plugin skip reading now and go to: https://wordpress.org/plugins/woobytes-gateway/

• Upon going live a merchant_id and a secret_key. Contact us on https://obyte.org/discord #merchants channel to get your merchant_id and you secret_key.

Integration process

Step 1: Either in test mode or in live mode, customize the Obyte quick payment button script with your merchant parameters and insert it in your checkout web page. Obyte quick payment button init script has to be inserted in the header section of your checkout page and the button itself can be displayed anywhere on the page in a Div container. The test mode triggers the whole notification process except there is no real payment. Once you are done with your tests, switch to live mode by changing the "mode" parameter from "test" to "live" in the button init script. See example.html: https://github.com/tarmo888/bbfm/tree/master/bbfm_www/example

Step 2: We notify you (upon your choice), either by mail and/or by a GET or a POST to your server, when a payment for your sale has arrived, we simultaneously send you the payment to your merchant address, minus our fee. At this stage you receive a first notification with an unconfirmed "result" field. When the payment is confirmed by the network you receive a second notification with a ok "result" field. Such notification of a confirmed payment typically takes between 5 to 15 minutes from the customer click to pay (live mode) or 1 minute (in test mode). You then have to handle the notification on your end so that you actualy process your customer order. You can process the delivery as soon as you received the ok notification (processing on unconfirmed notification is at your own risk!). In any case always check on your end that received_amount does match amount_asked_in_B before processing the order or contact your customer for missing Bytes (the event of an incomplete payment is not an error case on our end but it must be one on your end).

Parameters

Step 1: Obyte payment button field list

• order_UID (mandatory): Your merchant order ID (should match /^[a-zA-Z0-9-]{4,20}$/).

• merchant_return_url (optional): The full URL we will POST or GET to notify you a payment arrived.

• mode_notif (optional, default is get): Shall we GET or POST the notification to your server? (should match get | post).

• currency (optional, default B): Currency from which convert the amount into Bytes (should be B (for Bytes), BTC, ETH, USD, EUR, PLN, KRW, GBP, CAD, JPY, RUB, TRY, NZD, AUD, CHF, UAH, HKD, SGD, NGN, PHP, MXN, BRL, THB, CLP, CNY, CZK, DKK, HUF, IDR, ILS, INR, MYR, NOK, PKR, SEK, TWD, ZAR, VND, BOB, COP, PEN, ARS, ISK). Conversion is done automaticaly in real time at rates from CoinPaprika.

• merchant_email (optional): Fill in your email address if you want to be notified by email when payment arrives OR to get an alert email if we were not able to GET or POST to notify you on your merchant_return_url. Take care to whitelist emails from "[email protected]" (you can usually do that by adding this email to your contacts).

• amount (mandatory): The amount charged to your customer in currency (should match /^[0-9]+.?[0-9]*$/). Minimum amount is 1500 Bytes (or its equivalent in currency) Maximum amount is 1000 GBytes.

• byteball_merchant_address (mandatory): Your unique Obyte merchant address to receive your payment.

• merchant_id (mandatory): In test mode merchant_id is test_merchant. Contact us on https://obyte.org/discord #merchants channel to get a merchant id when you first go live.

• mode (mandatory): live | test. Are you testing the implementation or are you running the Obyte payment button from a production server? (should match live or test and will be returned as is on merchant_return_url).

• attach (optional): free text field (255 chars). Will be returned as is for your own convenience (must match /^[a-zA-Z0-9_.@,=?& -]{0,255}$/).

• qrcode (optional): you can here indicate your own qrcode url mask to use the qrcode api of your choice, using {text} as url placeholder. By default, the Google QRCode API is used, that is to say the value is: 'https://chart.googleapis.com/chart?chs=200x200&cht=qr&chl={text}&chld=H' But you can change it and choose for instance the Chinese liantu API by setting the value: 'http://qr.liantu.com/api.php?text={text}&w=100'

Step 2: Returned field list on merchant_return_url

• mode: live | test

  WARNING! WARNING! WARNING! Always check this field as in test mode the notification of payment received is always sent for integration and test purpose without any effective payment. Do not use the test mode on a production merchant server.

• result: nok | incoming | unconfirmed | ok

  'nok': check error_msg for text error.

  'incoming': the payment has been sent to us by your customer but it is still waiting for network confirmation.

  'unconfirmed': the payment has been sent to you but it is still waiting for network confirmation.

  'ok': final step. The payment unit we sent to you has been confirmed by the network. Process the order on your end.

• error_msg (occurence: 1 on result=nok or 0): human readable text field

• order_UID: Your merchant order ID

• currency: B (for Bytes, see rest above).

• amount_asked_in_currency (occurence: 0 on currency=B or 1): decimal

  WARNING! WARNING! WARNING! Always check amount_asked_in_currency does match the amount of the order in your own database and in your expected currency.

• currency_B_rate (occurence: 0 on currency=B or 1): decimal

• amount_asked_in_B: integer (in Bytes)

• fee: our fee (in Bytes)

• received_amount: the amount we received (in Bytes).

  WARNING! WARNING! WARNING! check on your end that received_amount does match amount_asked_in_B before processing the order. Contact your customer if some Bytes are missing from what you expected (the event of an incomplete payment is not an error case on our end but it must be one on your end).

• receive_unit: the DAG unit that shows the payment from your customer to our Obyte address.

• amount_sent: the amount sent to your byteball_merchant_address (received_amount minus fee)

• unit: the DAG unit that shows the payment from our Obyte address to your byteball_merchant_address

• sha256_digest: the digest of the notification is computed as sha256(secret_key+order_UID+merchant_return_url+merchant_email) where '+' means concatenate.

  WARNING! WARNING! WARNING! You SHOULD re-calculate on your end the sha256 digest on each notification to check if it does match sha256_digest. An attacker could POST or GET to your merchant server a false notification but he will never be able to compute a correct sha256_digest. In test mode secret_key is 134c8nfWK4XrrfkgN1UJ9ytqae76d7uDbs.

• attach: free text field (255 chars) returned "as is" from step 1 for your own convenience.

Note: if you filled in the optional merchant_email on step 1 you will receive the same information in an email plus possible alert email when - for any reason - if we were not able to notify you on merchant_return_url (for example a server time out on your end). We advise you to provide the merchant_email in order to receive such alert emails. We strongly advise you to whitelist [email protected]