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