Merchant Auth

Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context.

Log in

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/login

Authenticates with email and password. Returns either an authenticated session (tokens, user, memberships) when $case is authenticated, or an mfaToken to complete via 2FA when $case is mfa_required.

Body required

application/json

emailstringrequired

Example:string

passwordstringrequired

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/login

cURL

curl -X POST "$BASE_URL/merchant/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "string",
  "password": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "$case": "authenticated",
      "tokens": {
        "accessToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "refreshToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "expiresAt": 1718012345
      },
      "user": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "email": "string",
        "emailVerified": true,
        "displayName": "Satoshi Coffee",
        "avatarUrl": "string",
        "twoFactorEnabled": true,
        "status": "active"
      },
      "memberships": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantName": "Satoshi Coffee",
          "role": "admin",
          "status": "active",
          "isCustodial": true,
          "isDemo": true,
          "actionsBlocked": true
        }
      ],
      "activeMerchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  }
}

Register

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/register

Creates a new merchant user from email and password, with optional displayName and merchantName (bootstraps the first merchant with the user as admin). Returns the new userId and status.

Body required

application/json

emailstringrequired

Example:string

passwordstringrequired

Example:string

displayNamestring

Public display name shown to payers (optional).

Example:Satoshi Coffee

merchantNamestring

Merchant's internal name.

Example:Satoshi Coffee

referralCodestring

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/register

cURL

curl -X POST "$BASE_URL/merchant/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "string",
  "password": "string",
  "displayName": "Satoshi Coffee",
  "merchantName": "Satoshi Coffee",
  "referralCode": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  }
}

Refresh tokens

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/refresh

Exchanges a valid refreshToken for a fresh tokens bundle (accessToken, refreshToken, expiresAt).

Body required

application/json

refreshTokenstringrequired

Long-lived JWT refresh token. Use it at Refresh access tokens to obtain a new token pair.

Example:

eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3a…

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/refresh

cURL

curl -X POST "$BASE_URL/merchant/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "tokens": {
        "accessToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "refreshToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "expiresAt": 1718012345
      }
    }
  }
}

Log out

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/logout

Revokes the given refreshToken, or the current session if omitted. Returns { ok }.

Authorization: merchantAuth

Body required

application/json

refreshTokenstring

Long-lived JWT refresh token. Use it at Refresh access tokens to obtain a new token pair.

Example:

eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3a…

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/logout

cURL

curl -X POST "$BASE_URL/merchant/auth/logout" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "refreshToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}

Current user

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/me

Returns the authenticated user profile and the list of memberships linking the user to merchants with a role.

Authorization: merchantAuth

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/me

cURL

curl -X POST "$BASE_URL/merchant/auth/me" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "user": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "email": "string",
        "emailVerified": true,
        "displayName": "Satoshi Coffee",
        "avatarUrl": "string",
        "twoFactorEnabled": true,
        "status": "active"
      },
      "memberships": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantName": "Satoshi Coffee",
          "role": "admin",
          "status": "active",
          "isCustodial": true,
          "isDemo": true,
          "actionsBlocked": true
        }
      ],
      "activeMerchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "walletLinked": true,
      "walletAddress": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
      "hasReferralAttribution": true
    }
  }
}

Verify email

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/verify-email

Confirms an email address using the email and the emailed code. On success the user is signed in: returns the full auth bundle (tokens, user, memberships) so the client can log straight into the merchant cabinet without a separate login.

Body required

application/json

emailstringrequired

Example:string

codestringrequired

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/verify-email

cURL

curl -X POST "$BASE_URL/merchant/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "string",
  "code": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "tokens": {
        "accessToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "refreshToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "expiresAt": 1718012345
      },
      "user": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "email": "string",
        "emailVerified": true,
        "displayName": "Satoshi Coffee",
        "avatarUrl": "string",
        "twoFactorEnabled": true,
        "status": "active"
      },
      "memberships": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantName": "Satoshi Coffee",
          "role": "admin",
          "status": "active",
          "isCustodial": true,
          "isDemo": true,
          "actionsBlocked": true
        }
      ],
      "activeMerchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  }
}

OAuth login

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/oauth/login

Logs in via an OAuth provider using authCode or idToken (with optional redirectUri); merchantName bootstraps the first merchant for new accounts. Returns an authenticated session or an mfaToken challenge.

Body required

application/json

providerenumrequired

applegoogle

Example:apple

authCodestring

Example:string

idTokenstring

Example:

eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3a…

redirectUristring

Example:string

merchantNamestring

Merchant's internal name.

Example:Satoshi Coffee

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/oauth/login

cURL

curl -X POST "$BASE_URL/merchant/auth/oauth/login" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "apple",
  "authCode": "string",
  "idToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
  "redirectUri": "string",
  "merchantName": "Satoshi Coffee"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "$case": "authenticated",
      "tokens": {
        "accessToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "refreshToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "expiresAt": 1718012345
      },
      "user": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "email": "string",
        "emailVerified": true,
        "displayName": "Satoshi Coffee",
        "avatarUrl": "string",
        "twoFactorEnabled": true,
        "status": "active"
      },
      "memberships": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantName": "Satoshi Coffee",
          "role": "admin",
          "status": "active",
          "isCustodial": true,
          "isDemo": true,
          "actionsBlocked": true
        }
      ],
      "activeMerchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  }
}

Change password

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/password/change

Sets newPassword for the current user; oldPassword is required unless setting a password for the first time. Returns { ok }.

Authorization: merchantAuth

Body required

application/json

oldPasswordstring

Example:string

newPasswordstringrequired

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/password/change

cURL

curl -X POST "$BASE_URL/merchant/auth/password/change" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "oldPassword": "string",
  "newPassword": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}

Forgot password

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/password/forgot

Triggers a password-reset email for the given email. Always returns { ok } to avoid account enumeration.

Body required

application/json

emailstringrequired

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/password/forgot

cURL

curl -X POST "$BASE_URL/merchant/auth/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}

Reset password

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/password/reset

Sets newPassword using a reset token from the password-reset email. Returns { ok }.

Body required

application/json

tokenstringrequired

Example:

eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3a…

newPasswordstringrequired

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/password/reset

cURL

curl -X POST "$BASE_URL/merchant/auth/password/reset" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
  "newPassword": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}

Verify 2FA

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/2fa/verify

Completes an MFA login challenge with the mfaToken and a TOTP or recovery code. Returns an authenticated session (tokens, user, memberships).

Body required

application/json

mfaTokenstringrequired

Example:

eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3a…

codestringrequired

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/2fa/verify

cURL

curl -X POST "$BASE_URL/merchant/auth/2fa/verify" \
  -H "Content-Type: application/json" \
  -d '{
  "mfaToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
  "code": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "tokens": {
        "accessToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "refreshToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "expiresAt": 1718012345
      },
      "user": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "email": "string",
        "emailVerified": true,
        "displayName": "Satoshi Coffee",
        "avatarUrl": "string",
        "twoFactorEnabled": true,
        "status": "active"
      },
      "memberships": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantName": "Satoshi Coffee",
          "role": "admin",
          "status": "active",
          "isCustodial": true,
          "isDemo": true,
          "actionsBlocked": true
        }
      ],
      "activeMerchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  }
}

Set up TOTP

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/2fa/totp/setup

Begins TOTP enrollment, returning the secret, otpauthUri, and a qr data URI for the authenticator app. TOTP is not active until confirmed via enable.

Authorization: merchantAuth

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/2fa/totp/setup

cURL

curl -X POST "$BASE_URL/merchant/auth/2fa/totp/setup" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "secret": "string",
      "otpauthUri": "string",
      "qr": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005"
    }
  }
}

Enable TOTP

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/2fa/totp/enable

Activates TOTP by confirming a code from the authenticator. Returns one-time recoveryCodes shown only once.

Authorization: merchantAuth

Body required

application/json

codestringrequired

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/2fa/totp/enable

cURL

curl -X POST "$BASE_URL/merchant/auth/2fa/totp/enable" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "code": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "recoveryCodes": [
        "string"
      ]
    }
  }
}

Disable TOTP

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/2fa/totp/disable

Disables TOTP after re-authenticating with a current TOTP code or the account password. Returns { ok }.

Authorization: merchantAuth

Body required

application/json

codestring

Example:string

passwordstring

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/2fa/totp/disable

cURL

curl -X POST "$BASE_URL/merchant/auth/2fa/totp/disable" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "code": "string",
  "password": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}

Passkey register options

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/passkey/register/options

Returns WebAuthn publicKeyOptions (PublicKeyCredentialCreationOptions incl. challenge) to pass to navigator.credentials.create() for registering a new passkey.

Authorization: merchantAuth

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/passkey/register/options

cURL

curl -X POST "$BASE_URL/merchant/auth/passkey/register/options" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "publicKeyOptions": {}
    }
  }
}

Passkey register verify

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/passkey/register/verify

Verifies the authenticator attestation credential (with optional deviceLabel) and stores the passkey. Returns the created credential descriptor.

Authorization: merchantAuth

Body required

application/json

credentialany

PublicKeyCredential attestation JSON from the authenticator

deviceLabelstring

Example:Front desk

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/passkey/register/verify

cURL

curl -X POST "$BASE_URL/merchant/auth/passkey/register/verify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "credential": {},
  "deviceLabel": "Front desk"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "credential": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "deviceLabel": "Front desk",
        "createdAt": 1718012345,
        "lastUsedAt": 1718012345
      }
    }
  }
}

Passkey login options

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/passkey/login/options

Returns WebAuthn publicKeyOptions (PublicKeyCredentialRequestOptions incl. challenge) for navigator.credentials.get(). Pass email for a specific user, or omit for discoverable (usernameless) login.

Body required

application/json

emailstring

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/passkey/login/options

cURL

curl -X POST "$BASE_URL/merchant/auth/passkey/login/options" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "publicKeyOptions": {}
    }
  }
}

Passkey login verify

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/passkey/login/verify

Verifies the authenticator assertion credential and signs the user in (single-step, no extra MFA). Returns an authenticated session (tokens, user, memberships).

Body required

application/json

credentialany

PublicKeyCredential assertion JSON from the authenticator

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/passkey/login/verify

cURL

curl -X POST "$BASE_URL/merchant/auth/passkey/login/verify" \
  -H "Content-Type: application/json" \
  -d '{
  "credential": {}
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "tokens": {
        "accessToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "refreshToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "expiresAt": 1718012345
      },
      "user": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "email": "string",
        "emailVerified": true,
        "displayName": "Satoshi Coffee",
        "avatarUrl": "string",
        "twoFactorEnabled": true,
        "status": "active"
      },
      "memberships": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantName": "Satoshi Coffee",
          "role": "admin",
          "status": "active",
          "isCustodial": true,
          "isDemo": true,
          "actionsBlocked": true
        }
      ],
      "activeMerchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  }
}

List passkeys

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/passkey/list

Returns the current user's registered passkeys as items, each with id, deviceLabel, createdAt, and lastUsedAt.

Authorization: merchantAuth

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/passkey/list

cURL

curl -X POST "$BASE_URL/merchant/auth/passkey/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "items": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "deviceLabel": "Front desk",
          "createdAt": 1718012345,
          "lastUsedAt": 1718012345
        }
      ]
    }
  }
}

Delete passkey

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/passkey/delete

Removes the passkey identified by credentialId from the current user. Returns { ok }.

Authorization: merchantAuth

Body required

application/json

credentialIdstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/passkey/delete

cURL

curl -X POST "$BASE_URL/merchant/auth/passkey/delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "credentialId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}

List sessions

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/sessions/list

Lists the current user's active sessions as items (with userAgent, ip, timestamps, and current flag) plus totalCount. Accepts optional pagination.

Authorization: merchantAuth

Body required

application/json

paginationobject

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/sessions/list

cURL

curl -X POST "$BASE_URL/merchant/auth/sessions/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "pagination": {
    "limit": 20,
    "skip": 0
  }
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "items": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "userAgent": "string",
          "ip": "string",
          "createdAt": 1718012345,
          "expiresAt": 1718012345,
          "current": true
        }
      ],
      "totalCount": 0
    }
  }
}

Revoke session

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/sessions/revoke

Revokes the session identified by sessionId. Returns { ok }.

Authorization: merchantAuth

Body required

application/json

sessionIdstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/sessions/revoke

cURL

curl -X POST "$BASE_URL/merchant/auth/sessions/revoke" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}

Switch merchant

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/context/switch

Switches the active merchant context to merchantId, returning fresh tokens carrying the new merchantId/role claims.

Authorization: merchantAuth

Body required

application/json

merchantIdstringrequired

Identifier of the merchant (UUID).

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/context/switch

cURL

curl -X POST "$BASE_URL/merchant/auth/context/switch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "tokens": {
        "accessToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "refreshToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
        "expiresAt": 1718012345
      }
    }
  }
}

Link xpub key (via link token)

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/xpub/link

Links a BIP32 extended public key (xpub) to the merchant account, authorized by the one-time linkToken from Start wallet link (read from the scanned QR), no bearer auth required. Receiving addresses are later derived from this key along its derivationPath. Optionally pass the masterFingerprint (for PSBT key origins) and a label. Returns the stored key record with its keyId. For the signed-in dashboard flow, use Link xpub key (authorized).

Body required

application/json

linkTokenstringrequired

One-time link token from Start wallet link, read from the scanned QR. Scopes the call to the merchant's link session (no bearer auth needed).

Example:

eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3a…

xpubstringrequired

BIP32 extended public key (xpub/ypub/zpub) to link to the merchant account.

Example:string

derivationPathstring

Base derivation path the xpub is exported at (e.g. m/84'/0'/0'); receiving addresses derive from it.

Example:string

masterFingerprintstring

Master key fingerprint (8 hex chars), used in PSBT key origins so signers can match derived inputs.

Example:string

labelstring

Optional human-readable label for the linked key.

Example:Front desk

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/xpub/link

cURL

curl -X POST "$BASE_URL/merchant/auth/xpub/link" \
  -H "Content-Type: application/json" \
  -d '{
  "linkToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
  "xpub": "string",
  "derivationPath": "string",
  "masterFingerprint": "string",
  "label": "Front desk"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "keyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "xpub": "string",
      "derivationPath": "string",
      "masterFingerprint": "string",
      "label": "Front desk",
      "linkedAt": 1718012345
    }
  }
}

Link xpub key (authorized)

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/auth/xpub/link-authorized

Authenticated counterpart of Link xpub key (via link token): links an xpub to the active merchant identified by the bearer token, so no linkToken is needed. Same derivationPath, masterFingerprint, and label options; returns the stored key record with its keyId.

Authorization: merchantAuth

Body required

application/json

xpubstringrequired

BIP32 extended public key (xpub/ypub/zpub) to link to the merchant account.

Example:string

derivationPathstring

Base derivation path the xpub is exported at (e.g. m/84'/0'/0'); receiving addresses derive from it.

Example:string

masterFingerprintstring

Master key fingerprint (8 hex chars), used in PSBT key origins so signers can match derived inputs.

Example:string

labelstring

Optional human-readable label for the linked key.

Example:Front desk

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/auth/xpub/link-authorized

cURL

curl -X POST "$BASE_URL/merchant/auth/xpub/link-authorized" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "xpub": "string",
  "derivationPath": "string",
  "masterFingerprint": "string",
  "label": "Front desk"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "keyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "xpub": "string",
      "derivationPath": "string",
      "masterFingerprint": "string",
      "label": "Front desk",
      "linkedAt": 1718012345
    }
  }
}

Register (custodial)

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/custodial/auth/register

Custodial counterpart of Register: creates the cabinet user and a custodial merchant, then creates that merchant's Uphold business user and its BTC account. Alongside email / password it takes the legal entity details Uphold requires, businessEmail, country, subdivision, legalEntityType, and the accepted termsOfService code, which is recorded together with the time and the caller's IP. Returns the new userId and status. The Uphold half is best-effort: if it fails the registration still stands, and the entities are replayed by Create Uphold entities.

Body required

application/json

emailstringrequired

Example:string

businessEmailstringrequired

Example:string

passwordstringrequired

Example:string

displayNamestring

Public display name shown to payers (optional).

Example:Satoshi Coffee

merchantNamestring

Merchant's internal name.

Example:Satoshi Coffee

countrystringrequired

Example:string

subdivisionstringrequired

Example:string

legalEntityTypeenumrequired

government-entitynon-profitpartnershipprivate-limited-companypublic-companysole-proprietor

Example:government-entity

termsOfServiceenumrequired

general-us-hqgeneral-gb-fcageneral-pt-bopgeneral-lt-fcsgeneral-bs-scb

Example:general-us-hq

userIpstring

Example:string

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/custodial/auth/register

cURL

curl -X POST "$BASE_URL/merchant/custodial/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "string",
  "businessEmail": "string",
  "password": "string",
  "displayName": "Satoshi Coffee",
  "merchantName": "Satoshi Coffee",
  "country": "string",
  "subdivision": "string",
  "legalEntityType": "government-entity",
  "termsOfService": "general-us-hq",
  "userIp": "string"
}'

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active"
    }
  }
}

Create Uphold entities

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/custodial/create-uphold-entities

Replays the creation of the signed-in custodial merchant's Uphold business user and BTC account for the case where that step did not go through during Register (custodial). Takes no parameters, everything it needs, including the recorded Terms of Service acceptance, was stored at registration. Idempotent: once the entities exist the call is a no-op and never creates a second pair.

Authorization: merchantAuth

Responses

idstringrequired

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

resultobjectrequired

POST /merchant/custodial/create-uphold-entities

cURL

curl -X POST "$BASE_URL/merchant/custodial/create-uphold-entities" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 Successful response

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {}
  }
}