Create an invoice
1. Create your website and get the “SECRET_KEY”. Instruction can be found here.
2. Send the “GET” request to create an invoice
Endpoint:
https://plisio.net/api/v1/invoices/new
cURL request example:
curl --location --request GET https://plisio.net/api/v1/invoices/new
?source_currency=USD
&source_amount=2
&order_number=1
¤cy=BTC
&[email protected]
&order_name=btc1
&callback_url=http://test.com/callback
&api_key=SECRET_KEY
List of all supported request fields:
Field | Description |
---|---|
currency * |
one of the cryptocurrencies supported by Plisio (ID column from supported cryptocurrencies) |
order_name * |
merchant internal order name |
order_number * |
merchant internal order number. Must be an unique number in your store for each new store`s order!!! |
amount |
any cryptocurrency float value. If a fiat currency is to be converted, skip this field and use the source_currency and source_amount fields instead |
source_currency |
one of the 167 fiat currencies |
source_amount |
any float value |
allowed_psys_cids |
comma-separated list of cryptocurrencies that are allowed for a payment. Also, you will be able to select one of them. Example: 'BTC,ETH,TZEC';. To display one currency, need allow_psys_cids to match the currency parameter |
description |
merchant invoice description |
callback_url |
merchant full URL to get invoice updates. The POST request will be sent to this URL. If this parameter isn’t set, a callback will be sent to the URL that can be set under profile in API settings, in the 'Status URL' field; |
success_callback_url |
merchant full URL to get succeed invoice. |
fail_callback_url |
merchant full URL to get failed invoice. |
email |
an auto-fill invoice email. The customer will be asked to insert their email where a notification will be sent |
language |
en_US (supports English only) |
plugin |
Plisio’s internal field to determine integration plugin |
version |
Plisio’s internal field to determine integration plugin version |
redirect_to_invoice |
Instead of JSON response user will be redirected to the Plisio's invoice page (is not working for a white-label shop) |
api_key |
“Secret key” value from your API » Api settings page |
expire_min |
Interval in minutes when invoice will be expired |
* - required
3. The response is a model that can fill differently depending on whether you have While Label or not. In the first case, only two fields are returned: txn_id is a Plisio’s intertnal ID and invoice_url is an invoice URL. And in the second case, extra fields are added to them:
Success response example:
{
"status": "success",
"data": {
"txn_id": "5ee0e502283675293c450d0e",
"invoice_url": "https://plisio.net/invoice/5ee0e502283675293c450d0e"
}
}
White-label success response example:
{
"status": "success",
"data": {
"txn_id": "5f3268bcb7a85576c50d6307",
"invoice_url": "https://plisio.net/invoice/5f3268bcb7a85576c50d6307"
"amount": "0.00017305"
"pending_amount": "0.00017305"
"wallet_hash": "2Mvt2KbPfF7SFsVrPe7wqbcWKiJx6DmXKQM"
"psys_cid": "BTC"
"currency": "BTC"
"status": "new"
"source_currency": "USD"
"source_rate": "0.00008525"
"expire_utc": 1597175132
"expected_confirmations": "1"
"qr_code": "data:image/png;base64..."
"verify_hash": "13e34f5f9efeb5394d7ab5f432df5cc856cc38a4"
"invoice_commission": "0.00005550"
"invoice_sum": "0.00364490"
"invoice_total_sum": "0.00370040"
}
}
HTTP response status code: 200
Success response:
Field | Description |
---|---|
status |
success |
data.txn_id |
Plisio’s intertnal ID |
data.invoice_url |
Invoice URL |
White-label additional data:
Field | Description |
---|---|
amount |
Invoice amount in the selected cryptocurrency |
pending_amount |
The remaining amount to be paid in the selected cryptocurrency |
wallet_hash |
Invoice hash |
psys_cid |
Cryptocurrencies ID (supported cryptocurrencies) |
currency |
Cryptocurrencies code (supported cryptocurrencies) |
source_currency |
Fiat currency |
source_rate |
Exchange rate from the “psys_cid” to the “source_currency” at the moment of transfer |
expected_confirmations |
How many confirmations expected to mark invoice completed |
qr_code |
QR code image in base64 format |
verify_hash |
Hash to verify the “POST” data signed with your SHOP_API_KEY (PHP code example) |
invoice_commission |
Plisio commission |
invoice_sum |
Shop pays commission: invoice amount - invoice_commission ,client pays commission: invoice amount |
invoice_total_sum | shop pays commission: invoice amount, client pays commission: invoice_commission + invoice_sum |
Error response example:
{
"status": "error",
"data": {
"name": "Bad Request",
"message": "Missing required attribute: {\"name\":\"order_number\"}",
"code": 103
}
}
HTTP response status code: 400, 401, 422, 500
Error response:
Field | Description |
---|---|
status |
error |
data.name |
error name |
data.message |
error explanation |
data.code |
error code |
4. Expect invoice updates if the “callback_url” was entered in the invoice request. Status=completed
Callback:
POST http://test.com/callback
Field | Description |
---|---|
txn_id |
Plisio transaction ID |
ipn_type |
invoice |
merchant |
merchant site name |
merchant_id |
merchant site ID |
amount |
received amount in the selected cryptocurrency |
currency |
selected cryptocurrency |
order_number |
merchant internal order number |
order_name |
merchant internal order name |
confirmations |
block confirmations number |
status |
new - initial invoice statuspending - some amount received and waiting for confirmationsexpired - look for the “source_amount” field to verify payment. The full amount may not have been paid.completed - paid in fullmismatch - overpaiderror - some error has occurredcancelled - no payment received within 10 hours |
source_currency |
“source_currency” if stated |
source_amount |
amount in the “source_currency” if stated |
source_rate |
“source_currency” cryptocurrency exchange rate |
comment |
Plisio’s comments |
verify_hash |
Hash to verify the “POST” data signed with your SECRET_KEY Code example |
invoice_commission |
Plisio commission |
invoice_sum |
shop pays commission: invoice amount - invoice_commission client pays commission: invoice amount |
invoice_total_sum |
shop pays commission: invoice amount client pays commission: invoice_commission + invoice_sum |
White-label additional data:
Field | Description |
---|---|
psys_cid |
Cryptocurrencies ID (supported cryptocurrencies) |
pending_amount |
Invoice amount in the selected cryptocurrency |
qr_code |
QR code image in base64 format |
tx_urls |
Array of transaction URLs |
Callback data PHP verification example:
function verifyCallbackData () {
if (!isset($_POST['verify_hash'])) {
return false;
}
$post = $_POST;
$verifyHash = $post['verify_hash'];
unset($post['verify_hash']);
ksort($post);
$postString = serialize($post);
$checkKey = hash_hmac('sha1', $postString, 'SECRET_KEY');
if ($checkKey != $verifyHash) {
return false;
}
return true;
}