JAVASCRIPT API
Setup and usage

Getting started


Setup and usage

The JavaScript API supplies a collection of functions and events that underpin the majority of Boxcoin functionality. To start using the JavaScript API follow the tutorial below.

Usage

Make sure to load the chat by including the following script into the page where you want to use the APIs. Make sure the links are correct. If you're using the WordPress version this step is not required. Replace [YOUR-URL] with the URL of your Boxcoin installation, e.g. https://example.com/boxcoin/js/client.js.

                                <script id="boxcoin" src="[YOUR-URL]/js/client.js"></script>
                            

Insert the code snippets, functions, and methods of this documentation into the function below.

                                (function ($) {
                                    $(document).on("BXCInit", function () {
                                        // Insert your code here
                                    });
                                }(jQuery));
                            

Function parameters

Insert the function parameters in the same order of this documentation. Example: BOXCoin.checkout.settings(settings, area, onSuccess).

Debug

Check the browser console for errors and debug information.


JAVASCRIPT API
Functions

Functions


BOXCoin.checkout.init()

Initialize a checkout and show it.


Parameters

settings
Array of checkout settings. Available settings: { checkout_id: 123, price: 123, external-reference: "ABC", redirect: "https://boxcoin.dev", currency: "USD", type: "popup" }. Get the settings array of an existing checkout via BOXCoin.checkout.settings().
area
The DOM object where the checkout will be shown, e.g. $('body').
onSuccess
Function to execute once the function is complete. Syntax: function(response) { ... }. The response is the checkout HTML code.

BOXCoin.checkout.settings()

Get the settings array of an existing checkout.


Parameters

checkout
The checkout DOM object, e.g. $('[data-boxcoin]').

BOXCoin.checkout.cancelTransaction()

Cancel the active transaction.


BOXCoin.checkout.show()

Show a hidden checkout.


Parameters

checkout_id
The checkout ID.

BOXCoin.openPopup()

Open, or close, a popup checkout.


Parameters

checkout_id
The checkout ID.
open
Set it to false to close the popup. Default: true.

JAVASCRIPT API
Events

Events


Usage

Use the code below and replace EVENT-NAME with the event name. The response represents the returned value if there is only one attribute, otherwise, it's an array of values. JQuery is required.

                                $(document).on("EVENT-NAME", function (e, response) {
                                    // Insert your code here
                                });
                            

Example:

                                $(document).on("TransactionStarted", function (e, response) {
                                    console.log(response["checkout_id"]);
                                    console.log(response["amount"]);
                                });
                            

TransactionStarted

Event fired when a transaction is created and started by the user, or started again after a page reload.


Response

{
    id: 123,
    checkout_id: 123,
    amount: 123,
    address_payment: "bc1qq3hasvdxnrt6pzyehmp3z225kdxzuakayynpwc",
    cryptocurrency: "BTC",
    external_reference: "ABCDE"
}

TransactionCompleted

Event fired when a transaction is complete and payment has been received.


Response

{
    id: 123,
    checkout_id: 123,
    amount: 123,
    address_payment: "bc1qq3hasvdxnrt6pzyehmp3z225kdxzuakayynpwc",
    cryptocurrency: "BTC",
    external_reference: "ABCDE"
    vat: {"amount":"0.33","percentage":"22","country":"Italy","country_code":"IT"}
}

TransactionCancelled

Event fired when a transaction is cancelled.


Response

{
    id: 123,
    checkout_id: 123,
    amount: 123,
    address_payment: "bc1qq3hasvdxnrt6pzyehmp3z225kdxzuakayynpwc",
    cryptocurrency: "BTC",
    external_reference: "ABCDE"
}

JAVASCRIPT API
AJAX

AJAX Functions


Usage

List of AJAX functions. Use the function below to start an AJAX call:

                                BOXCoin.ajax('FUNCTION-NAME', { parameter: value, parameter: value, ... }, (response) => {
                                   // Insert your code here
                                });
                            

Replace FUNCTION-NAME with the name of one of the functions below. Replace the list of parameter: value with the function parameters. The response is in JSON format.


create-transaction

Create a new transaction ready to be paid by the user.


Parameters

amount
The transaction amount in FIAT, e.g. 123.
cryptocurrency_code
The cryptocurrency code, e.g. btc.
currency_code
The currency code, e.g. usd. Default: Settings > Currency.
external_reference
Enter the string you want, it will be sent via webhook and as a redirect URL parameter.
title
Enter the string you want, it will be shown in the the admin area.
description
Enter the string you want, it will be shown in the the admin area.
billing
A JSON string containing billing details. Default empty string.

Response

[433, '0.00032102', 'bc1rj7hascxdxnrt3pzyehmp3z221kdxzuakquunpwc']
[transaction ID, cryptocurrency amount to pay, payment address]

check-transactions

Check the latest Blockchain transactions of the payment address and returns the Blockchain transaction details if the payment is detected.


Parameters

transaction_id
The transaction ID.

Response

Returns false if the payment is not found, or and encrypted string if the payment is detected. The encrypted string can be used for the attribute transaction of the function check-transaction.


check-transaction

Returns the details of a Blockchain transaction.


Parameters

transaction
Enter the encrypted string returned by the function check-transactions. If you're logged as admin you can pass the following array as well: { id: "", hash: "", cryptocurrency: "", to: "" }. The id is the Boxcoin transaction ID.

Response

{
    "confirmed" => true,
    "confirmations" => 1155,
    "minimum_confirmations" => 3,
    "hash" => "8f50833a701b122698d56a4412d7c92bd56af97..."
}

webhook

Send the webhook of a transaction. The webhook can be sent only 1 time per transaction.


Parameters

transaction
Enter the encrypted string returned by the function check-transactions. If you're logged as admin you can pass the following array as well: { id: "", hash: "", cryptocurrency: "", to: "" }. The id is the Boxcoin transaction ID.

Response

true

Returns false if the webhook has already been sent.


get-fiat-value

Get the FIAT value of a cryptocurrency value.


Parameters

amount
The FIAT value.
cryptocurrency_code
The cryptocurrency code, e.g. btc.
currency_code
The currency code, e.g. usd.

Response

305126.4

cron

Run the cron jobs.


Response

true

JAVASCRIPT API
AJAX ADMIN

AJAX Functions | Admin


Usage

List of AJAX functions available only after logging in as an administrator. Use the login function to log in as an administrator.

Use the function below to start an AJAX call:

                                BOXCoin.ajax('FUNCTION-NAME', { parameter: value, parameter: value, ... }, (response) => {
                                   // Insert your code here
                                });
                            

Replace FUNCTION-NAME with the name of one of the functions below. Replace the list of parameter: value with the function parameters. The response is in JSON format.


login

Log in as an administrator.


Parameters

username
The username.
password
The password.

Response

Returns an encrypted string to be saved in a cookie named BXC_LOGIN. Use the function BOXCoin.cookie('BXC_LOGIN', response, 365, 'set') to save the cookie. Use the function BOXCoin.cookie('BXC_LOGIN', false, false, 'delete'); to log out. Returns false if login fails.


get-balances

Returns the balances of the cryptocurrency addresses saved in the admin area.


Response

{
    "balances": {
        "btc": {
            "amount": 0.63521135,
            "fiat": 19563.05,
            "name": "Bitcoin"
        },
        "eth": {
            "amount": 0.001,
            "fiat": 1.92,
            "name": "Ethereum"
        },
        "doge": {
            "amount": 10,
            "fiat": 0.98,
            "name": "Dogecoin"
        }
    },
    "total": 18461.67,
    "currency": "USD"
}

get-checkouts

Returns the checkouts list, or a single checkout.


Parameters

checkout_id
The checkout ID. Leave it empty to get all checkouts.

Response

[{
    "id": "2",
    "title": "Cloud Storage Premium",
    "description": "",
    "price": "99",
    "currency": "CNY",
    "type": "I",
    "redirect": "",
    "external_reference": "ABC",
    "creation_time": "2022-02-02 10:00:00"
}, {
    "id": "3",
    "title": "Cloud Storage Base",
    "description": "",
    "price": "99.5",
    "currency": "USD",
    "type": "P",
    "redirect": "",
    "external_reference": "",
    "creation_time": "2022-02-03 11:05:19"
},
...
]

save-checkout

Create a new checkout, or update an existing one.


Parameters

checkout
Pass the checkout array below or get it from the function get-checkouts. Add the key id: CHECKOUT-ID to update an existing checkout.
{
    "title": "Cloud Storage Premium",
    "description": "",
    "price": "99",
    "currency": "CNY",
    "type": "I",
    "redirect": "",
    "external_reference": "ABC",
    "creation_time": "2022-02-02 10:00:00"
}

Response

Returns the checkout ID.


delete-checkout

Delete a checkout.


Parameters

checkout_id
The checkout ID.

Response

true

get-settings

Returns all Boxcoin settings.


Response

{
    "address-btc": "",
    "address-eth": "",
    "address-doge": "",
    "refresh-interval": "5",
    "confirmations": "",
    "currency": "",
    "custom-explorer-active": false,
    "custom-explorer-divider": "",
    "custom-explorer-balance-url": "",
    "custom-explorer-balance-path": "",
    "custom-explorer-transaction-url": "",
    "custom-explorer-transaction-path": "",
    "custom-explorer-transactions-url": "",
    "custom-explorer-transactions-path": "",
    "custom-explorer-address": "",
    "custom-explorer-address-path": "",
    "webhook-url": "",
    ...
}

save-settings

Save all Boxcoin settings.


Parameters

settings
Pass the array of all settings. Get it with the function get-settings.

Response

true

update

Update Boxcoin to the latest version if available.


Response

true

get-transactions

Returns all Boxcoin transactions.


Arguments

pagination
Set the pagination number from 0 to N. Returns only 100 results per page. Set it to -1 to get all results. Default: 0.
search
Returns only the transactions matching the specified search terms. Default: false.
status
Returns only the transactions with the given status. Accepted values: C(completed) and P(pending). Default: false.
cryptocurrency
Returns only the transactions in the given cryptocurrency. Default: false.
date_range
Returns only the transactions within the date range. Syntax: ['yyyy-mm-dd', 'yyyy-mm-dd']. Example: ['2022-08-02', '2022-08-03'].

Response

[
    {
	    "id": "433",
	    "title": "",
	    "description": "",
	    "from": "",
	    "to": "bc1qj2hafvdxnrt1pzyyhmp3z335kdxzuakqyynpuc",
	    "hash": "",
	    "amount": "0.00032102",
	    "amount_fiat": "10",
	    "cryptocurrency": "btc",
	    "currency": "usd",
	    "external_reference": "",
	    "creation_time": "2022-05-30 15:57:51",
	    "status": "P",
	    "webhook": "0"
    },
    ...
]                                 

update-transaction

Update a transaction.


Arguments

transaction_id
The transaction ID.
values
Array in PHP or JSON format, with the values to update. Syntax: ['key' => 'value', 'key' => 'value', ...]. Example: ['status' => 'C', 'title' => 'Example']. Allowed keys: title, description, from, to, hash, amount, amount_fiat, cryptocurrency, currency, external_reference, creation_time(2022-04-14 10:00:00), status (C for completed, P for pending, R for refunded), billing.

Response

true                             

download-transactions

Download a CSV file with transaction details.


Parameters

search
Returns only the transactions matching the search.
status
Returns only the transactions with the provided status.
cryptocurrency
Returns only the transactions with the provided cryptocurrency.
date_range
Returns only the transactions within the date range. Syntax: ['yyyy-mm-dd', 'yyyy-mm-dd']. Example: ['2022-08-02', '2022-08-03'].

Response

http://boxcoin.dev/uploads/transactions-790419984.csv

invoice

Generate an invoice and return the link to the invoice.


Parameters

transaction_id
The transaction ID.

Response

http://boxcoin.dev/uploads/inv-5.pdf

vat

Returns the VAT information of a given amount and country.


Arguments

amount
The amount.
country_code
The country code of the VAT-registered country you want to apply. If not provided, the country is automatically retrieved from the user's IP. Default: false.
currency_code
The currency code of the provided amount. Default: false.

Response

[12.2,2.2,"IT","Italy","Including  2.2 for VAT in Italy",22]

vat-validation

Validate a VAT number.


Arguments

vat_number
The VAT number.

Response

{
  "success": true,
  "code": 200,
  "data": {
    "valid": true,
    "company": {
      "vat_number": "288305674",
      "country_code": "GB",
      "company_name": "WEIO LTD",
      "company_address": "142 CROMWELL ROAD\nLONDON\nGREATER LONDON\n\n\nSW7 4EF"
    }
  }
}