Skip to main content

Commerce

Overview

Strike API can be used to create invoices and receive payments for goods and services. Create a Strike account and integrate the API in your checkout process and get paid via the Bitcoin Lightning network.

How payment process works

To receive a payment you first need to issue an invoice. When issued the invoice starts in the UNPAID state. Generate a quote for the invoice and present the lightning invoice to the customer. You can be notified about the invoice state change via a webhook. If the quote has been paid the state of the invoice will be changed to PAID and you can finalize the purchase. If the quote has expired it cannot be paid anymore so a new quote must be generated for the invoice.

Strike tipping flow

Integration example

1. Issue an invoice

During the checkout process, when a customer is ready to pay, use create invoice endpoint to issue an invoice. Specify the required amount, currency, description and correlation id. Correlation id is the id of the order in your system and is useful to correlate your order with Strike 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"
}
}

The response will be something like:

{
"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"
}

Since in this case you are the issuer and receiver, issuerId and receiverId will be set to the id of your Strike account.

You can use any invoiceable currency that is available for your account.

At any time you can look up the invoice by the id using the get invoice endpoint.

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

Also if you need to display the price in other currencies you can utilize rates endpoint to get exchange rates for the supported currencies.

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

2. Request a quote

Request a quote for the invoice using the quote generation endpoint. Specify the invoice for which the quote is generated using invoice id from the create invoice response.

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'

The response will look something like:

{
"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 quote is valid up to time specified in the expiration property. After that the quote cannot be paid anymore and the new one has to be created.

3. Share payment info

Use the lnInvoice from the quote response and display the lightning invoice as a QR code for payment.

4. Wait for invoice payment

To be notified when the invoice has been paid subscribe to the invoice.updated event. For details on how to subscribe to the event type check the webhooks section.

When the invoice has been updated the Strike will trigger the POST request to the webhook that you provided when creating the subscription. The request payload will have the following format:

{
"id": "245e40d8-f197-411c-8f20-a326d08da402",
"eventType": "invoice.updated",
"webhookVersion": "v1",
"data": {
"entityId": "<INVOICE_ID>",
"changes": [
"state"
]
},
"created": "2009-01-03T18:15:00+01:00",
"deliverySuccess": true
}

where entityId is the id of the invoice and changes indicates that state of the invoice has changed. Note how webhook payload doesn’t contain the new value of the invoice state so each time you are notified about the update, use get invoice endpoint to get the invoice state and see if it was paid.

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

Check the state property in the response. If the value is PAID the invoice has been paid and you have successfully received the funds on your Strike account.

If the invoice hasn’t been paid before the quote expires you’ll need to request a new quote. However since we don’t guarantee the delivery of the notifications it could happen that the invoice.updated notification hasn’t been delivered for some reason (e.g. temporary network issue) so it’s recommended that you check the status with get invoice endpoint at the quote expiration time. You can get the quote expiration time from the request quote endpoint response (see step 2). If the invoice status is still UNPAID, the quote has expired so go back to step 2 and create a new quote. If the invoice status is PAID the invoice has been paid and you have successfully received the funds on your Strike account.

5. Check invoices history

At any point you can check all of your invoices using paginated get invoices endpoint. The endpoint uses OData syntax for filtering, pagination and ordering. The endpoint supports ordering by created field and filtering by various fields such as created, currency, state and more. See the API reference for full details. Example request which filters only UNPAID invoices, orders ascending by creation time, skips 1 and takes top 2:

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>'

The response will be something like:

{
"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
}

where count represents the total number of invoices that satisfy the provided filter.