REST API

JAVASCRIPT API

PHP API

Getting started

Functions

Events

AJAX functions

AJAX functions | Admin

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 Alipal 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 Alipal installation, e.g. https://example.com/alipal/js/client.js. 

<script id="alipal" 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.

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://alipal.info", 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.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"
}
JAVASCRIPT API
AJAX

AJAX Functions

Usage

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

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

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 alipal transaction ID.

Response

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

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.

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:

alipal.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 Alipal 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 Alipal settings.

Parameters

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

Response

true

update

Update Alipal to the latest version if available.

Response

true

get-transactions

Returns all Alipal 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"
    },
    ...
]

get-transaction

Returns a Alipal 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://alipal.info/uploads/transactions-790419984.csv

invoice

Generate an invoice and return the link to the invoice.

Parameters

transaction_id
 The transaction ID.

Response

http://alipal.info/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"
    }
  }
}

Returns the payment link of a transaction.

Arguments

transaction_id
 The transaction ID.

Response

https://example.com/alipal/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.

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