Skip to main content

Receiving payments

Overview​

The Strike API can be used to receive cash payments for goods and services. This walkthrough shows you how to integrate the Strike API into your payment experience and get paid via the Bitcoin Lightning Network in dollars, or for select business accounts, in bitcoin. Please contact business@strike.me for more information.

How receiving a payment works​

Receiving a payment via the Strike API begins with creating an invoice. An invoice is a request for a payment in a desired amount and currency. Invoices begin in the UNPAID state.

After the invoice has been created, a quote must be generated, which specifies the cost of paying the invoiced amount in bitcoin. This quote has an expiration time, offering a temporary window through which the payment can be made.

Generating a quote produces both a corresponding Lightning invoice and an on-chain Bitcoin address. A Lightning invoice is an alphanumeric code that contains within it the necessary information to complete a payment, including an amount to be paid in bitcoin and a payment destination. An on-chain Bitcoin address is an alphanumeric code that acts as the destination for payments on the Bitcoin blockchain. Both Lightning invoices and on-chain Bitcoin addresses can be presented to a payer as a string of characters or as a scannable QR code.

When a payer scans the QR code and confirms the payment within their Lightning or on-chain-enabled Bitcoin wallet app, bitcoin is sent via their wallet app, routed through either the Lightning Network or sent on-chain, and delivered to the recipient. Once the payment has been delivered, the original invoice transitions to the PAID state, and the payment process can be finalized.

Please note that Lightning transactions are faster and cheaper than on-chain transactions, and are often considered preferable for many bitcoin payment solutions.

Receiving flow

Integration walkthrough​

1. Create an invoice​

Receiving a payment begins by creating an invoice. You can create an invoice by using the issue invoice endpoint, and specifying the desired payment amount and currency to be received. You may also add an optional description and correlationId to the invoice. As a best practice, we recommend that you add a correlationId that is universally identifiable by you, and which can be used to correlate the invoice with any corresponding invoice tracking systems. The correlationId must be unique otherwise the invoice creation will fail.

Below is an example request to create an invoice:

Example request:
curl -X 'POST' \
 'https://<ENVIRONMENT>/v1/invoices' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY> \
 -H 'Content-Type: application/json' \
 -d '{
 "correlationId": "224bff37-021f-43e5-9b9c-390e3d834750",
 "description": "Invoice for order 123",
 "amount": {
   "currency": "USD",
   "amount": "150.00"
 }
}'

To use this example yourself, simply replace the placeholder values with your own values. The <ENVIRONMENT> should be replaced with api.strike.me, and the <API_KEY> should be replaced with your own API key bearer token.

Below is the response to the invoice creation request:

Example response:
{
 "invoiceId": "6b91e56d-fce9-4eec-995f-1d08fe6ba380",
 "amount": {
   "amount": "150.00",
   "currency": "USD"
 },
 "state": "UNPAID",
 "created": "2021-11-12T20:08:45.98159+00:00",
 "correlationId": "224bff37-021f-43e5-9b9c-390e3d834750",
 "description": "Invoice for order 123",
 "issuerId": "bf909224-3432-400b-895a-3010302f80f5",
 "receiverId": "bf909224-3432-400b-895a-3010302f80f5"
}

The above response shows the newly created invoice for $150.00 USD, which is in the UNPAID state and is identifiable by its unique invoiceId. For this example, both the issuerId and receiverId are returned as the same value: the ID of the Strike account that created the invoice. This is because the creator of the invoice and the intended recipient of the funds are the same Strike account.

In situations where you are creating an invoice on behalf of a third-party, the receiverId will differ from the issuerId. Learn more about creating invoices for third-parties here.

When creating an invoice, you may specify any invoiceable currency that is available for your account. To check which currencies are invoiceable for a specific Strike user, you can use the fetch public account profile info by handle endpoint. If the Strike user’s profile is set to private, the endpoint will return 404.

Below is an example request to fetch public account profile info:

Example request:
curl -X 'GET' \
 'https://<ENVIRONMENT>/v1/accounts/handle/<HANDLE>/profile' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY>'

Below is the response to the fetch public account profile info request:

Example response:
{
 "handle": "astrid_waters64",
 "canReceive": true,
 "currencies": [
   {
     "currency": "BTC",
     "isDefaultCurrency": false,
     "isAvailable": true,
     "isInvoiceable": true
   },
   {
     "currency": "USD",
     "isDefaultCurrency": true,
     "isAvailable": true,
     "isInvoiceable": true
   }
 ]
}

Any currency for which isInvoiceable is returned as true can be used to create an invoice with this Strike user as the intended recipient. In the above example, this Strike user has both canReceive and isInvoiceable set to true for both BTC and USD, meaning this user’s account can receive funds and issue invoices in bitcoin and US dollars.

If you wish to receive payments in bitcoin, you can issue the invoice creation request with the currency and amount set as bitcoin, provided your account has isInvoiceable for BTC as true.

Below is an example request to issue an invoice denominated in bitcoin:

Example request:
curl -X 'POST' \
 'https://<ENVIRONMENT>/v1/invoices' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY> \
 -H 'Content-Type: application/json' \
 -d '{
 "correlationId": "224bff37-021f-43e5-9b9c-390e3d834750",
 "description": "Invoice for order 123",
 "amount": {
   "currency": "BTC",
   "amount": "0.00004200"
 }
}'

Below is the response to the bitcoin-denominated invoice creation request:

Example response:
{
 "invoiceId": "6b91e56d-fce9-4eec-995f-1d08fe6ba380",
 "amount": {
   "amount": "0.00004200",
   "currency": "BTC"
 },
 "state": "UNPAID",
 "created": "2023-05-08T18:05:27.6218085+00:00",
 "correlationId": "224bff37-021f-43e5-9b9c-390e3d834750",
 "description": "Invoice for order 123",
 "issuerId": "bf909224-3432-400b-895a-3010302f80f5",
 "receiverId": "bf909224-3432-400b-895a-3010302f80f5"
}

Once the invoice has been created, you may look up the invoice and its details by using the find invoice endpoint and specifying the invoiceId.

Below is an example request to find an invoice:

Example request:
curl -X 'GET' \
 'https://<ENVIRONMENT>/v1/invoices/<INVOICE_ID>' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY>'

Below is the response to the find invoice request:

Example response:
{
 "invoiceId": "6b91e56d-fce9-4eec-995f-1d08fe6ba380",
 "amount": {
   "amount": "150.00",
   "currency": "USD"
 },
 "state": "UNPAID",
 "created": "2021-11-12T20:08:45.98159+00:00",
 "description": "Invoice for order 123",
 "issuerId": "bf909224-3432-400b-895a-3010302f80f5",
 "receiverId": "bf909224-3432-400b-895a-3010302f80f5"
}

If you need to display the invoice amount in other currencies, you can use the get currency exchange rates endpoint to retrieve the rates for supported currencies.

Below is an example request to retrieve conversion rates:

Example request:
curl -X 'GET' \
 'https://<ENVIRONMENT>/v1/rates/ticker' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY>'

Below is the response to the conversion rates request:

Example response:
[
  {
    "amount": "23096.6400",
    "sourceCurrency": "BTC",
    "targetCurrency": "USD"
  },
  {
    "amount": "0.0000433",
    "sourceCurrency": "USD",
    "targetCurrency": "BTC"
  },
  {
    "amount": "0.9998",
    "sourceCurrency": "USD",
    "targetCurrency": "USDT"
  },
  {
    "amount": "1.0002",
    "sourceCurrency": "USDT",
    "targetCurrency": "USD"
  },
  {
    "amount": "23092.9500",
    "sourceCurrency": "BTC",
    "targetCurrency": "USDT"
  },
  {
    "amount": "0.0000433",
    "sourceCurrency": "USDT",
    "targetCurrency": "BTC"
  }
]

2. Generate a quote​

Once the invoice has been created, a quote must be generated for paying the invoice. A quote is generated using the quote generation endpoint, which will require the invoiceId that was returned in response to the invoice creation request described in step 1.

The quote serves as a necessary step to retrieve the Lightning invoice (lnInvoice) or Bitcoin on-chain address (onchainAddress) in preparation for execution. For cross-currency payments, such as paying a USD-invoice in bitcoin, the quote serves as a temporary exchange rate that can be executed when called upon.

When generating the quote, you can also add a descriptionHash, which is an optional parameter as defined in the BOLT11 spec. The descriptionHash can be used to implement the LN-URL payRequest spec. If a descriptionHash is provided, it will be added in the resulting Lightning invoice in lieu of the invoice description detailed in step 1. The original description can still be retrieved via the find invoice endpoint.

Below is an example request to generate a quote:

Example request:
curl -X 'POST' \
 'https://<ENVIRONMENT>/v1/invoices/<INVOICE_ID>/quote' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY>' \
 -H 'Content-Length: 0'

Below is the response to the quote generation request:

Example response:
{
 "quoteId": "ee1c09c4-a6a3-4856-b886-e75fc613fea2",
 "description": "Invoice for order 123",
 "lnInvoice": "lnbcrt2406610n1pscajk9pp53w8whfszxhwyukdmeqgvrnavqzck68x9np8fhrvssg2s66zdrdcsdpzf9h8vmmfvdjjqen0wgsx7unyv4ezqvfjxvcqzpgxqzpffppqcuvchrllhnku2vxfdgjceup6xdnha94qsp5kgaq5vxhls6ug07saqkxkfn84hakmaztrcclychklna0jmen6hds9qyyssqzr5cfw9lqcaz7qzqtxyrzsp60ndezrg9nlqqzs6t8alffs7yay4r2w5vd6kpgde38kwx0vge7cxlur50hul6ky68pjprw6suc7c6encq3xfh93",
 "onchainAddress": "bcrt1qcuvchrllhnku2vxfdgjceup6xdnha94q3s2jdy",
 "expiration": "2021-11-12T20:13:35.019+00:00",
 "expirationInSec": 41,
 "sourceAmount": {
   "amount": "0.00240661",
   "currency": "BTC"
 },
 "targetAmount": {
   "amount": "150.00",
   "currency": "USD"
 },
 "conversionRate": {
   "amount": "62328.3374",
   "sourceCurrency": "BTC",
   "targetCurrency": "USD"
 }
}

The above response shows the generated quote, identifiable by its unique quoteId. The quote contains the amount needed to pay the invoice in bitcoin, a corresponding Lightning invoice (lnInvoice), a Bitcoin on-chain address (onchainAddress), an expiration period, and the exchange rate (conversionRate) between the source and target currencies. After the expiration period has passed, the quote will no longer be usable and a new quote must be generated.

Please note that for bitcoin-denominated invoices, the conversionRate will simply be 1 and the expiration period will be 1 hour (3,600 seconds). For cross-currency invoices, the expiration period will be 2 minutes (120 seconds).

3. Share payment info​

After a quote has been generated, the next step is to present the payment information to the payer. This can be done by sharing the quote’s lnInvoice or onchainAddress as a string of characters or a scannable QR code. The lnInvoice has encoded within it the amount to be paid in bitcoin and the payment destination, whereas the onchainAddress provides a payment destination for an on-chain transaction.

The payer can scan the QR code or paste the string of characters using their Lightning or on-chain-enabled Bitcoin wallet app, and confirm the payment.

There are a number of libraries available to facilitate displaying QR codes, including the qrcode.react library. You can find an example Lightning invoice QR code and corresponding alphanumeric representation below:

Invoice QR code

LNBC10U1P3PJ257PP5YZTKWJCZ5FTL5LAXKAV23ZMZEKAW37ZK6KMV80PK4XAEV5QHTZ7QDPDWD3XGER9WD5KWM36YPRX7U3QD36KUCMGYP282ETNV3SHJCQZPGXQYZ5VQSP5USYC4LK9CHSFP53KVCNVQ456GANH60D89REYKDNGSMTJ6YW3NHVQ9QYYSSQJCEWM5CJWZ4A6RFJX77C490YCED6PEMK0UPKXHY89CMM7SCT66K8GNEANWYKZGDRWRFJE69H9U5U0W57RRCSYSAS7GADWMZXC8C6T0SPJAZUP6

4. Receive the payment​

The payer scans the Lightning invoice or on-chain address QR code and confirms the payment in their wallet app prior to the quote’s expiration.

For cross-currency payments (such as BTC to USD), the quote’s expiration period is set at 2 minutes, within which the Lightning invoice must be paid or the on-chain transaction must be broadcast to the Bitcoin blockchain. If the 2 minutes expires, any Lightning payment sent to the lnInvoice will fail and any on-chain payment sent to the onchainAddress will be held in PENDING status, until a refreshed quote is issued by contacting api@strike.me.

For same-currency payments (such as BTC to BTC), the quote’s expiration period is set at 1 hour, within which the Lightning invoice must be paid or the on-chain transaction must be broadcast to the Bitcoin blockchain.

5. Check payment status​

If the payment is successful, the original Strike invoice from step 1 will transition to the PAID state. Payments received via an on-chain transaction will transition from PENDING to PAID after one confirmation on the Bitcoin blockchain.

You can be notified of an invoice state change by subscribing to the invoice.updated webhook event. When one of your subscribed events occurs, a POST request will be automatically made to the webhook URI of the subscription. For details on how to subscribe to events visit the webhooks section.

Below is an example of a webhook subscription response:

Example response:
{
 "id": "245e40d8-f197-411c-8f20-a326d08da402",
 "eventType": "invoice.updated",
 "webhookVersion": "v1",
 "data": {
   "entityId": "6b91e56d-fce9-4eec-995f-1d08fe6ba380",
   "changes": [
     "state"
   ]
 },
 "created": "2022-01-03T18:15:00+01:00",
 "deliverySuccess": true
}

In this response, the “id” is the webhook event ID and the entityId is the invoiceId created in step 1, indicating that the state of the invoice has changed.

Please note that the webhook subscription response doesn’t contain the new invoice state, rather it describes that the state has changed. To request the new state of the invoice, use the find invoice endpoint and specify the relevant invoiceId.

Below is an example of a find invoice request:

Example request:
curl -X 'GET' \
 'https://<ENVIRONMENT>/v1/invoices/<INVOICE_ID>' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY>'

Below is the response to the find invoice request:

Example response:
{
 "invoiceId": "6b91e56d-fce9-4eec-995f-1d08fe6ba380",
 "amount": {
   "amount": "150.00",
   "currency": "USD"
 },
 "state": "PAID",
 "created": "2021-11-12T20:08:45.98159+00:00",
 "description": "Invoice for order 123",
 "issuerId": "bf909224-3432-400b-895a-3010302f80f5",
 "receiverId": "bf909224-3432-400b-895a-3010302f80f5"
}

If the invoice’s state is returned as PAID, then the payment was successful and the funds have been deposited into your Strike account.

If the payment is not made before the quote expires, you’ll need to generate a new quote (at the start of step 2), which will contain a new corresponding lnInoivce and onchainAddress to be presented to the payer.

You can also use the get invoices endpoint at any time to retrieve information on multiple invoices. When using this endpoint, you can filter by various fields such as the invoice’s creation date, currency, current state, issuerId, receiverId, payerId, and correlationId. This endpoint uses OData syntax for filtering, pagination, and ordering.

The below example is a request to retrieve invoices, and apply a filter to include only those in an UNPAID state, order them in ascending order by creation time, skip the first invoice, and return only the top 2 invoices:

Example request:
curl -X 'GET' \
'https://<ENVIRONMENT>/v1/invoices?%24filter=state%20eq%20%27UNPAID%27&%24orderby=created%20asc&%24skip=1&%24top=2' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY>'

Below is the response to the filtered and ordered get invoices request:

Example response:
{
 "items": [
   {
     "invoiceId": "487b2454-31eb-43e0-8743-48d0020738d7",
     "amount": {
       "currency": "USD",
       "amount": "15.00"
     },
     "state": "UNPAID",
     "created": "2021-09-09T03:57:47.829226+02:00",
     "description": "stack sats",
     "issuerId": "bf909224-3432-400b-895a-3010302f80f5",
     "receiverId": "bf909224-3432-400b-895a-3010302f80f5"
   },
   {
     "invoiceId": "6f648c48-882a-4cf8-ad2c-d53cb699a073",
     "amount": {
       "currency": "USD",
       "amount": "150.00"
     },
     "state": "UNPAID",
     "created": "2021-10-30T20:30:27.071595+02:00",
     "correlationId": "224bff37-021f-43e5-9b9c-390e3d834741",
     "description": "Invoice for order 123",
     "issuerId": "bf909224-3432-400b-895a-3010302f80f5",
     "receiverId": "bf909224-3432-400b-895a-3010302f80f5"
   }
 ],
 "count": 2
}

The count at the end of the response represents the total number of invoices that satisfy the provided filter.