Introduction
Welcom to HivePay.io
Our goal is to provide a simple interface to allow sellers of all types to accept Hive and Hive-Engine Tokens as payment!
This guide will help you get started setting a form to accept payment, and how to use our Instant Payment Notification (IPN) system to automatically update your site accordingly.
Looking for help? Join our Discord
Couldn’t find what you are looking for?
Why not join our Discord and let us help you.
What's New
Version 2 has brought a lot of improvements to HivePay. This list highlights some of the bigger changes:
- New Payment Portal - All payments are now done through
https://hivepay.io/pay/
- History / Subscription Management - Users can now see their HivePay history and manage their current subscriptions at
https://hivepay.io/history/
- Taxes - Sellers are able to define item tax on all product sales
- Seller focused purchase page - We removed the HivePay logo at the top and put the seller information front and center
- Seller Logo - Sellers can add their logo to any form and it will display prominently at the top the purchase page for brand recognition for the buyer
Purchase Payment
Purchase payments are used normally when a customer is purchasing or subscribing to a single item. This method is effective for most membership type websites as well as any website that does not have a cart functionality.
- Payment Flow
This depicts the purchase payment flow from initial customer interaction through Instant Payment Notification (IPN) and providing the product to the customer.
Seller builds form using elements or form builds and puts form on web page
Customer goes to web page, clicks on form button, and is directed to HivePay to complete purchase
HivePay confirms transaction through Hive and sends IPN to notify_url
Customer completes purchase and is directed to return_url or cancel_url if cancelled
Website verifies and confirms IPN data against local database
Website supplies product to customer (email, webpage, etc..)
- Form Builder
Our form builder has simplified the creation of html forms. Click on the button, input all required elements, select a button to use, and copy and paste the code on your website!
- Form Elements
Create a form with the minimum required elements, a method of post
and an action of https://hivepay.io/pay/
.
- Sellers Hive Username in all lowercase without the leading @.
- Seller/Business name. Shown on header of purchase page if no image.
- https URL to Seller/Business logo. Shown on header of purchase page.
- If a valid email, will receive email updates on purchase and any IPN issues found.
- Specifies memo when tokens are transferred to seller. Use HIVEBUYER to show buyers Hive username.
- Base currency for purchase. Can be approved fiat or Hive/Hive-Engine Token.
- Comma separated list of Hive/Hive-Engine Token seller will accept payment in.
- Price in base_currency of item being purchased.
- Name of item being purchased. Shows in memo to buyer on purchase.
- https URL to image of item being purchased shown at 100px x 100px.
- Amount in base_currency of taxes to be applied to purchases.
- Quantity of item being purchased.
- Amount in base_currency of shipping price to be applied to purchases.
- Short description of item(s) being purchased.
- https URL to receive Instant Payment Notification (IPN). Sent immediately upon confirmation (transaction verification) of payment.
- https URL buyer is redirected to after purchase completion. Buyer is redirected before payment is confirmed. All Hive and Hive-Engine transactions take up to 10 seconds to confirm. IPN is sent immediately upon confirmation. Do not use return_url as a confirmation of payment.
- https URL buyer is redirected to if they decide to cancel the purchase.
- Name shown on cancel button, default is "Seller". Button displays: Cancel and return to "cancel_url_name".
light,medium,dark
- Bacgkround color of purchase page.
<form method="post" action="https://hivepay.io/pay/"> <input type="hidden" name="merchant" value="blainjones"> <input type="hidden" name="merchant_name" value="My T-Shirts"> <input type="hidden" name="merchant_image" value="https://website.com/logo.png"> <input type="hidden" name="merchant_email" value="payments@website.com"> <input type="hidden" name="merchant_memo" value="Purchase Made By HIVEBUYER"> <input type="hidden" name="base_currency" value="USD"> <input type="hidden" name="pay_currency" value="CTP,HIVE,TOP10T"> <input type="hidden" name="amount" value="4.75"> <input type="hidden" name="item_name" value="Custom T-Shirt"> <input type="hidden" name="item_image" value="https://website.com/tshirt1.png"> <input type="hidden" name="item_tax" value="0.34"> <input type="hidden" name="quantity" value="1"> <input type="hidden" name="shipping" value="4.95"> <input type="hidden" name="description" value="Awesome Custom T-Shirt Design"> <input type="hidden" name="notify_url" value="https://website.com/notify/"> <input type="hidden" name="return_url" value="https://website.com/thank_you/"> <input type="hidden" name="cancel_url" value="https://website.com/cancel/"> <input type="hidden" name="cancel_url_name" value="My T-Shirts"> <input type="hidden" name="background" value="medium"> </form>
- Third Party Elements
In addition to the form elements, seller can add third party elements to transfer tokens to a third party. Third party elements are used when you need to send a portion of the amount received to a different person and want to automate that as well. There is no additional charge for third party usage. All elements are required if the purchase includes a third party. They are omitted otherwise.
- Hive username of the third party in all lowercase and without the leading @.
- Percent in decimal value that the third party will receive. 99% max (0.01-99)
10% = 10, 45% = 45, 92.5% = 92.5
- Memo included when tokens are transferred to the third party.
<form method="post" action="https://hivepay.io/pay/"> <input type="hidden" name="merchant" value="blainjones"> <input type="hidden" name="base_currency" value="USD"> <input type="hidden" name="pay_currency" value="CTP,HIVE,TOP10T"> <input type="hidden" name="amount" value="4.75"> <input type="hidden" name="item_name" value="Custom T-Shirt"> <input type="hidden" name="notify_url" value="https://website.com/notify/"> <input type="hidden" name="return_url" value="https://website.com/thank_you/"> <input type="hidden" name="cancel_url" value="https://website.com/cancel/"> <input type="hidden" name="third_party" value="jongolson"> <input type="hidden" name="third_party_percent" value="10"> <input type="hidden" name="third_party_memo" value="Commission for Custom T-Shirt"> </form>
- Additional Elements
In addition to the form elements, sellers can add custom elements in order to track specific meta data or item numbers as needed.
<form method="post" action="https://hivepay.io/pay/"> <input type="hidden" name="merchant" value="blainjones"> <input type="hidden" name="base_currency" value="USD"> <input type="hidden" name="pay_currency" value="CTP,HIVE,TOP10T"> <input type="hidden" name="amount" value="4.75"> <input type="hidden" name="item_name" value="Custom T-Shirt"> <input type="hidden" name="notify_url" value="https://website.com/notify/"> <input type="hidden" name="return_url" value="https://website.com/thank_you/"> <input type="hidden" name="cancel_url" value="https://website.com/cancel/"> <input type="hidden" name="custom" value="BRD839"> <input type="hidden" name="item_number" value="17"> </form>
- Javascript Library
This library was created and submitted by @wehmoen.
class HivePay { constructor(merchant) { this.merchant = merchant; } setItemName(name) { this.itemName = name; return this; } setItemDescription(description) { this.itemDescription = description; return this; } setNotifyUrl(url) { this.notifyUrl = url; return this; } setReturnUrl(url) { this.returnUrl = url; return this; } setAmount(amount) { this.amount = amount return this; } setBaseCurrency(currency = "USD") { this.baseCurrency = currency; return this; } setPayCurrencies(currencies) { this.payCurrency = Array.isArray(currencies) ? currencies.join(',') : currencies; return this; } submit() { const form = document.createElement('form'); form.style.display = 'none'; form.method = 'POST'; form.action = 'https://hivepay.io/pay/'; const merchant = document.createElement('input'); merchant.type = 'hidden'; merchant.name = 'merchant'; merchant.value = this.merchant; form.appendChild(merchant); const itemName = document.createElement('input'); itemName.type = 'hidden'; itemName.name = 'item_name' itemName.value = this.itemName; form.appendChild(itemName); const itemDescription = document.createElement('input'); itemDescription.type = 'hidden'; itemDescription.name = 'description'; itemDescription.value = this.itemDescription; form.appendChild(itemDescription); const notifyUrl = document.createElement('input'); notifyUrl.type = 'hidden'; notifyUrl.name = 'notify_url'; notifyUrl.value = this.notifyUrl; form.appendChild(notifyUrl); const returnUrl = document.createElement('input'); returnUrl.type = 'hidden'; returnUrl.name = 'return_url'; returnUrl.value = this.returnUrl; form.appendChild(returnUrl); const amount = document.createElement('input'); amount.type = 'hidden'; amount.name = 'amount'; amount.value = this.amount; form.appendChild(amount); const baseCurrency = document.createElement('input'); baseCurrency.type = 'hidden'; baseCurrency.name = 'base_currency'; baseCurrency.value = this.baseCurrency; form.appendChild(baseCurrency); const payCurrencies = document.createElement('input'); payCurrencies.type = 'hidden'; payCurrencies.name = 'pay_currency'; payCurrencies.value = this.payCurrency; form.appendChild(payCurrencies); document.children[0].appendChild(form) form.submit(); } }
- Usage
const HP = new HivePay('wehmoen'); HP .setItemName('test item') .setItemDescription('This is a test') .setNotifyUrl('https://example.com/notify/') .setReturnUrl('https://example.com/thankyou/') .setAmount('2.00') .setBaseCurrency() .setPayCurrencies(['HIVE', 'LEO', 'SPORTS']); document.getElementById('payWithHivePay').onclick = function () { HP.submit(); }
- Usage
const HP = new HivePay('wehmoen'); HP .setItemName('test item') .setItemDescription('This is a test') .setNotifyUrl('https://example.com/notify/') .setReturnUrl('https://example.com/thankyou/') .setAmount('2.00') .setBaseCurrency() .setPayCurrencies(['HIVE', 'LEO', 'SPORTS']); document.getElementById('payWithHivePay').onclick = function () { HP.submit(); }
Checkout Payment
Checkout payments are used normally in conjuction with a website that has a cart function. Checkout is meant for use when customers are purchasing multiple items at one time. Subscriptions are unavailable with checkout.
- Checkout Flow
This depicts the purchase payment flow from initial customer interaction through Instant Payment Notification (IPN).
Customer builds cart of products and begins checkout process
Website uses HivePay API to create a checkout and directs customer to HivePay Checkout
HivePay confirms transaction through Hive and sends IPN to notify_url
Customer completes purchase and is directed to return_url or cancel_url if cancelled
Website verifies and confirms IPN data against local database
Website supplies product to customer (email, webpage, etc..)
- Checkout API
Use the checkout API at https://api.hivepay.io/
by sending a JSON with all required elements. If successful, you will receive a JSON response with an id
value that represents the checkout id for the customer.
With the checkout id, sellers can redirect the customer to https://hivepay.io/pay/?cid=CHECKOUTID
replacing CHECKOUTID with the checkout id received.
If there are any errors to the request, you will receive a JSON response with an errors
array. Fix any issues and resend to receive the checkout id.
- Checkout Elements:
- Set as "2" for HivePay v2.
- Array of elements in the checkout form.
Sub Elements:
- Sellers Hive Username in all lowercase without the leading @.
- Seller/Business name. Shown on header of purchase page if no image.
- https URL to Seller/Business logo. Shown on header of purchase page.
- If a valid email, will receive email updates on purchase and any IPN issues found.
- Specifies memo when tokens are transferred to seller. Use HIVEBUYER to show buyers Hive username.
- Specifies memo that is posted on the blockchain transaction from the purchaser.
- Base currency for purchase. Can be approved fiat or Hive/Hive-Engine Token.
- Comma separated list of Hive/Hive-Engine Token seller will accept payment in.
- https URL to receive Instant Payment Notification (IPN). Sent immediately upon confirmation (transaction verification) of payment.
- https URL buyer is redirected to after purchase completion. Buyer is redirected before payment is confirmed. All Hive and Hive-Engine transactions take up to 10 seconds to confirm. IPN is sent immediately upon confirmation. Do not use return_url as a confirmation of payment.
- https URL buyer is redirected to if they decide to cancel the purchase.
- Name shown on cancel button, default is "Seller". Button displays: Cancel and return to "cancel_url_name".
- Background color of purchase page.
- Array of items to be purchased
Sub Elements:
- Name of item being purchased. Shows in memo to buyer on purchase.
- Short description of item being purchased,
null
if no description.
- Price in base_currency of item being purchased.
- Quantity of item being purchased.
- https URL to image of item being purchased shown at 100px x 100px,
null
if no image.
- Amount in base_currency of shipping price to be applied to item.
- Amount in base_currency of taxes to be applied to item.
- Use "name":"value" format for all items. Leave array empty if none.
- Use "name":"value" format for all items. Leave array empty if none.
- If paying a third party set third_party->third_party to true otherwise false.
Sub Elements:
-
true
or false
to use third_party.
- Hive username of third party in lowercase without the leading @,
null
if third_party is false
.
- Percent in decimal value that the third party will receive. 99% max (0.01-99),
null
if third_party is false
.10% = 10, 45% = 45, 92.5% = 92.5
- Memo included when tokens are transferred to third party,
null
if third_party is false
.
{ "version": 2, "hivepay.checkout.create": { "merchant": "blainjones", "merchant_name": "Blain Jones", "merchant_image": "https://website.com/logo.png", "merchant_email": "payments@website.com", "merchant_memo": "Payment Made By HIVEBUYER", "base_currency": "USD, "pay_currency": "CTP,HIVE,TOP10T", "notify_url": "https://website.com/notify/", "return_url": "https://website.com/thank_you/", "cancel_url": "https://website.com/cancel/", "cancel_url_name": "Store Name", "background": "light", "items": [ { "name": "Custom T-Shirt", "description": "Specific Design Custom Shirt", "amount": "24.50", "quantity": "1", "image": "https://website.com/image.png", "shipping": "10.00", "tax": "0.95" }, { "name": "Custom T-Shirt", "description": "Specific Design Custom Shirt", "amount": "24.50", "quantity": "1", "image": "https://website.com/image.png", "shipping": "10.00", "tax": "0.95" } ], "metadata": { "shirt_req": "17348756" }, "additional_fields": { "item_number": "4" }, "third_party": { "third_party": true, "username": "jongolson", "percent": "10", "memo": null } } }
- Success Response
{ "id": 2fq43d, "hivepay.checkout.create": "success" }
- Error Response
{ "errors": [ "notify_url must be https", "item[0][amount] must be in decimal format (e.g. 0.00)", ], "version": 2, "hivepay.checkout.create": { "merchant": "blainjones", "merchant_name": "Blain Jones", "merchant_image": "https://website.com/logo.png", "merchant_email": "payments@website.com", "merchant_memo": "Payment Made By HIVEBUYER", "base_currency": "USD, "pay_currency": "CTP,HIVE,TOP10T", "notify_url": "http://website.com/notify/", "return_url": "https://website.com/thank_you/", "cancel_url": "https://website.com/cancel/", "cancel_url_name": "Store Name", "background": "light", "items": [ { "name": "Custom T-Shirt", "description": "Specific Design Custom Shirt", "amount": "thiswillerror", "quantity": "1", "image": "https://website.com/image.png", "shipping": "10.00", "tax": "0.95" }, { "name": "Custom T-Shirt", "description": "Specific Design Custom Shirt", "amount": "24.50", "quantity": "1", "image": "https://website.com/image.png", "shipping": "10.00", "tax": "0.95" } ], "metadata": { "shirt_req": "17348756" }, "additional_fields": { "item_number": "4" }, "third_party": { "third_party": true, "username": "jongolson", "percent": "10", "memo": null } } }
Instant Payment Notification (IPN)
IPN is used to tell your website or app that a purchase is successful and complete. Notifications are sent instantly upon confirmation of every transaction.
- Notifications
Upon successful verification of a transaction, HivePay will send an IPN as a JSON to the specified notify_url. All of the original form or checkout data will be included in the IPN.
There will be two additional pieces of information with the JSON object, hivepay_ipn and payment_details. hivepay_ipn depicts that this is a notification, payment details is an array depicting all of the payment information.
{ "hivepay_ipn":"notification", "payment_details":{ "payment_successful":true, "txid":"c9db8c6cd3995405a557effe42800e30fedc02f5", "merchant":"blainjones", "buyer":"someaccount", "token":"HIVE", "token_amount":"0.603", "fee":"0.002", "amount_received":"0.002" }, *FORM/CHECKOUT DATA WILL BE LISTED HERE* }
- Verification
Use IPN Verification to verify the data you received at your notify_url is true and valid from HivePay. Send a JSON POST request to https://api.hivepay.io/
with the information listed below, and you will receive a success or error response.
Required verification elements: version,ipn_verification,txid,merchant,buyer,token,token_amount,fee,amount_received
A success response will be a JSON object containing two elements: verify_hivepay and verify_txid. An error response will contain a single array error and the original request.
Verification Elements
{ "version": 2, "ipn_verification": true, "txid": "c9db8c6cd3995405a557effe42800e30fedc02f5", "merchant": "blainjones", "buyer": "someaccount", "token": "HIVE", "token_amount": "0.603", "fee": "0.002", "amount_received": "0.601" }
- Success Response
{ "verify_hivepay": true, "verify_txid": "c9db8c6cd3995405a557effe42800e30fedc02f5" }
- Error Response
{ "errors": [ "No transactions found that match that criteria", "buyer MUST be included", ], *ORIGINAL REQUEST DATA WILL BE LISTED HERE* }
- Confirmation
Once you have verified the information is true and from HivePay, you should confirm at least two things: merchant is your Hive username and token_amount is correct.
To confirm the merchant is correct, just add an if statement saying that if your defined merchant is the same as the verification merchant, merchant is confirmed.
You are able confirm token amount by using our API endpoint https://api.hivepay.io/
. Create a JSON object with version, convert_token, base_currency, return_currency, and amount. You will receive a response with return_amount and return_currency.
To confirm the amount is correct, just add an if statement saying that if your item amount is the same as the verification amount, amount is confirmed.
Because of the volatile nature of cryptocurrency, you will want to allow limits to the left and right of your primary or base currency.
- Confirm Token Amount
{ "version": 2, "convert_token": true, "base_currency": "HIVE", "return_currency": "USD", "amount": "0.603" }
- Confirm Token Amount Response
{ "return_amount": "0.50", "return_currency": "USD" }
Payment Buttons
Use any of the buttons below in conjunction with a purchase or checkout.




























Base Fiat Currencies
This is the current list of accepted fiat currencies to be used as base_currency in your purchase or checkout. List is updated automatically as new fiat is added.
USD | AED | AFN | ALL | AMD | ANG | AOA | ARS | AUD | AWG |
AZN | BAM | BBD | BDT | BGN | BHD | BIF | BMD | BND | BOB |
BRL | BSD | BTC | BTN | BWP | BYN | BZD | CAD | CDF | CHF |
CLF | CLP | CNH | CNY | COP | CRC | CUC | CUP | CVE | CZK |
DJF | DKK | DOP | DZD | EGP | ERN | ETB | EUR | FJD | FKP |
GBP | GEL | GGP | GHS | GIP | GMD | GNF | GTQ | GYD | HKD |
HNL | HRK | HTG | HUF | IDR | ILS | IMP | INR | IQD | IRR |
ISK | JEP | JMD | JOD | JPY | KES | KGS | KHR | KMF | KPW |
KRW | KWD | KYD | KZT | LAK | LBP | LKR | LRD | LSL | LYD |
MAD | MDL | MGA | MKD | MMK | MNT | MOP | MRO | MRU | MUR |
MVR | MWK | MXN | MYR | MZN | NAD | NGN | NIO | NOK | NPR |
NZD | OMR | PAB | PEN | PGK | PHP | PKR | PLN | PYG | QAR |
RON | RSD | RUB | RWF | SAR | SBD | SCR | SDG | SEK | SGD |
SHP | SLL | SOS | SRD | SSP | STD | STN | SVC | SYP | SZL |
THB | TJS | TMT | TND | TOP | TRY | TTD | TWD | TZS | UAH |
UGX | UYU | UZS | VES | VND | VUV | WST | XAF | XAG | XAU |
XCD | XDR | XOF | XPD | XPF | XPT | YER | ZAR | ZMW | ZWL |
Crypto Currencies
This is the current list of accepted Hive and Hive-Engine token that can be used as pay_currency. List is updated automatically as long as the token has an https image, and a value above $0.00.
HIVE | HBD | BEE | SWAP.HIVE | ORB | ALPHA | BETA | UNTAMED | DEC | SWAP.BTC |
SWAP.HBD | SWAP.BTS | NEOX | NEOXAG | LASSECASH | BPC | JAHM | EGG | CCC | BUILDTEAM |
RECOIN | STEM | TIXM | CTP | CTPM | QBEE | BEER | CHARY | LIT | VIMM |
EXOFUEL | MPATH | M | WEED | LOTUS | SAND | AWRE | SPORTS | SIM | LEOMM |
ENGAGE | DUCAT | PESOS | ATOM | SOL | AFIT | AFITX | BLQ | INFOWARS | WEEDMM |
WEEDM | EEK | BROS | CRYPTEX | SPACO | SUFB | KANDA | SPACOM | ARCHON | MEME |
CAT | ARCHONM | BTCMYK | SPI | PALMM | PALM | LOVE | PAL | EDENBUXX | LIST |
HSC | WLS | VIP | MOOBEE | FOX | FQX | ECU | DIY | HUSTLER | HUSTLERM |
ECO | THS | GAMER | PLANET | GIFT | HBT | SELF | PLUS | SMOKE | PIXEL |
BEECASH | BEEHIVE | BRO | BBB | TRPY | TRPN | PHO | HEART | DAT | SHARE |
NONANONE | SPT | DHEDGE | ANTS | ENTRY | PONZI | ASH | BLOG | COIN.HONEY | SMLN |
SWAP.ETH | TKN | DSL | DEIA | GFS | LBI | LEOG | BBH | INDEX | PAK |
SEX | BBD | YIELDBONDA | CRNM | MILF | ATX | INDO | DREIT | OMA | MOTA |
SOULS | LBIM | COM | TIME | HYPNO | TOTEMC | TOTEMR | TOTEME | TOTEML | COPPERS |
CM | BUDS | X | QUE | LEGEND | HKWATER | ALIVE | PIMP | UTOPIS | LUV |
LOTUSM | SDB | OST | TLNT | LEN | LENM | REVX | VIBES | VIBESM | POB |
ALIVEM | CUB | BST | QUILL | EDSM | FREEROSS | PIZZA | LERN | SH | BHT |
XTC | CINE | SWAP.BAT | SWAP.USDT | CENT | SPS | STARPRO | VFT | CD | CROP |
CL | MUT | MEOWLEO | STAR | DREEM | SWAP.BNB | AWESOME | REAL | RUBY | ZDG |
DECR | CUNT | BCN | BYT | SMANA | NFTC | NFTG | FDOGE | CCH | LVL |
CENTG | FOUNDATION | WINEX | WAIV | LTHN | ONEUP | OPG | DOJO | SWAP.AXS | SWAP.SLP |
CAAD | HKAVATAR | LISTNERDS | SPARK | ICPVTWO | WOOSATURN | BRAIN | WHALE | TCK | GCK |
BABYJESUS | BLAQEMRLD | POLAR | ICPVTHREE | SCRAP | SHARD |