Create a payrequest

You can create a payrequest through the payrequest API. This API will return an object with a payment payload and many other associated details, using which you can receive funds from your customer.

Let's learn how to use the payrequest API.

Use the /payrequests endpoint and basic details such as expected_currency, min_amount, max_amount, type, max_uses, and others to create a payrequest object. In this example below, we'll show you how you can create a payrequest for your customers.

Make a POST request specifying the following parameters.

Request parameters

Provide the basic information outlined in the table below:

ParameterRequiredTypeDescription
expected_currencystringIn this parameter, you must specify your preferred expected currency (fiat or cryptocurrency) in which you want to save the payment details of a payrequest. A three-lettered ISO-compliant currency name must be used.
min_amountdoubleThis is the minimum amount (in SATS) you want to receive through this payrequest.
max_amountdoubleThis is the maximum amount (in SATS) you want to receive through this payrequest.
typeStringSpeed supports both onchain and lnurl payrequest methods. Use this parameter to mention which payment method you want; lnurl or onchain.
max_usesdoubleIn this parameter, you must specify the maximum amount of times you want to receive payment through this payrequest. Here 0 means an infinite number of times.
{
  "expected_currency": "USD",
  "min_amount": 1,
  "max_amount": 500000000,
  "type": "lnurl",
  "max_uses": 0,
  "success_url": null,
  "success_message": "Thank you for the payment!",
  "statement_descriptor": null
}

For creating an on-chain payrequest, you do not need to mention details such as the expected_currency, min_amount, max_amountmax_uses, and others. However, mentioning them in both scenarios is suggested by us.

More information can be found in our API reference.

Request headers

ParameterRequiredTypeDescription
speed-versionstringAs of now, there are two versions (2022-04-15 and 2022-10-15). Version 2022-10-15 supports both on-chain and lightning payment methods. In the parameter speed-version, you have to specify version 2022-10-15.

Response

{
  "id": "pr_xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "pay_request",
  "status": "active",
  "type": "lnurl",
  "min_amount": 1,
  "max_amount": 500000000,
  "expected_currency": null,
  "max_uses": 0,
  "address": null,
  "url": null,
  "secret": null,
  "encoded": null,
  "success_url": null,
  "success_message": null,
  "statement_descriptor": null,
  "created": 1675826833155,
  "modified": 1600626833155
}

Your response contains the following attributes:

Attributes


id string
Unique identifier for the object.

object string
The type of the object indicates to which entity this response belongs.

status string
Payrequest can have 2 statuses, as mentioned below:

active
Payrequest is active after its generation until it is deactivated.
deactivated
You can manually deactivate a payrequest if you no longer wish to get paid via it.

type string
Both onchain and lnurl methods can be used to receive funds. This indicates the payrequest method (lnurlor onchain) used to send funds through this payrequest.

min_amount BigInteger
This is the minimum amount you will receive through this payrequest.

max_amount BigInteger
This is the maximum amount you will receive through this payrequest.

expected_currency string
Your customer will make a payment in SATS/BTC. However, you can specify the expected currency (fiat or cryptocurrency) in which you would like to store the conversion of the payment made by your customers in SATS.

max_uses BigInteger
This is the maximum number of payments that can be received through this payrequest. Here 0 means an infinite number of payments can be received.

address string
If the method type is onchain, this indicates the Bitcoin wallet address to which the payment is sent. If not, it is null.

url string
If the method type is lnurl, this indicates the url which is derived from decoding the lnurl. If not, it is null.

secret string
If the method type is lnurl, this indicates the secret derived from the url. If not, it is null.

encoded string
If the method type is lnurl, this indicates the lnurl that your customer can use to send funds. If not, it is null.

statement_descriptor string
Additional information about a payment made to an account using this payrequest.

success_message string
Message customers will see when they make payment via their preferred wallet.

success_url string
Customers will see this clickable link in their wallet if the transaction goes through successfully.

created timestamp
Time at which the payrequest object was created.

modified timestamp
Time at which the last modification was made.