API docs by Redocly

Swiss Bitcoin Pay Merchant's API (1.2.1)

Download OpenAPI specification:Download

E-mail: hello@swiss-bitcoin-pay.ch Terms of Service

API for merchants to connect to their Swiss Bitcoin Pay's wallet account.
For creating an invoice, you need to provide the api-key header with your API Key, available in your dashboard (not required for reading invoice).

checkout

Everything about creating and checking invoices

Create an invoice

Authorizations:
ApiKeyAuth
Request Body schema: application/json
title
required
string

What will appear on the client's wallet

description
string
amount
required
number

How much to charge, with decimals. ex: 21.50

unit
string
Default: "Your account's default currency"

Optionally select a reference currency you want use. All major currencies are supported, along with sat and BTC

onChain
boolean
Default: false

If Onchain payment is available

delay
number
Default: 10

How long (in minutes) the client have to pay the invoice before it gets expired

email
string

An message containing the created invoice will be sent to this email

emailLanguage
string

In which language the email should be sent. Currently only supports en and fr

redirect
boolean

If the server should directly return a 302 REDIRECT request to force the user's browser to go to the invoice payment page

redirectAfterPaid
string

Where the user will be redirected after paid (confirmation page).
(Lightning: instant, Onchain: after 1 confirmation)

object

Our backend will call your webhook with a POST request will all the invoice details once it has been paid (Lightning: instant, Onchain: after 1 confirmation), unconfirmed (in case of an Onchain payment just discovered), or expired.
You need to manually check on your side the status value (will be either paid, unconfirmed, or expired).
The webhook configuration is never visible to the user

object

Any extra parameters that will be returned to you when your webhook is called

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "amount": 0,
  • "unit": "Your account's default currency",
  • "onChain": false,
  • "delay": 10,
  • "email": "string",
  • "emailLanguage": "string",
  • "redirect": true,
  • "redirectAfterPaid": "string",
  • "webhook": {
    },
  • "extra": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "pr": "string",
  • "checkoutUrl": "string",
  • "onChainAddr": "string"
}

Check invoice status

path Parameters
id
required
string

Hash ID of invoice

Responses

Response samples

Content type
application/json
{
  • "createdAt": 0,
  • "delay": 0,
  • "pr": "string",
  • "amount": 0,
  • "btcAmount": "string",
  • "unit": "string",
  • "isPaid": true,
  • "isInit": true,
  • "isExpired": true,
  • "paymentMethod": "lightning",
  • "paidAt": 0,
  • "title": "string",
  • "description": "string",
  • "hash": "string",
  • "fiatAmount": 0,
  • "fiatUnit": "string",
  • "onChainAddr": "string",
  • "minConfirmations": 0,
  • "confirmations": 0,
  • "txid": "string",
  • "idPending": true,
  • "redirectAfterPaid": "string"
}

atm

Everything about the ATM service

You need to provide 2 keys in the header:
1. api-key: Your API key available in your dashboard
2. sbp-sig: An HMAC SHA-256 signature of your payload, with the encryption key in your dashboard as sha256=${signature}

Create LNURLw QR code

Authorizations:
ApiKeyAuthSbpSigAuth
Request Body schema: application/json
amount
required
number

How much to withdraw. ex: 21

unit
string
Default: "Your account's default currency"

In which currency is the amount denominated. ex: EUR. All major currencies are supported, along with sat and BTC

title
string

Set a specific title that your client will see & keep when scanning your LNURLw QR code

uses
number
Default: 1

How many times the LNURLw QR code can be used to withdraw sats

wait_time
number
Default: 1

How long to wait in seconds between each withdraw

deviceName
string

An optional device name to keep track in your dashboard from which device/software the LNURLw QR code was generated. ex. ATM A

customNote
string

An optional note that will be visible in your Dashboard's activities list

language
string

In which language the default title should be expressed. Currently only supports en and fr. No effect if you defined title

webhook_url
string

Webhook called when the QR code is withdrawn

webhook_body
string

Attached body to the webhook

webhook_headers
string

Attached headers to the webhook

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "unit": "Your account's default currency",
  • "title": "string",
  • "uses": 1,
  • "wait_time": 1,
  • "deviceName": "string",
  • "customNote": "string",
  • "language": "string",
  • "webhook_url": "string",
  • "webhook_body": "string",
  • "webhook_headers": "string"
}

Response samples

Content type
application/json
{
  • "lnurl": "string",
  • "amount": "string"
}