Create an invoice

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://payenium.com/api/v1/invoices/new

cURL request example:

curl --location --request GET https://payenium.com/api/v1/invoices/new
  ?source_currency=USD
  &source_amount=2
  &order_number=1
  &currency=BTC
  &email=customer@payenium.com
  &order_name=btc1
  &callback_url=http://test.com/callback
  &api_key=SECRET_KEY

List of all supported request fields:

FieldDescription
currencyone of the cryptocurrencies supported by Payenium (ID column from supported cryptocurrencies)
amountany 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_currencyone of the 167 fiat currencies
source_amountany float value
allowed_psys_cidsA 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_namemerchant internal order name
order_numbermerchant internal order number. Must be an unique number in your store for each new store`s order!!!
descriptionmerchant invoice description
callback_urlmerchant full URL to get invoice updates. The “POST” request will be sent to this URL (example). If this parameter isn’t set, Payenium will send a callback to URL that can be set under profile API » API settings » ”Status URL” field
emailan auto-fill invoice email. The customer will be asked to insert their email where a notification will be sent
languageen_US (we support EN language only)
pluginPayenium’s internal field to determine integration plugin
versionPayenium’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://payenium.com/invoice/5ee0e502283675293c450d0e"
    }
  }

White-label success response example:

 {
    "status": "success",
    "data": {
      "txn_id": "5f3268bcb7a85576c50d6307",
      "invoice_url": "https://payenium.com/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:

FieldDescription
statussuccess
data.txn_idPayenium’s intertnal ID
data.invoice_urlInvoice URL

White-label additional data:

FieldDescription
amountInvoice amount in the selected cryptocurrency
pending_amountThe remaining amount to be paid in the selected cryptocurrency
wallet_hashInvoice hash
psys_cidID column from Appendix 1
currencyCode column from Appendix 1
source_currencyFiat currency
source_rateExchange rate from the “psys_cid” to the “source_currency” at the moment of transfer
expected_confirmationsHow many confirmations expected to mark invoice completed
qr_codeQR code image in base64 format
verify_hashHash to verify the “POST” data signed with your SHOP_API_KEY (PHP code example)
invoice_commissionPayenium commission
invoice_sumShop pays commission:
invoice amount – invoice_commission,
client pays commission: invoice amount
invoice_total_sumshop 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:

FieldDescription
statuserror
data.nameerror name
data.messageerror explanation
data.codeerror 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:\/\/payenium.com\/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:

FieldDescription
txn_idPayenium transaction ID
ipn_typeinvoice
merchantmerchant site name
merchant_idmerchant site ID
amountreceived amount in the selected cryptocurrency
currencyselected cryptocurrency
order_numbermerchant internal order number
order_namemerchant internal order name
confirmationsblock confirmations number
statusnew – 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_amountamount in the “source_currency” if stated
source_rate“source_currency” cryptocurrency exchange rate
commentPayenium’s comments
verify_hashHash to verify the “POST” data signed with your SECRET_KEY
Code example
invoice_commissionPayenium commission
invoice_sumshop pays commission: invoice amount – invoice_commission
client pays commission: invoice amount
invoice_total_sumshop pays commission: invoice amount
client pays commission: invoice_commission + invoice_sum

White-label additional data:

FieldDescription
psys_cidID column from Appendix 1
pending_amountInvoice amount in the selected cryptocurrency
qr_codeQR code image in base64 format
tx_urlsArray 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;}