Create an invoice

invoice scheme

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
  &currency=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 status
pending - some amount received and waiting for confirmations
expired - look for the “source_amount” field to verify payment. The full amount may not have been paid.
completed - paid in full
mismatch - overpaid
error - some error has occurred
cancelled - 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;
}