Plisio logo Plisio logo
Log in Sign up

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)
amount any cryptocurrency float value.
!!! Please, skip this field If you want to convert a fiat currency and use source_currency and source_amount fields instead
source_currency one of the 167 fiat currencies
source_amount any float value
allowed_psys_cids A comma-separated list of supported cryptocurrencies which are allowed for payment. Customer will be able to select from them (e.g. BTC, ETH, TZEC)
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!!!
description merchant invoice description
callback_url merchant full URL to get invoice updates. The “POST” request will be sent to this URL (example). If this parameter isn’t set, Plisio will send a callback to URL that can be set under profile API » API settings » ”Status URL” field
email an auto-fill invoice email. The customer will be asked to insert their email where a notification will be sent
language en_US (we support EN language 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

* - required

 

3. Receive the JSON response and open the “invoice_url” for a customer. The customer will be asked to enter an email and after that the payment details will be provided.

 

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"
    }
  }

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 ID column from Appendix 1
currency Code column from Appendix 1
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 example (http://test.com/callback):

   {
    "txn_id": "5ee0e502283675293c450d0e",
    "ipn_type": "invoice",
    "merchant": "Test site",
    "merchant_id": "5db97a60bfc16a194f208193",
    "amount": "0.00021777",
    "currency": "BTC",
    "order_number": "1",
    "order_name": "btc1",
    "confirmations": 0,
    "status": "completed",
    "source_currency": "USD",
    "source_amount": "2.09992208",
    "source_rate": "0.00010268",
    "invoice_commission": "0.00008536",
    "invoice_total_sum": "0.01698674",
    "'invoice_total'": "0.01707210",

    "comment": "Invoice details: https:\/\/plisio.net\/account\/transactions\/5ee0b6cc8e3d6825de0afaeb",
    "verify_hash": "eaac338615dc644d980dbfb8f175da13059c0678"
    //White-label additional data
    "psys_cid": "BTC",
    "pending_amount": "0.00021777",
    "tx_urls": "[\"https:\\/\\/sochain.com\\/resolver?query=f11eb95261a3efd697e6922d42a422bba2b72277e4cb427d8ccdee8f0550ea36\",\"https:\\/\\/sochain.com\\/resolver?query=29f6bee123a0accc50f499295831f1f2f50f947fd2eef8fb3649fab00bd36ee6\"]",

  }

Callback fields:

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 ID column from Appendix 1
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;
}