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.

- 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/.

- 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.

- 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.

- 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();
  }
}

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 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:

Sub Elements:

Sub Elements:

Sub Elements:

- 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.

- 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.

- 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.