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://api.plisio.net/api/v1/invoices/new
cURL request example:
curl --location --request GET https://api.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). Optional parameter. If the parameter is not set, one of the active cryptocurrencies from the API settings is selected automatically when creating an invoice. |
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;. When adding json=true to the url, the response will come in the form of JSON |
success_callback_url | merchant full URL to get succeed invoice. When adding json=true to the url, the response will come in the form of JSON |
fail_callback_url | merchant full URL to get failed invoice. When adding json=true to the url, the response will come in the form of JSON |
success_invoice_url | "To the site" invoice's button link in a case of invoice has been paid |
fail_invoice_url | "To the site" invoice's button link in a case of invoice has not been paid |
email | Before paying an invoice, your client will be asked to enter an email to which a notification will be sent. If you want to skip this step for your clients, fill in this field beforehand (with any information acceptable). |
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 |
return_existing | Return existing invoice instead of error |
* - 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
cancelled duplicate
- a customer has switched to another cryptocurrency and payment has been received to the that currency
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 confirmationspending internal - moving invoice money to user wallet has been initiatedexpired - look for the “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);
if (isset($post['expire_utc'])){
$post['expire_utc'] = (string)$post['expire_utc'];
}
if (isset($post['tx_urls'])){
$post['tx_urls'] = html_entity_decode($post['tx_urls']);
}
$postString = serialize($post);
$checkKey = hash_hmac('sha1', $postString, 'SECRET_KEY');
if ($checkKey != $verifyHash) {
return false;
}
return true;
}
composer require plisio/plisio-api-php
function verifyCallbackData ()
$plisio = new \Plisio\ClientAPI($secretKey);
return $plisio->verifyCallbackData($_POST, $secretKey);
}
Example getting callback data in Node
:
Works if the url is callback_url
, success_callback_url
, fail_callback_url
has the value json=true
. Example: https://Localhost.loc/success?json=true
.
const http = require("http");
const crypto = require('crypto');
const secretKey = 'SECRET_KEY';
const host = '127.0.0.1';
const port = 8000;
const vallidateRequest = function (data) {
if (typeof data === 'object' && data.verify_hash && secretKey) {
const ordered = {...data};
delete ordered.verify_hash;
const string = JSON.stringify(ordered);
const hmac = crypto.createHmac('sha1', secretKey);
hmac.update(string);
const hash = hmac.digest('hex');
return hash === data.verify_hash;
}
return false;
}
const requestListener = function (req, res) {
let chunks = '';
req.on('data', chunk => chunks += chunk);
req.on('end', () => {
let data;
try {
data = JSON.parse(chunks);
res.setHeader("Content-Type", "application/json");
} catch (e){
// console.error(e);
data = false;
}
if (data && vallidateRequest(data)) {
res.writeHead(200);
res.end('This is a correct JSON callback');
} else {
res.writeHead(422);
res.end('Incorrect data 1');
}
})
};
const server = http.createServer(requestListener);
server.listen(port, host, () => {
console.log(`Server is running on http://${host}:${port}`);
});
-->