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.
- On the left sidebar, click Receive Payments > Payment Link.
- Click
Create new
. - 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. - 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. - 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:
Parameter | Required | Type | Description |
---|---|---|---|
Amount | ✅ | BigDecimal | This 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. |
Currency | ✅ | String | In 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 descriptor | String | Customers 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_url | String | When the payment is successfully done, you can use this parameter to redirect the customer to your hosted page. | |
Success_message | String | When 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. | |
Title | String | You can use this parameter to add the header or title to your payment page. | |
Title_description | String | You can use this parameter to provide a brief description of your payment page. | |
Title_image | String | You 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. | |
Metadata | Object | You 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. | |
Cashback | Object | You can use this parameter to associate an active cashback with a payment link. |
More information can be found in our API reference.
Request headers
Parameter | Required | Type | Description |
---|---|---|---|
speed-version | string | As 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
Set up webhooks to monitor the outcome. Notifications allow you to receive payment updates after you've sent the payment link to your shopper.
Updated about 1 month ago