Overview

This library provides a convenient abstraction of BitPay's cryptographically-secure API and allows payment gateway developers to focus on payment flow/e-commerce integration rather than on the specific details of client-server interaction using the API. This library optionally provides the flexibility for developers to have control over important details, including the handling of private tokens needed for client-server communication.

Dependencies

You must have a BitPay merchant account to use this library. It's free to sign-up for a BitPay merchant account.

If you need a test account, please visit https://test.bitpay.com/dashboard/signup and register for a BitPay merchant test account. Please fill in all questions, so you get a fully working test account. If you are looking for a testnet bitcoin wallet to test with, please visit https://bitpay.com/wallet and create a new wallet. If you need testnet bitcoin please visit a testnet faucet, e.g. https://testnet.coinfaucet.eu/en/ or http://tpfaucet.appspot.com/

For more information about testing, please see Testing

Usage

This library was built and tested using the PhpStorm IDE; the source code tree is directly compatible with Other PHP IDEs. Library dependencies can be downloaded by executing the following command at the root of the library:

php composer.phar install

Getting your client token

First of all, you need to generate a new POS token on your BitPay's account which will be required to securely connect to the BitPay's API.

For testing purposes use:
https://test.bitpay.com/dashboard/merchant/api-tokens

For production use:
https://bitpay.com/dashboard/merchant/api-tokens

Click on Add New Token, give a name on the Token Label input, leave the Require Authentication checkbox unchecked and click on Add Token. The new token will appear and ready to use.

Installation

Composer

Install Composer

curl -sS https://getcomposer.org/installer | php

Install via composer by hand

Add to your composer.json file by hand.

{
    ...
    "require": {
        ...
        "bitpay/sdk-light": "^2.0"
    }
    ...
}

Once you have added this, just run:

php composer.phar update bitpay/sdk-light

Install using composer

php composer.phar require bitpay/sdk-light:^2.0

Initializing your BitPay light client

Once you have your previously generated Token, you can initialize the client following this example:

$bitpay = new BitPaySDKLight\\Client("CFJCZH3VitcEER9Uybx8LMvkPsSWzpSWvN4vhNEJp47b", BitPaySDKLight\\Env::Test);

Create an invoice

Invoices are time-sensitive payment requests addressed to specific buyers. An invoice has a fixed price, typically denominated in fiat currency. It also has an equivalent price in the supported cryptocurrencies, calculated by BitPay, at a locked exchange rate with an expiration time of 15 minutes.

POST /invoices

Facade POS

HTTP Request

Headers

Body

Example code for creating an invoice

$invoice = new Invoice(50.0, "USD");  
$invoice->setToken($bitpay->\_token);  
$invoice->setOrderId("65f5090680f6");  
$invoice->setFullNotifications(true);  
$invoice->setExtendedNotifications(true);  
$invoice->setNotificationURL("<https://hookbin.com/lJnJg9WW7MtG9GZlPVdj>  
  
");  
$invoice->setRedirectURL("<https://hookbin.com/lJnJg9WW7MtG9GZlPVdj>  
  
");  
$invoice->setItemDesc("Ab tempora sed ut.");  
$invoice->setNotificationEmail("");

$buyer = new Buyer();  
$buyer->setName("Bily Matthews");  
$buyer->setEmail("");  
$buyer->setAddress1("168 General Grove");  
$buyer->setAddress2("");  
$buyer->setCountry("AD");  
$buyer->setLocality("Port Horizon");  
$buyer->setNotify(true);  
$buyer->setPhone("+990123456789");  
$buyer->setPostalCode("KY7 1TH");  
$buyer->setRegion("New Port");

$invoice->setBuyer($buyer);

$basicInvoice = $bitpay->createInvoice($invoice);

HTTP Response

{  
    "facade": "pos/invoice",  
    "data": {  
        "url": "<https://bitpay.com/invoice?id=KSnNNfoMDsbRzd1U9ypmVH>  
  
",  
        "status": "new",  
        "price": 10,  
        "currency": "USD",  
        "orderId": "20210511_abcde",  
        "invoiceTime": 1620734545366,  
        "expirationTime": 1620735445366,  
        "currentTime": 1620734545415,  
        "id": "KSnNNfoMDsbRzd1U9ypmVH",  
        "lowFeeDetected": false,  
        "amountPaid": 0,  
        "displayAmountPaid": "0",  
        "exceptionStatus": false,  
        "redirectURL": "<https://merchantwebsite.com/shop/return>  
  
",  
        "refundAddressRequestPending": false,  
        "buyerProvidedInfo": {},  
        "paymentSubtotals": {  
            "BTC": 18200,  
            "BCH": 744500,  
            "ETH": 2535000000000000,  
            "GUSD": 1000,  
            "PAX": 10000000000000000000,  
            "BUSD": 10000000000000000000,  
            "USDC": 10000000,  
            "XRP": 7084249,  
            "DOGE": 2068707100,  
            "DAI": 9990000000000000000,  
            "WBTC": 18100  
        },  
        "paymentTotals": {  
            "BTC": 29800,  
            "BCH": 744500,  
            "ETH": 2535000000000000,  
            "GUSD": 1000,  
            "PAX": 10000000000000000000,  
            "BUSD": 10000000000000000000,  
            "USDC": 10000000,  
            "XRP": 7084249,  
            "DOGE": 2068707100,  
            "DAI": 9990000000000000000,  
            "WBTC": 18100  
        },  
        "paymentDisplayTotals": {  
            "BTC": "0.000298",  
            "BCH": "0.007445",  
            "ETH": "0.002535",  
            "GUSD": "10.00",  
            "PAX": "10.00",  
            "BUSD": "10.00",  
            "USDC": "10.00",  
            "XRP": "7.084249",  
            "DOGE": "20.687071",  
            "DAI": "9.99",  
            "WBTC": "0.000181"  
        },  
        "paymentDisplaySubTotals": {  
            "BTC": "0.000182",  
            "BCH": "0.007445",  
            "ETH": "0.002535",  
            "GUSD": "10.00",  
            "PAX": "10.00",  
            "BUSD": "10.00",  
            "USDC": "10.00",  
            "XRP": "7.084249",  
            "DOGE": "20.687071",  
            "DAI": "9.99",  
            "WBTC": "0.000181"  
        },  
        "exchangeRates": {  
            "BTC": {  
            "USD": 55072.459995,  
            "EUR": 45287.42496000001,  
            "BCH": 40.884360403999914,  
            "ETH": 13.953840617367156,  
            "GUSD": 55072.459995,  
            "PAX": 55072.459995,  
            "BUSD": 55072.459995,  
            "USDC": 55072.459995,  
            "XRP": 38907.54307403195,  
            "DOGE": 113694.39064944115,  
            "DAI": 55018.486859390934,  
            "WBTC": 0.9983514430763876  
            },  
            "BCH": {  
            "USD": 1343.1537000000003,  
            "EUR": 1104.481875,  
            "BTC": 0.02437664632426631,  
            "ETH": 0.34031805835672807,  
            "GUSD": 1343.1537000000003,  
            "PAX": 1343.1537000000003,  
            "BUSD": 1343.1537000000003,  
            "USDC": 1343.1537000000003,  
            "XRP": 948.9100440136494,  
            "DOGE": 2772.8748903518513,  
            "DAI": 1341.8373575522414,  
            "WBTC": 0.024348638771359274  
            },  
            "ETH": {  
            "USD": 3944.6466899999996,  
            "EUR": 3242.8077850000004,  
            "BTC": 0.07159065804331831,  
            "BCH": 2.9284029977060646,  
            "GUSD": 3944.6466899999996,  
            "PAX": 3944.6466899999996,  
            "BUSD": 3944.6466899999996,  
            "USDC": 3944.6466899999996,  
            "XRP": 2786.8105223000134,  
            "DOGE": 8143.529484384802,  
            "DAI": 3940.7807840508463,  
            "WBTC": 0.07150840394174397  
            },  
            ...  
        },  
        "supportedTransactionCurrencies": {  
            "BTC": {  
            "enabled": true  
            },  
            "BCH": {  
            "enabled": true  
            },  
            "ETH": {  
            "enabled": true  
            },  
            ...  
        },  
        "minerFees": {  
            "BTC": {  
            "satoshisPerByte": 79.152,  
            "totalFee": 11600  
            },  
            "BCH": {  
            "satoshisPerByte": 0,  
            "totalFee": 0  
            },  
            "ETH": {  
            "satoshisPerByte": 0,  
            "totalFee": 0  
            },  
            ...  
        },  
        "jsonPayProRequired": false,  
        "paymentCodes": {  
            "BTC": {  
            "BIP72b": "bitcoin:?r=<https://bitpay.com/i/KSnNNfoMDsbRzd1U9ypmVH>  
  
",  
            "BIP73": "<https://bitpay.com/i/KSnNNfoMDsbRzd1U9ypmVH>"  
            },  
            "BCH": {  
            "BIP72b": "bitcoincash:?r=<https://bitpay.com/i/KSnNNfoMDsbRzd1U9ypmVH>  
  
",  
            "BIP73": "<https://bitpay.com/i/KSnNNfoMDsbRzd1U9ypmVH>"  
            },  
            "ETH": {  
            "EIP681": "ethereum:?r=<https://bitpay.com/i/KSnNNfoMDsbRzd1U9ypmVH>"  
            },  
            ...  
        },  
        "token": "8nPJSGgi7omxcbGGZ4KsSgqdi6juypBe9pVpSURDeAwx4VDQx1XfWPy5qqknDKT9KQ"  
    }  
}

To get the generated invoice url and status

$invoiceUrl = $basicInvoice->getURL();

$status = $basicInvoice->getStatus();

🚧

WARNING: If you get the following error when initiating the client for first time: "500 Internal Server Error` response: {"error":"Account not setup completely yet."}" Please, go back to your BitPay account and complete the required steps. More info here:https://support.bitpay.com/hc/en-us/articles/203010446-How-do-I-apply-for-a-merchant-account-

Retrieve an invoice

GET /invoices/:invoiceid

Facade POS

HTTP Request

URL Parameters

Headers

To get the generated invoice details, pass the Invoice Id with URL parameter

$invoice = $bitpay->getInvoice($basicInvoice->getId());

Create bill

Bills are payment requests addressed to specific buyers. Bill line items have fixed prices, typically denominated in fiat currency.

POST /bills

Facade POS

HTTP Request

Headers

Body

$items = \[];

$item = new Item();  
$item->setPrice(6.0);  
$item->setQuantity(1);  
$item->setDescription("Test Item 1");  
array_push($items, $item);

$item = new Item();  
$item->setPrice(4.0);  
$item->setQuantity(1);  
$item->setDescription("Test Item 2");  
array_push($items, $item);

$bill = new Bill("bill1234-ABCD", Currency::USD, "", $items);  
$bill->setEmail("[email protected]");

$basicBill = $this->\_client->createBill($bill);

HTTP Response

{
    "facade": "pos/bill",
    "data": {
        "status": "draft",
        "url": "https://bitpay.com/bill?id=X6KJbe9RxAGWNReCwd1xRw&resource=bills",
        "number": "bill1234-ABCD",
        "createdDate": "2021-05-21T09:48:02.373Z",
        "dueDate": "2021-05-31T00:00:00.000Z",
        "currency": "USD",
        "email": "[email protected]",
        "cc": [
        "[email protected]"
        ],
        "passProcessingFee": true,
        "id": "X6KJbe9RxAGWNReCwd1xRw",
        "items": [
        {
            "id": "EL4vx41Nxc5RYhbqDthjE",
            "description": "Test Item 1",
            "price": 6,
            "quantity": 1
        },
        {
            "id": "6spPADZ2h6MfADvnhfsuBt",
            "description": "Test Item 2",
            "price": 4,
            "quantity": 1
        }
        ],
        "token": "qVVgRARN6fKtNZ7Tcq6qpoPBBE3NxdrmdMD883RyMK4Pf8EHENKVxCXhRwyynWveo"
    }
}

Get bill
GET /bills/:billid

Facade POS

HTTP Request

URL Parameters

Headers

HTTP Response

{  
    "facade": "pos/bill",  
    "data": {  
        "status": "draft",  
        "url": "<https://bitpay.com/bill?id=X6KJbe9RxAGWNReCwd1xRw&resource=bills>  ",  
        "number": "bill1234-ABCD",  
        "createdDate": "2021-05-21T09:48:02.373Z",  
        "dueDate": "2021-05-31T00:00:00.000Z",  
        "currency": "USD",  
        "email": "[email protected]",  
        "cc": [  
        "[email protected]"  
        ],  
        "passProcessingFee": true,  
        "id": "X6KJbe9RxAGWNReCwd1xRw",  
        "items": [  
        {  
            "id": "EL4vx41Nxc5RYhbqDthjE",  
            "description": "Test Item 1",  
            "price": 6,  
            "quantity": 1  
        },  
        {  
            "id": "6spPADZ2h6MfADvnhfsuBt",  
            "description": "Test Item 2",  
            "price": 4,  
            "quantity": 1  
        }  
        ],  
        "token": "qVVgRARN6fKtNZ7Tcq6qpoPBBE3NxdrmdMD883RyMK4Pf8EHENKVxCXhRwyynWveo"  
    }  
}

Deliver bill

GET /bills/:billid/deliveries

Facade POS

HTTP Request

URL Parameters

Headers

Body

$deliveredBill = $bitpay->deliverBill($bill->getId());

HTTP Response

Body

{
    "data": "Success"
}

Get Exchange Rates

Rates are exchange rates, representing the number of fiat currency units equivalent to one BTC. You can retrieve BitPay's https://bitpay.com/exchange-rates.

GET /rates/:basecurrency

Facade Public

HTTP Request

URL Parameters

Headers

$rates = $bitpay->getRates();

$rate = $rates->getRate(Currency::USD); //Always use the included Currency model to avoid typos

$rates->update();

HTTP Response

Body

{
    "data":[
        {
        "code":"BTC",
        "name":"Bitcoin",
        "rate":1
        },
        {
        "code":"BCH",
        "name":"Bitcoin Cash",
        "rate":50.77
        },
        {
        "code":"USD",
        "name":"US Dollar",
        "rate":41248.11
        },
        {
        "code":"EUR",
        "name":"Eurozone Euro",
        "rate":33823.04
        },
        {
        "code":"GBP",
        "name":"Pound Sterling",
        "rate":29011.49
        },
        {
        "code":"JPY",
        "name":"Japanese Yen",
        "rate":4482741
        },
        {
        "code":"CAD",
        "name":"Canadian Dollar",
        "rate":49670.85
        },
        {
        "code":"AUD",
        "name":"Australian Dollar",
        "rate":53031.99
        },
        {
        "code":"CNY",
        "name":"Chinese Yuan",
        "rate":265266.57
        },
        ...
    ]
}

You can retrieve all the rates for a given cryptocurrency

URL Parameters

Headers

$rates = $bitpay->getCurrencyRates(Currency::ETH);

$rate = $rates->getRate(Currency::USD);

You can retrieve the rate for a cryptocurrency / fiat pair

$rate = $bitpay->getCurrencyPairRate(Currency::BTC, Currency::USD);

HTTP Response

Body

{
    "data":
        {
            "code":"USD",
            "name":"US Dollar",
            "rate":41154.05
        }
}

See also the test package for more examples of API calls.

Get Currencies

GET /currencies

Facade PUBLIC

HTTP Request

Headers

You can retrieve all the currencies supported by BitPay.

$currencies = $bitpay->getCurrencies();

HTTP Response

Body

{
    "data": [
        {
        "code": "BTC",
        "symbol": "฿",
        "precision": 6,
        "name": "Bitcoin",
        "plural": "Bitcoin",
        "alts": "btc",
        "minimum": 0.000006,
        "sanctioned": false,
        "decimals": 8,
        "chain": "BTC"
        },
        ...
        ...
        {
        "code": "XRP",
        "symbol": "Ʀ",
        "precision": 6,
        "name": "Ripple",
        "plural": "Ripple",
        "alts": "xrp",
        "minimum": 0.000006,
        "sanctioned": false,
        "decimals": 6,
        "chain": "XRP"
        },
        ...
        ...
        {
        "code": "EUR",
        "symbol": "€",
        "precision": 2,
        "name": "Eurozone Euro",
        "plural": "Eurozone Euros",
        "alts": "eur",
        "minimum": 0.01,
        "sanctioned": false,
        "decimals": 2
        },
        ...
        ...
        {
        "code": "USD",
        "symbol": "$",
        "precision": 2,
        "name": "US Dollar",
        "plural": "US Dollars",
        "alts": "usd bucks",
        "minimum": 0.01,
        "sanctioned": false,
        "decimals": 2
        },
        {
        "code": "USDC",
        "symbol": "$",
        "precision": 2,
        "name": "Circle USD Coin",
        "plural": "Circle USD Coin",
        "alts": "",
        "minimum": 0.01,
        "sanctioned": false,
        "decimals": 6,
        "chain": "ETH"
        },
        ...
        ...
    ]
}