Request Payment

You need to create a 'request' to receive payments through Ninjapay. A request contains both a Lightning Network BOLT11 invoice, capable of accepting payments through the LN protocol, and a on-chain address for standard on-chain transactions. We recommend using only "lbtc" lightning wallet for all your use-cases, since it's built for instant almost zero fee micro payments.

Method


POST https://prod.ninjapay.me/sapi/v1/receive

Parameters


Body (application/json)
 {
  wallet: string; // lbtc(recommended), usdt, btc are supported currently
  payment_mode: string; // onchain, lightning
  amount: int; // For lbtc & btc amount should be entered in BTC not SAT
  receiver_ninjatag?: string; // Add this username if you want to request for other users
  chain_network?: string; // Add this to get the onchain address for a specific network(not required for "lbtc" wallet)
  fiat_value?: int;
  fiat_currency?: string; // INR, USD, EUR...
  description?: string;
  expires_in?: int; // The expiry of payment request in mins for hosted checkout
  callback_url?: string; // only works for lbtc_wallet currently
  success_url?: string; // Redirected to this after success from hosted checkout
  customer_name?: string;
  order_id?: string;
  extra?: {};
}

Other info

Parameters

Input options

wallet

lbtc,btc,usdt

chain_network

BTC,ERC20,BEP20, MATIC

Response

  {
      "tid": 198660213997,
      "payment_mode": "lightning", // lightning, onchain 
      "wallet": "btc",
      "amount": 0.19362, // All amounts in BTC unit
      "receiver_ninjatag": "nakamoto",
      "description": "sample_description",
      "created_at": 1661215876,
      "status": "undefined", // undefined, pending, declined, paid status's by ninjapay
      "status_payee": "undefined", // undefined, pending, declined, paid (if payee decides to change the status from dashboard)
      "status_payer": "undefined", // undefined, pending, declined, paid (status from hosted checkout)
      "transaction_hash": null, // transaction hash added by payer from hosted checkout)
      "callback_url": "https://yourwebhook.com",
      "callback_status": null, // 200, 400, ... only triggers after payment
      "success_url": "https://yoursuccessurl.com",
      "hosted_checkout_url": "https://checkout.ninjapay.me/198660213997",
      "hosted_checkout_expiry": 1714912921,
      "customer_name": null;
      "order_id": "21",
      "fiat_currency": "USD",
      "fiat_value": 4000.22,
      "extra": {
          "name": "nakamoto",
          "email": "sample@sample.com"
      },
      "chain_address": {
          "asset": "BTC",
          "chain_network": "ERC20",
          "address": "2NAyVsR6N8opLW9na23yBhkWqizEmwDVwvm"
      },
      "uri": "bitcoin:2NAyVsR6N8opLW9na23yBhkWqizEmwDVwvm?amount=0.00019362&label=sample_description&lightning=lntb193620n1p3sgfyrpp5vsy5xumnky24rvt3aty94d4srrwy2rhp94yqzwu6er5x9eymh2zsdqawdsk6urvv40kgetnvdexjur5d9hkucqzpgxqzjhsp5uvmlp5xkteze6qmty35kuxe3j8cwzk25zsx7t9z84423peps9h9s9qyyssqp2ydxchkqceyzz4ma68kmjm58pr0pnx3anl48ajqlhfcgzqrpa0j7kxzjygdxujptkqjrkk6gxsag87yx9wcd7ugyauq45skvcg9aygqx5geqv",
      "ttl": 10,
      "lightning_invoice": {
          "lightning_invoice_type": "invoice",
          "expires_at": 1814912992,
          "payreq": "lnbc193620n1p3sgfyrpp5vsy5xumnky24rvt3aty94d4srrwy2rhp94yqzwu6er5x9eymh2zsdqawdsk6urvv40kgetnvdexjur5d9hkucqzpgxqzjhsp5uvmlp5xkteze6qmty35kuxe3j8cwzk25zsx7t9z84423peps9h9s9qyyssqp2ydxchkqceyzz4ma68kmjm58pr0pnx3anl48ajqlhfcgzqrpa0j7kxzjygdxujptkqjrkk6gxsag87yx9wcd7ugyauq45skvcg9aygqx5geqv"
      },
      "total_fee": {
          "network_fee": "0.00008161 btc",
          "service_fee": "0.00000002 btc (0.1%)",
          "gst_fee": null
      }
  }

How to decode a lightning invoice?

Use the url 👉 https://lightningdecoder.com/<lightning_invoice> or there are many free open source dependency packages which can be used in your code/project to decode an invoice. You can also use our api Decode Invoice method.

Code Example


const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'API_KEY'
  },
  body: '{"amount":0.0018,"description":"sample_description","wallet":"lbtc","receiver_ninjatag":"nakamoto","order_id":"21","callback_url":"https://yourwebhook.com"}'
};

fetch('https://prod.ninjapay.me/sapi/v1/receive', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

You can use Ninjapay's native checkout experience by redirecting your user to the checkout endpoint:

Production - https://checkout.ninjapay.me/{tid}

PreviousSend Payment NextNinjaAuth

Last updated 1 year ago

Body (application/json) { wallet: string; // lbtc(recommended), usdt, btc are supported currently payment_mode: string; // onchain, lightning amount: int; // For lbtc & btc amount should be entered in BTC not SAT receiver_ninjatag?: string; // Add this username if you want to request for other users chain_network?: string; // Add this to get the onchain address for a specific network(not required for "lbtc" wallet) fiat_value?: int; fiat_currency?: string; // INR, USD, EUR... description?: string; expires_in?: int; // The expiry of payment request in mins for hosted checkout callback_url?: string; // only works for lbtc_wallet currently success_url?: string; // Redirected to this after success from hosted checkout customer_name?: string; order_id?: string; extra?: {}; }

{ "tid": 198660213997, "payment_mode": "lightning", // lightning, onchain "wallet": "btc", "amount": 0.19362, // All amounts in BTC unit "receiver_ninjatag": "nakamoto", "description": "sample_description", "created_at": 1661215876, "status": "undefined", // undefined, pending, declined, paid status's by ninjapay "status_payee": "undefined", // undefined, pending, declined, paid (if payee decides to change the status from dashboard) "status_payer": "undefined", // undefined, pending, declined, paid (status from hosted checkout) "transaction_hash": null, // transaction hash added by payer from hosted checkout) "callback_url": "https://yourwebhook.com", "callback_status": null, // 200, 400, ... only triggers after payment "success_url": "https://yoursuccessurl.com", "hosted_checkout_url": "https://checkout.ninjapay.me/198660213997", "hosted_checkout_expiry": 1714912921, "customer_name": null; "order_id": "21", "fiat_currency": "USD", "fiat_value": 4000.22, "extra": { "name": "nakamoto", "email": "sample@sample.com" }, "chain_address": { "asset": "BTC", "chain_network": "ERC20", "address": "2NAyVsR6N8opLW9na23yBhkWqizEmwDVwvm" }, "uri": "bitcoin:2NAyVsR6N8opLW9na23yBhkWqizEmwDVwvm?amount=0.00019362&label=sample_description&lightning=lntb193620n1p3sgfyrpp5vsy5xumnky24rvt3aty94d4srrwy2rhp94yqzwu6er5x9eymh2zsdqawdsk6urvv40kgetnvdexjur5d9hkucqzpgxqzjhsp5uvmlp5xkteze6qmty35kuxe3j8cwzk25zsx7t9z84423peps9h9s9qyyssqp2ydxchkqceyzz4ma68kmjm58pr0pnx3anl48ajqlhfcgzqrpa0j7kxzjygdxujptkqjrkk6gxsag87yx9wcd7ugyauq45skvcg9aygqx5geqv", "ttl": 10, "lightning_invoice": { "lightning_invoice_type": "invoice", "expires_at": 1814912992, "payreq": "lnbc193620n1p3sgfyrpp5vsy5xumnky24rvt3aty94d4srrwy2rhp94yqzwu6er5x9eymh2zsdqawdsk6urvv40kgetnvdexjur5d9hkucqzpgxqzjhsp5uvmlp5xkteze6qmty35kuxe3j8cwzk25zsx7t9z84423peps9h9s9qyyssqp2ydxchkqceyzz4ma68kmjm58pr0pnx3anl48ajqlhfcgzqrpa0j7kxzjygdxujptkqjrkk6gxsag87yx9wcd7ugyauq45skvcg9aygqx5geqv" }, "total_fee": { "network_fee": "0.00008161 btc", "service_fee": "0.00000002 btc (0.1%)", "gst_fee": null } }

const options = { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'API_KEY' }, body: '{"amount":0.0018,"description":"sample_description","wallet":"lbtc","receiver_ninjatag":"nakamoto","order_id":"21","callback_url":"https://yourwebhook.com"}' }; fetch('https://prod.ninjapay.me/sapi/v1/receive', options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err));