Skip to main content

Directing payments to Strike users

Overview​

The Strike API can be used to request payments over the Bitcoin Lightning Network and have those payments directed to a specific Strike user’s account to be received as dollars. This can be used for a variety of services, including bill splitting, third party billing, and invoicing. This walkthrough shows you how to use the Strike API for situations where the intended recipient of inbound payments is not your own account.

How the payment process works​

The process of directing payments to a Strike user begins with creating an invoice on behalf of that Strike user. 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 sets 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​

Directing a payment to a Strike user begins by creating an invoice which has the Strike user’s “handle” as its intended recipient. A handle is a unique identifier similar to a username that facilitates transactions to and from Strike users.

You can create an invoice by using the create invoice for a specified receiver endpoint, and specifying the intended recipient’s handle, 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 for a specified receiver:

Example request:
curl -X 'POST' \
 'https://<ENVIRONMENT>/v1/invoices/handle/<HANDLE>' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer <API_KEY>' \
 -H 'Content-Type: application/json' \
 -d '{
 "correlationId": "224bff37-021f-43e5-9b9c-390e3d834744",
 "description": "Payment handle by X on users behalf",
 "amount": {
   "currency": "USD",
   "amount": "10.99"
 }
}'

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

Below is the response to the request to create an invoice for a specified receiver:

Example response:
{
  "invoiceId": "23f3bb9f-55c3-4263-bdb2-670530c6c1d7",
  "amount": {
    "amount": "10.99",
    "currency": "USD"
  },
  "state": "UNPAID",
  "created": "2021-11-12T18:42:01.374248+00:00",
  "correlationId": "224bff37-021f-43e5-9b9c-390e3d834744",
  "description": "Payment handle by X on users behalf", 
  "issuerId": "bf909224-3432-400b-895a-3010302f80f5",
  "receiverId": "83dde585-4b8e-4e26-8b07-b2d273e907b7"
}

The above response shows the newly created invoice, which is in the UNPAID state and is identifiable by its unique invoiceId. Please note that the issuerId is the ID of your Strike account, since the invoice creation request came from your account, and the receiverId is the ID of the intended recipient’s Strike account.

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": "23f3bb9f-55c3-4263-bdb2-670530c6c1d7",
  "amount": {
    "amount": "10.99",
    "currency": "USD"
  },
  "state": "UNPAID",
  "created": "2021-11-12T18:42:01.374248+00:00",
  "description": "Payment handle by X on users behalf",
  "issuerId": "bf909224-3432-400b-895a-3010302f80f5",
  "receiverId": "83dde585-4b8e-4e26-8b07-b2d273e907b7"
}

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": "Payment handle by X on users behalf",
  "lnInvoice": "lnbcrt2406610n1pscajk9pp53w8whfszxhwyukdmeqgvrnavqzck68x9np8fhrvssg2s66zdrdcsdpzf9h8vmmfvdjjqen0wgsx7unyv4ezqvfjxvcqzpgxqzpffppqcuvchrllhnku2vxfdgjceup6xdnha94qsp5kgaq5vxhls6ug07saqkxkfn84hakmaztrcclychklna0jmen6hds9qyyssqzr5cfw9lqcaz7qzqtxyrzsp60ndezrg9nlqqzs6t8alffs7yay4r2w5vd6kpgde38kwx0vge7cxlur50hul6ky68pjprw6suc7c6encq3xfh93",
  "onchainAddress": "bcrt1qcuvchrllhnku2vxfdgjceup6xdnha94q3s2jdy",
  "expiration": "2021-11-12T20:13:35.019+00:00",
  "expirationInSec": 41,
  "sourceAmount": {
    "amount": "0.00017632",
    "currency": "BTC"
  },
  "targetAmount": {
    "amount": "10.99",
    "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 and direct the 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": "23f3bb9f-55c3-4263-bdb2-670530c6c1d7",
    "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": "23f3bb9f-55c3-4263-bdb2-670530c6c1d7",
  "amount": {
    "amount": "10.99",
    "currency": "USD"
  },
  "state": "PAID",
  "created": "2021-11-12T18:42:01.374248+00:00",
  "description": "Payment handle by X on users behalf",
  "issuerId": "bf909224-3432-400b-895a-3010302f80f5",
  "receiverId": "83dde585-4b8e-4e26-8b07-b2d273e907b7"
}

If the value of the invoice’s state is PAID, then the payment was successful and the funds have been deposited into the designated recipient’s 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. See the API reference for full details.

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.