Skip to main content

Tipping platform

Overview

Create tips for Strike users payable by anyone through the Lightning network.

How tipping works

Tipping flow includes invoice and quote resources. First the invoice is created for the tip receiver with an amount and optional description. Then the quote is created for that invoice. The quote is short lived and contains the payment details like source amount, target amount, conversion rate, encoded lightning invoice, expiration time, etc. The encoded lightning invoice can then be used to make a payment using any lightning wallet. Invoice is created in the UNPAID state and moved to PAID only when the quote generated for the invoice is paid. If the quote has expired before payment has been made, a new quote for the invoice can be created.

Strike tipping flow

Integration example

1. Issue an invoice

Use create invoice for receiver endpoint to issue an invoice for the tip receiver. The receiver is identified by the unique account handle. When created the invoice will be in UNPAID state.

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

In the example request just replace the placeholder values (values wrapped in <...>) with your values. Correlation id is optional but can be used to link the invoice in Strike system with some entity on the integrator side.

The response will look something like:

{
"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": "Tip",
"issuerId": "bf909224-3432-400b-895a-3010302f80f5",
"receiverId": "83dde585-4b8e-4e26-8b07-b2d273e907b7",
}

where issuerId is the id of your Strike account and receiverId is the id of the tip receiver.

To find which currencies are invoiceable for the receiver you can use an endpoint for getting the receiver’s profile by account handle if the profile is public. If the profile is private, the endpoint will return 404.

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

The response will be something like:

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

and you can pick any currency from the currencies list for which isInvoiceable is set to true.

If you need to know the invoice amount in some other currency (e.g. BTC) our rate endpoint can be used to fetch the conversion rates.

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": "2f065dda-bd57-44b0-a7c1-68eb59f3d2c0",
"description": "Tip",
"lnInvoice": "lnbcrt177330n1pscadshpp5u0waxwlgq3e8m04ks3csd47f56x2m3p37hulwrgqwes0xh6qf9tsdq9235hqcqzpgxqpdfppq8a9kt2kljvy32v428hxrxgy44apw8j6ysp5l5hwrr7kqylp3gws6gpkmksjsjqqw9qnfe69h5efy5q0t4csq45s9qyyssq4lm0qv2kv4d0yuymjwny6sr5k59m3l3hgx5zvpfwx8ttyyazf98pdjgpr842qk28gcztjl4xqjt5ufkj2recdcee889lsj6ujv403eqps4f0mh",
"onchainAddress": "bcrt1q8a9kt2kljvy32v428hxrxgy44apw8j6yj4d03u",
"expiration": "2021-11-12T18:44:52.735+00:00",
"expirationInSec": 13,
"sourceAmount": {
"amount": "0.00017733",
"currency": "BTC"
},
"targetAmount": {
"amount": "10.99",
"currency": "USD"
},
"conversionRate": {
"amount": "61974.8492",
"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.

If you need some additional info about the tip receiver use the get profile endpoint to get the receiver’s profile by account handle. However note that this is possible only if the receiver's profile is public. If the receiver profile is private this endpoint will return 404.

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

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 API 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 the tip has been successfully sent to the receiver.

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 tip has been successfully sent to the receiver.