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