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 Boxcoin script by including the following code snippet 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.
document.addEventListener('BXCInit', function () {
// Enter your code here
});
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.
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-bxc]'). |
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. |
Events
Usage
Use the code below and replace EVENT-NAME with the event name. The response.detail represents the event values.
document.addEventListener("EVENT-NAME", function (response) {
// Enter your code here
});
Example:
document.addEventListener("BXCTransactionStarted", function (response) {
console.log(response.detail.checkout_id);
console.log(response.detail.amount);
});
BXCTransactionStarted
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,
to: "bc1qq3hasvdxnrt6pzyehmp3z225kdxzuakayynpwc",
cryptocurrency: "BTC",
external_reference: "ABCDE"
}
BXCTransactionCompleted
Event fired when a transaction is complete and payment has been received.
Response
{
id: 123,
checkout_id: 123,
amount: 123,
to: "bc1qq3hasvdxnrt6pzyehmp3z225kdxzuakayynpwc",
cryptocurrency: "BTC",
external_reference: "ABCDE"
vat: {"amount":"0.33","percentage":"22","country":"Italy","country_code":"IT"}
}
BXCTransactionCancelled
Event fired when a transaction is cancelled.
Response
{
id: 123,
checkout_id: 123,
amount: 123,
to: "bc1qq3hasvdxnrt6pzyehmp3z225kdxzuakayynpwc",
cryptocurrency: "BTC",
external_reference: "ABCDE"
}
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. |
note |
Enter any string you want, it will be shown in the the admin area. |
billing |
A JSON string containing billing details. Default empty string. |
vat |
A JSON string containing billing details. Default empty string. |
checkout_id |
The checkout ID linked to the transaction. Default false. |
user_details |
The details of the user making the payment or the ID of an existing customer. Example : [first_name: "", last_name: "", email: ""] or 123. If the user does not exists, it will be created. This attribute is supported only if the shop app is installed. Default false. |
discount_code |
The discount code. This attribute is supported only if the shop app is installed. Default false. |
type |
The transaction type. 1 is standard transaction, 2 is shop transaction, 3 is exchange transaction. Default 1. |
Response
[433, '0.00032102', 'bc1rj7hascxdxnrt3pzyehmp3z221kdxzuakquunpwc', 3, 'iu7iuo']
[transaction ID, cryptocurrency amount to pay, payment address, minimum confirmations, encrypted transaction]
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..."
}
delete-transaction
Delete a transaction.
Arguments
transaction_id |
The transaction ID. |
Response
true
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
encryption
Encrypt or decrypt a string.
Parameters
string |
The string to encrypt or decrypt. |
encrypt |
Set it to false to decrypt. Default: true. |
Response
Returns the encrypted or decrypted string. Returns false on failure.
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 or currency. 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']. |
checkout_id |
Returns only the transactions linked to the specified checkout ID. Default: false. |
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"
},
...
]
get-transaction
Returns a Boxcoin transaction.
Arguments
transaction_id |
Set transaction ID. |
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
Returns true if the VAT number is valid, otherwise returns false.
payment-link
Returns the payment link of a transaction.
Arguments
transaction_id |
The transaction ID. |
Response
https://example.com/boxcoin/pay.php?id=1234
refund
Refunds a transaction by sending the received cryptocurrency amount to the sender address and mark the transaction as refunded. The transaction status must be complete or underpayment. Depending on the cryptocurrency, the settings Bitcoin Node > Refunds, Ethereum Node > Refunds, Coinbase > Refunds must be active.
Arguments
transaction_id |
The transaction ID. |
Response
[true, 'Refund sent. Transaction details <a href="#" data-hash="8f50833a701b122698d56a4412d7c92bd56af97" target="_blank">here</a>']
Returns [false, 'Error messsage'] on error.
get-exchange-rates
Returns the exchange rate of the specified FIAT currency code to the specified cryptocurrency code.
Arguments
currency_code |
The FIAT currency code. |
cryptocurrency_code |
The cryptocurrency code, e.g. btc, eth, doge. |
Response
0.05781
get-usd-rates
Returns the exchange rate of USD to other FIAT currencies like EURO or GBP.
Arguments
currency_code |
The FIAT currency code. If not set the return the USD exchange rate of all FIAT currencies. |
Response
1.002914
validate-address
Checks if the specified address is valid.
Arguments
address |
The address. |
cryptocurrency_code |
The cryptocurrency code. |
Response
Returns true if the specified address is valid, otherwise returns false.
get-explorer-link
Returns the URL of an explorer to see the details of a transaction.
Arguments
hash |
The transaction hash. |
cryptocurrency_code |
The cryptocurrency code of the transaction. |
Response
https://mempool.space/tx/41ca2705f51ae52b7e93be677b5fedc73bcb11366c3c8e8befbd37e88e311c94
get-network-fee
Returns the estimated network fee of the specified cryptocurrency network.
Arguments
cryptocurrency_code |
The cryptocurrency code of the network. |
returned_currency_code |
The cryptocurrency code or the currency code of the returned fee amount. Set it to false to return the amount in the same cryptocurrency code. Default: false. |
Response
0.00546