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.

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, as it offers a temporary conversion rate between the invoiced currency and bitcoin.

Generating a quote produces a corresponding Lightning invoice, which is a unique alphanumeric code that can be presented in the form of a scannable QR code to anyone willing to pay. The Lightning invoice QR code contains all the necessary information to complete the payment, including the quoted bitcoin amount and the destination of the payment. You can find an example Lightning invoice QR code and corresponding alphanumeric representation below

Invoice QR code

LNBC10U1P3PJ257PP5YZTKWJCZ5FTL5LAXKAV23ZMZEKAW37ZK6KMV80PK4XAEV5QHTZ7QDPDWD3XGER9WD5KWM36YPRX7U3QD36KUCMGYP282ETNV3SHJCQZPGXQYZ5VQSP5USYC4LK9CHSFP53KVCNVQ456GANH60D89REYKDNGSMTJ6YW3NHVQ9QYYSSQJCEWM5CJWZ4A6RFJX77C490YCED6PEMK0UPKXHY89CMM7SCT66K8GNEANWYKZGDRWRFJE69H9U5U0W57RRCSYSAS7GADWMZXC8C6T0SPJAZUP6

When a payer scans the QR code and confirms the payment within their Lightning-enabled wallet app, bitcoin is sent via their wallet app, routed through the Lightning Network, converted into the invoiced amount and currency, and delivered to the recipient’s account. Once the payment has been delivered, the original invoice transitions to the PAID state, and the payment process can be finalized.

Receiving flow

Integration Walkthrough​

1. Create an invoice​​

Receiving a payment begins by creating an invoice. You can create an invoice by using the create 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, 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 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": false
    },
    {
      "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 canReceive set to true and isInvoiceable set to true for USD, meaning this user’s account can receive funds and be the recipient of invoices in USD.

Now that 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 rates endpoint to get conversion rates for the 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 create invoice endpoint described in step 1.

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), and an expiration time. After the expiration time has passed, the quote will no longer be usable and a new quote must be generated.

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 using the quote’s lnInvoice, which contains the necessary information to execute the payment, including the amount to be paid in bitcoin and the destination of the payment. This lnInvoice can be displayed as a QR code and presented to a payer for them to scan and confirm the payment with their Lightning-enabled wallet app.

There are a number of libraries available to facilitate displaying QR codes, including the qrcode.react library.

4. Receive payment​

The payer scans the Lightning invoice QR code and confirms the payment in their wallet app prior to the quote expiration time. If the payment is successful, the original invoice will transition to the PAID state.

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 event ID and the entityId is the ID of the invoice, 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.

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 value of the invoice’s state is 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, which will contain a new corresponding Lightning invoice to be presented to the payer.

If the invoice state remains UNPAID as the quote expires, return to step 2 and generate a new quote.

5. Check invoices history​​

At any point you use the get invoices endpoint 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, apply a filter to include only those that are UNPAID, 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": 3
}

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