API docs by Redocly

Swiss Bitcoin Pay Merchant's API (1.3.0)

Download OpenAPI specification:

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 (the API Key is not required to read invoice's status with webhook or GET requests).

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

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

emailLanguage
string
Enum: "en" "fr" "de" "it" "es" "pt" "fi"

In which language the email should be sent. If language is unknown, will fall back to en (English)

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

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

Custom schemas and deeplinks are also supported.

This information is revelated by the server only when the invoice is fully settled, so it is safe to hide a "secret" redirection page or use this parameter as a paywall redirection.

object

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

object (Device)

An optional device info to keep track in your dashboard and exports from which device/software the invoice code was generated. ex. name=Satohi's Phone and type=phone

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": "en",
  • "redirect": true,
  • "redirectAfterPaid": "string",
  • "webhook": {
    },
  • "device": {
    },
  • "extra": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "pr": "string",
  • "checkoutUrl": "string",
  • "onChainAddr": "string",
  • "amount": 0
}

Get invoice

path Parameters
id
required
string <uuid>

ID of invoice

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "description": "string",
  • "merchantName": "string",
  • "status": "draft",
  • "tag": "string",
  • "createdAt": 0,
  • "paidAt": 0,
  • "amount": 0,
  • "paymentDetails": [
    ],
  • "paymentMethod": "lightning",
  • "input": {
    },
  • "delay": 0,
  • "extra": { },
  • "device": {
    },
  • "redirectAfterPaid": "string",
  • "isInit": true,
  • "btcAmount": "string",
  • "pr": "string",
  • "isPaid": true,
  • "isExpired": true,
  • "hash": "string",
  • "fiatAmount": 0,
  • "fiatUnit": "string",
  • "onChainAddr": "string",
  • "minConfirmations": 0,
  • "confirmations": 0,
  • "txId": "string",
  • "isPending": true
}

[Websocket] Receive invoice updates

Get notified when any property of an invoice changes (eg. invoice settled, lightning invoice and sat amount updated)

This endpoint initiates a WebSocket connection.

URL: wss://api.swiss-bitcoin-pay.ch/invoice

To connect, use the WebSocket protocol:

const socket = new WebSocket("wss://api.swiss-bitcoin-pay.ch/invoice");

Once connected, simply send the invoice ID with which you want to be notified as JSON:

{
  "id": "INVOICE_ID"
}
path Parameters
id
required
string <uuid>

ID of invoice

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "description": "string",
  • "merchantName": "string",
  • "status": "draft",
  • "tag": "string",
  • "createdAt": 0,
  • "paidAt": 0,
  • "amount": 0,
  • "paymentDetails": [
    ],
  • "paymentMethod": "lightning",
  • "input": {
    },
  • "delay": 0,
  • "extra": { },
  • "device": {
    },
  • "redirectAfterPaid": "string",
  • "isInit": true,
  • "btcAmount": "string",
  • "pr": "string",
  • "isPaid": true,
  • "isExpired": true,
  • "hash": "string",
  • "fiatAmount": 0,
  • "fiatUnit": "string",
  • "onChainAddr": "string",
  • "minConfirmations": 0,
  • "confirmations": 0,
  • "txId": "string",
  • "isPending": true
}