Create an invoice

invoice scheme

1. Create your online shop 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 168 fiat currencies
source_amount any float value
order_name merchant internal order name
order_number merchant internal order number
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"
    }
  }
  

HTTP response status code: 200

 

Success response:

Field Description
status success
data.txn_id Plisio’s intertnal ID
data.invoice_url Invoice URL

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 shop",
    "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",
    "comment": "Invoice details: https:\/\/plisio.net\/account\/transactions\/5ee0b6cc8e3d6825de0afaeb",
    "verify_hash": "eaac338615dc644d980dbfb8f175da13059c0678"
  }
  

Callback fields:

Field Description
txn_id Plisio transaction ID
ipn_type invoice
merchant merchant shop name
merchant_id merchant shop ID
amount invoice 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

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