From cd93ff785e833a6c2d12903b57e396162e43bb52 Mon Sep 17 00:00:00 2001 From: Antonio Buedo Date: Tue, 15 Oct 2019 14:22:30 +0200 Subject: [PATCH] - Readme and Guide added --- GUIDE.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 48 +++++++++++++++++++++- 2 files changed, 167 insertions(+), 2 deletions(-) create mode 100644 GUIDE.md diff --git a/GUIDE.md b/GUIDE.md new file mode 100644 index 0000000..c6eefde --- /dev/null +++ b/GUIDE.md @@ -0,0 +1,121 @@ +## Using the BitPay PHP light client + +This SDK provides a convenient abstraction of BitPay's [cryptographically-secure API](https://bitpay.com/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 SDK 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 SDK. It's free to [sign-up for a BitPay merchant account](https://bitpay.com/start). + +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 https://bitpay.com/docs/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: +```bash +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 + +```bash +curl -sS https://getcomposer.org/installer | php +``` + +### Install via composer by hand + +Add to your composer.json file by hand. + +```bash +{ + ... + "require": { + ... + "bitpay/sdk-light": "~1.0" + } + ... +} +``` + +Once you have added this, just run: + +```bash +php composer.phar update bitpay/sdk-light +``` + +### Install using composer + +```bash +php composer.phar require bitpay/sdk:~3.0 +``` + +### Initializing your BitPay light client + +Once you have the environment file (JSON or YML previously generated) you can initialize the client on two different ways: + +```php +// Provide the full path to the env file which you have previously stored securely. + +$bitpay = BitPaySDKLight\Client::create()->withFile([FULL_PATH_TO_THE_CONFIG_FILE]); +``` + +```php +$bitpay = new BitPaySDKLight\Client(BitPaySDKLight\Env.Test,"CFJCZH3VitcEER9Uybx8LMvkPsSWzpSWvN4vhNEJp47b"); +``` +## +### Create an invoice + +```php +$invoice = $bitpay->createInvoice(new Invoice(50.0, "USD")); + +$invoiceUrl = $invoice->getURL(); + +$status = $invoice->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 + +```php +$invoice = $bitpay->getInvoice($invoice->getId()); +``` + +### Get exchange Rates + +You can retrieve BitPay's [BBB exchange rates](https://bitpay.com/exchange-rates). + +```php +$rates = $bitpay->getRates(); + +$rate = $rates->getRate(Currency::USD); //Always use the included Currency model to avoid typos + +$rates->update(); +``` + +See also the test package for more examples of API calls. diff --git a/README.md b/README.md index db3923c..ef02012 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,46 @@ -# php-bitpay-light-client -Light version of the Java library for the new cryptographically secure BitPay API + + +# BitPay PHP Light Client +[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/bitpay/php-bitpay-light-client/master/LICENSE.md) +[![Packagist](https://img.shields.io/packagist/v/bitpay/sdk-light.svg?style=flat-square)](https://packagist.org/packages/bitpay/sdk-light) +[![Total Downloads](https://poser.pugx.org/bitpay/sdk-light/downloads.svg)](https://packagist.org/packages/bitpay/sdk-light) +[![Latest Unstable Version](https://poser.pugx.org/bitpay/sdk-light/v/unstable.svg)](https://packagist.org/packages/bitpay/sdk-light) + +Light implementation of the client for the BitPay's [Cryptographically Secure RESTful API](https://bitpay.com/api). + +## Getting Started + +To get up and running with our PHP library quickly, follow [The GUIDE](https://github.com/bitpay/php-bitpay-light-client/blob/master/GUIDE.md) + +## Support + +* https://github.com/bitpay/php-bitpay-light-client/issues +* https://support.bitpay.com + +## Contribute + +To contribute to this project, please fork and submit a pull request. + +## License + +MIT License + +Copyright (c) 2019 BitPay + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE.