Design a Bitcoin Lightning crypto payment form

​

Key characteristics of Lightning payments

lnbcrt1m1p5u93tfpp53wwjfugpyypf68mgwjfzq99x8cghlurxwpp680r9uyvd8qxkjulqdqqcqzysxqzuysp5fdzuturj4cttdaafw09j739adh4slxxqynnjpl6n208wqfc8ny6q9qxpqysgqgdgwm5hdt736pm3jkn0spp85zwx0023vlxj8s0fjkha55wtyg5hjxvmkjl6ee4ztxrc75j3q7qzxua7r28qujlvc3ykmaklczwccmkspazvfhu

• Each invoice is created for a specific amount and can only be paid once.
• The invoice contains the exact payment amount, so it must be paid in full and exactly as issued. Partial payments and overpayments are not possible.
• The invoice expires 15 minutes after it is created. The exact expiration time is included in the API response when the Lightning invoice is generated.
• The amount cannot be changed after the invoice is created.
• The maximum supported amount is 0.045 BTCLN. For larger deposits, use the Bitcoin network.

​

How the payment form can be implemented

1

Display a Generate Lightning invoice form to a user

Add an Amount field for the user to fill in:

2

Send POST /addresses/take to AlphaPo

After the user enters an amount and clicks Generate, your site should send a POST request to the /addresses/take endpoint.

POST /api/v2/addresses/take HTTP/1.1
Host: app.alphapo.net
X-Processing-Key: <api-key>
X-Processing-Signature: <api-key>
Content-Type: application/json
Accept: */*
    
{
  "currency": "BTCLN",
  "foreign_id": "1909242403",
  "amount": 0.0025
}

3

Process the API response

Extract the Lightning invoice from the address field in the API response:

{
  "data": {
    "id": 240379058,
    "currency": "BTCLN",
    "address": "lnbcrt1m1p5u93tfpp53wwjfugpyypf68mgwjfzq99x8cghlurxwpp680r9uyvd8qxkjulqdqqcqzysxqzuysp5fdzuturj4cttdaafw09j739adh4slxxqynnjpl6n208wqfc8ny6q9qxpqysgqgdgwm5hdt736pm3jkn0spp85zwx0023vlxj8s0fjkha55wtyg5hjxvmkjl6ee4ztxrc75j3q7qzxua7r28qujlvc3ykmaklczwccmkspazvfhu",
    "tag": null,
    "foreign_id": "1909242403",
    "expires_at": 1774373101
  }
}

4

Show the Lightning invoice to the user

Generate a QR code for the user to scan, or provide an Open wallet button:

5

Payment successful

Wait for a deposit callback from AlphaPo where status is confirmed, then show a deposit confirmation message.

​

Adding an Open wallet button on mobile

lightning:lnbcrt1m1p5u93tfpp53wwjfugpyypf68mgwjfzq99x8cghlurxwpp680r9uyvd8qxkjulqdqqcqzysxqzuysp5fdzuturj4cttdaafw09j739adh4slxxqynnjpl6n208wqfc8ny6q9qxpqysgqgdgwm5hdt736pm3jkn0spp85zwx0023vlxj8s0fjkha55wtyg5hjxvmkjl6ee4ztxrc75j3q7qzxua7r28qujlvc3ykmaklczwccmkspazvfhu

1. The customer taps the link on their mobile device.
2. Your site opens the lightning:lnbc... deeplink.
3. If the customer has a compatible wallet site installed, it opens with the invoice ready to pay.
4. If no compatible wallet is installed, the deeplink does not open and the customer may see an error such as No Lightning wallet is installed on your device.

​

Additional details

• Bitcoin withdrawals using the Lightning Network are not supported. To withdraw funds, first exchange BTCLN to BTC or another supported currency. Exchanges between BTCLN and BTC are always at a 1:1 rate with no fees.
• You can also convert BTCLN to any supported currency and withdraw in a single step by using the /withdrawal/crypto endpoint with the convert_to parameter set to the target currency.
• For more details about the /addresses/take endpoint, refer to Generate a crypto address.