Create a payment

You can create a payment through the payments 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 Payments API.

Use the /payments endpoint and basic details such as amount, currency, payment_methods, and target currency, statement descriptor, and others to create a payment object. In this example below, we'll show you how you can create a payment for your customer to receive 200 USD.

Make a POST /payments request specifying the following mandatory parameters.

{
  "amount": 200,
  "currency": "USD",
  "ttl": 600,
  "statement_descriptor": "ABC",
  "target_currency": "SATS",
  "payment_methods": [
    "onchain",
    "lightning"
  ]
}

Request parameters

Provide the basic information outlined in the table below:

If optional parameters are not specified, then the payment object will be generated without them.

More information can be found in our API reference.

Request headers

Response

{
  "id": "pi_lawdbwftiHXHsZyC",
  "object": "payment",
  "status": "unpaid",
  "currency": "SATS",
  "amount": 1000,
  "exchange_rate": 1,
  "target_currency": "SATS",
  "target_amount": 1000,
  "payment_method": [
    "onchain",
    "lightning"
  ],
  "payment_method_options": {
    "on_chain": {
      "id": "btcaddr_lawdbwiawrrFIrP2",
      "address": "tb1qu48d57npsufsh3gk9nk42puvf8sznurjpwmavp"
    },
    "lightning": {
      "id": "lni_lawdbwh8WaakvyjP",
      "payment_request": "lntb10u1p3cpx4ppp5n0zaum247aq4humnhv4ehc65gpm750sw0aua97uepj6g385c0anqdqdg4ehqun9wdek7cqzpgxqzjcsp55a4ncwc0gfced2n4tsxk286vveg9e9ft6qqll5ecz4f7xy8jdcyq9qyyssqmkpk4yfexwj45kxzf6jyl6ee6cvu3c4lztm2ung0sn54rty0hhs5nfg85czkg64rhac7088jad83c8deuazkzgggmnc7s80jhcfxrmcqq2qv9g"
    }
  },
  "ttl": 600,
  "expires_at": 1669373177273,
  "description": "Payment V2",
  "statement_descriptor": "Espresso",
  "metadata": {
    "key_2": "value_2",
    "key_1": "value_1"
  },
  "created": 1669372577273,
  "modified": 1669372577273
}

Your 2022-10-15 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
A payment object can have 4 statuses as mentioned below.

• unpaid
• The payment object has unpaid status after its generation until it is paid or expired.
• paid
• The payment object is marked paid once any amount (the amount may be less than the actual payment in the case of on-chain partial payment) of payment is received within the timeframe (ttl).
• expired
If the payment is not received within the stipulated timeframe (ttl) then it will be marked as expired.
• cancelled
• When you deactivate a checkout or payment link, the payment associated with it gets cancelled.

currency string
The base currency in which you prefer to work.

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

exchange_rate BigDecimal
The exchange rate is used to convert the currency(base currency) into target_currency.

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

target_amount BigDecimal
The converted amount (from base currency to target_currency) for which the payment request is generated.

target_amount_paid BigDecimal
Once the payment is made, this returns the exact amount received in the target_currency.

target_amount_paid_at timestamp
Time at which the payment was paid.

payment_methods object
Both on-chain and lightning network methods can be used to receive funds. Please indicate whether you want to use lightning or on-chain. When passing payment methods through the API, the default settings in the Speed web application will be overridden.

payment_method_options integer
This object contains two objects, lightning, and on-chain, both specifying all the data required to process the payment.

• on_chain
• This object has all the data associated with the payment if the payment method is on-chain.
• id
• Unique identifier for the on-chain object.
• address
• It specifies the BTC wallet address to which the payment is processed.
• lightning
• This object has all the data associated with the payment if the payment method is lightning.
• id
• Unique identifier for the lightning object.
• payment_request
• The lightning network payload for generating a QR code is returned.

ttl integer
Represents the time duration until which the payment has not expired. (Specified in milliseconds)

expires_at timestamp
Time at which the payment expires.

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

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

created timestamp
Time at which the payment object was created.

modified timestamp
Time at which the last modification was made.

Use case it solves

Whatever type of business you're in - whether it's a marketplace, SaaS, e-commerce, B2B, or B2C - Speed has this product: payment APIs that you can use to develop a payment page on your website for accepting crypto payments (as of now, Speed only supports SATS). You only need to embed this payment payload on the payment page.

Before you begin

Before you begin, make sure you have completed the steps outlined below.

1. Get an overview of the Speed payment page to understand how to create your payment page using this payment payload.
2. Confirm that you have the necessary keys to create payments through the payments API.