Create a payment link

Payment links have a no-code option, where you can generate a payment page with the web application and begin collecting on-chain/lightning payments in seconds. To ensure that you can receive both on-chain and lightning payments, remember to keep the “BTC On-chain” payment method enabled from the payment methods in Speed web application.

You can perform all the actions of payment links from the web application - create, activate, deactivate and more. Alternatively, you can extend the functionality and generate payment links programmatically at scale using the Speed platform API, in addition to the benefits of this no-code option.

Create payment link via the web application

Log in to your account and follow the steps below to create a payment link.

  1. On the left sidebar, click Receive Payments > Payment Link.
  2. Click Create new.
  3. After clicking the Create new button, you are redirected to a Create page. Here you can fill out the required details including title, description and image.
  4. Click the create payment link button. This will redirect you to the detail page, where you can see the payment link you created and its details, like all the payments made via this link.
  5. Now, share it and get paid.

Create payment link via API

Create a payment link using the /payment-links endpoint and basic details such as amount, currency, statement descriptor, and others. In this example below, we'll show you how you can create a payment link for your customer on a purchase of 200 USD.

Make a POST /payment-links request specifying the following mandatory parameters.

  • amount
  • currency
{
"currency": "USD",
"amount": 200,
"title": "Donation",
"title_description": "Joy of giving",
"title_image": "https://23477318.fs1na1.net/23477/x400.jpg"
}

You can also include other optional parameters, for example, statement descriptor. If optional parameters are not specified, then the payment page will be rendered without a description.

Request parameters

Provide the basic information outlined in the table below:

ParameterRequiredTypeDescription
AmountBigDecimalThis is the total amount you intend to collect from the customer via the payment link. Please add a positive value. Values up to 32 digits can be handled by the amount param, which can have a decimal precision of up to 16 digits.
CurrencyStringIn this parameter, you must specify your preferred base currency (fiat or cryptocurrency) to create a payment link. A three-lettered ISO-compliant currency name must be used. You can choose one of the 167 available currencies.
Statement descriptorStringCustomers need this information because it describes the purpose of payment. Keep this text brief and to the point. On the payment page, this description will be visible.
Success_urlStringWhen the payment is successfully done, you can use this parameter to redirect the customer to your hosted page.
Success_messageStringWhen the payment is successfully done, you can use this parameter to thank them with a customized message. Success_url and success-message are mutually exclusive request parameters—only one of them can be used.
TitleStringYou can use this parameter to add the header or title to your payment page.
Title_descriptionStringYou can use this parameter to provide a brief description of your payment page.
Title_imageStringYou can include a related image illustrating the purpose of a payment page along with the title and description. Image size must not be more than 2 MB.
MetadataObjectYou can use this object to store additional information in key-value pairs about the payment link object in a structured format. You can add up to 50 key-value pairs in a raw JSON format.
CashbackObjectYou can use this parameter to associate an active cashback with a payment link.

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. When passing payment methods through the API, the default settings in the Speed web application will be overridden.

Response attributes

Your 2022-10-15 response contains the following attributes:

{
  "id": "plink_xxxxxxxxxxxxxxxxxxxxxxx",
  "object": "payment.link",
  "livemode": false,
  "status": "active",
  "url": "https://buy.tryspeed.dev/plink_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "currency": null,
  "amount": null,
  "target_currency": null,
  "statement_descriptor": null,
  "success_url": null,
  "success_message": null,
  "title": "Donation",
  "title_description": "Joy of giving",
  "title_image": "https://23477318.fs1na1.net/23477/x400.jpg",
  "metadata": {
    "key_1": "value_1",
    "key_2": "value_2"
  },
  "cashback": {
    "id": "cb_xxxxxxxxxxxxxxxxx"
  },
  "created": null,
  "modified": null
}
Attributes

id string
Unique identifier for the object.


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


livemode boolean
If the object is in live mode, it has the value true; otherwise, it has the value false.


status string
A payment link can have 2 statuses as mentioned below.

  • active
  • Upon generation, by default, it will be active until deactivated.
  • deactivated
  • You can manually deactivate a payment link when you don't intend to get paid via it.

url string
The public URL that can be shared with your customers to receive payments.


currency string
Your preferred currency (base currency) in which you want to create a payment link.


amount BigDecimal
Total amount for which the payment link was created. Values up to 32 digits can be handled by the amount param, which can have a decimal precision of up to 16 digits.


target_currency string
The cryptocurrency in which you want to receive payment from your customer. As of now, Speed only supports SATS.


statement_descriptor string
Additional information about a payment made to an account via this payment link.


success_url string
If the payment is successful, the customer will be redirected to this URL.


success_message string
Message customers will see when they make payment via their wallet. Success_url and success-message are mutually exclusive request parameters—only one of them can be used.


title string
This attribute represents the header or title of the payment page.


title_description string
This attribute represents additional information about your payment page.


title_image string
Represents a public URL consisting of an image illustrating the purpose of a payment page along with the title and description.

Users won't see the image on payment page if the image path is removed or deleted after the payment link is created.


metadata object
You can use this to store additional information about the object in a structured format.


cashback object
You can use this parameter to associate an active cashback with a payment link.

  • id string
  • Unique identifier for the cashback object.

created timestamp
Time at which the payment link was created.


modified timestamp
Time at which the last modification was made.


Before you begin

Before you begin to integrate the payment link APIs, make sure you have followed these steps.The prerequisite steps to accept on-chain/lightning payments through APIs are listed below

  1. Set up your test account.
  2. Create your API key in order to create payment links.

Set up webhooks to monitor the outcome. Notifications allow you to receive payment updates after you've sent the payment link to your shopper.