Getting Started - Sandbox

This guide will walk you step by step to integrate with our API and assumes no prior Bitclear API knowledge.

All references on this page point to the Sandbox version of the API which allow clients to test all features without using any real funds.

It is suggested to first integrate with the Sandbox environment and test all scenarios there, without risking losing any funds.

Differences between Sandbox and Production

This table summarized the differences between the environments

Feature	Sandbox	Production
API URL	api-sandbox.bitclear.li	api.bitclear.li
Panel URL	panel-sandbox.bitclear.li	panel.bitclear.li
Bitcoin network	Testnet (coins have no value)	Mainnet (coins have real value)

There are no differences in terms of offered functionalities.

Both environments are disconnected from each other. This means that API clients need to use different set of credentials and API keys (for example: API key from Production will not work on Sandbox)

Obtaining API key

Contact us first

Accounts are created by our support staff, prior to obtaining API access please contact us via Contact Page.

Our technical team is always available on our private Slack team to provide support when needed.

Create API key in client panel

API keys are needed to connect to Bitclear API.

First time in client panel

Client panel: https://panel-sandbox.bitclear.li

Before first login you have to reset your password, using Don't remember your password? link on login page. Provide e-mail address that was used for your account. Be sure to have access to provided e-mail, as you will receive link to reset your password.
Check received e-mail, click provided link and enter new password
Now you have set your password, so follow to next section

Create API keys

Login to client panel using e-mail provided to our support and password that was set during first login.
Go to My API keys section in menu on the left side of the web page.
Click New API key button.
Provide API key Name that describes the purpose of the API key for you. You should use only letters, numbers and underscore.
Click Create API key
You will see a popup that shows your newly created API key. It's very important to store it in some safe place as Bitclear team will not be able to restore this API key secret for you. It's never stored as plain text in our system.
Click I saved API Key
The pair containing the name and secret of API key will be needed to use our API.

Create payments via Bitclear API

Basic information about the requests

To authorize in Bitclear API you have to use basic auth over https. Set the username as the API Key ID and password as API Key Secret which was generated when the key was created.
The url to sandbox environment is: https://api-sandbox.bitclear.li/v3/.
All available endpoints are described in OpenAPI Specification

Example

curl --request 'POST' \
  --user "$API_KEY_ID:$API_KEY_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{"priceAmount":"1.23","priceCurrency":"USD","externalPaymentId":"123456789abcdef","notificationUrl":"http://localhost:8888/helloPayment","transferCurrency":"BTC","walletMessage":"Barber for Gandalf"}' \
  'https://api-sandbox.bitclear.li/v3/payments'

Request:

POST /v3/payments HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Authorization: Basic b25lS2V5X3RvUnVsZV90aGVtQWxsOkxyY3lYb2VGRjM1T2tjMlhXZHVKYzBhMzBPOGl4Wlo5
Connection: keep-alive
Content-Type: application/json
Host: api-sandbox.bitclear.li

{
    "priceAmount": "1.23",
    "priceCurrency": "USD",
    "externalPaymentId": "123456789abcdef",
    "walletMessage": "Barber for Gandalf",
    "notificationUrl": "http://localhost:8888/helloPayment",
    "transferCurrency": "BTC"
}

Response:

HTTP/1.1 200 OK
Content-Length: 655
Content-Type: application/json
Date: Wed, 08 Apr 2020 13:10:45 GMT
Server: Bitclear API

{
    "priceAmount": 1.23,
    "priceCurrency": "USD",
    "address": "2N3kVr2CHHt2pSdCidq4dwZBFeBnMQhvaka",
    "expirationTime": "2020-04-08T13:12:45.239167Z",
    "guaranteedExchangeRate": 6493.57142857,
    "notificationUrl": "http://localhost:8888/helloPayment",
    "paidPriceAmount": 0.0,
    "paidTransferAmount": 0.0,
    "acceptedPaidPriceAmount": 0.0,
    "acceptedPaidTransferAmount": 0.0,
    "pendingPaidPriceAmount": 0.0,
    "pendingPaidTransferAmount": 0.0,
    "transferAmount": 0.00018942,
    "transferCurrency": "BTC",
    "paymentId": "8618ed13372b483b84d56c0cc5509a401c182d9e4dc04824a6ffddd8473753a3",
    "paymentPageUrl": "https://payments-sandbox.bitclear.li/payments/8618ed13372b483b84d56c0cc5509a401c182d9e4dc04824a6ffddd8473753a3",
    "paymentUri": "bitcoin:2N3kVr2CHHt2pSdCidq4dwZBFeBnMQhvaka?amount=0.00018942&label=&message=Barber%20for%20Gandalf",
    "status": "NEW",
    "transactions": []
}