First Commit

beanstream-php-master.orig/README.md

@@ -0,0 +1,128 @@
+Beanstream PHP API
+==================
+
+Composer ready PHP wrapper for [Beanstream API](http://developer.beanstream.com/documentation/).
+
+## Help Contribute
+Send us pull requests and help improve the code, and we will send you a t-shirt.
+
+## Installation
+
+The recommended way to install the library is using [Composer](https://getcomposer.org).
+
+1) Add this json to your composer.json file:
+```json
+{
+    "require": {
+        "beanstream/beanstream": "dev-master"
+    }
+}
+```
+
+2) Next, run this from the command line:
+```
+composer install
+```
+3) Finally, add this line to your php file that will be using the SDK:
+```
+require 'vendor/autoload.php';
+```
+
+## Handling Exceptions
+
+If the server returns an unexpected response or error, PHP API throws *\Beanstream\Exception*.
+
+Positive error codes correspond to Beanstream API errors, see
+[Take Payment Errors](http://developer.beanstream.com/documentation/take-payments/errors/),
+[Analyze Payment Errors](http://developer.beanstream.com/documentation/analyze-payments/errors/),
+[Tokenize Payments Errors](http://developer.beanstream.com/documentation/tokenize-payments/errors/).
+
+Negative codes correspond to [cURL errors](http://curl.haxx.se/libcurl/c/libcurl-errors.html)
+(original cURL error codes are positive, in *\Beanstream\Exception* those are just reversed).
+Exception with zero error code are PHP API specific, e.g. *The curl extension is required* or
+*Unexpected response format*.
+
+Generally, any unsuccessful request, e.g. insufficient data or declined transaction, results in *\Beanstream\Exception*,
+thus *try..catch* is recommended for intercepting and handling them, see example below.
+
+## Your First Integration
+
+The sample below is an equivalent of original [example](http://developer.beanstream.com/documentation/your-first-integration/)
+from Beanstream.
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+
+$merchant_id = ''; //INSERT MERCHANT ID (must be a 9 digit string)
+$api_key = ''; //INSERT API ACCESS PASSCODE
+$api_version = 'v1'; //default
+$platform = 'api'; //default
+
+//Create Beanstream Gateway
+$beanstream = new \Beanstream\Gateway($merchant_id, $api_key, $platform, $api_version);
+
+//Example Card Payment Data
+$payment_data = array(
+        'order_number' => 'a1b2c3',
+        'amount' => 1.00,
+        'payment_method' => 'card',
+        'card' => array(
+            'name' => 'Mr. Card Testerson',
+            'number' => '4030000010001234',
+            'expiry_month' => '07',
+            'expiry_year' => '22',
+            'cvd' => '123'
+        )
+);
+$complete = TRUE; //set to FALSE for PA
+
+//Try to submit a Card Payment
+try {
+
+	$result = $beanstream->payments()->makeCardPayment($payment_data, $complete);
+    
+    /*
+     * Handle successful transaction, payment method returns
+     * transaction details as result, so $result contains that data
+     * in the form of associative array.
+     */
+} catch (\Beanstream\Exception $e) {
+    /*
+     * Handle transaction error, $e->code can be checked for a
+     * specific error, e.g. 211 corresponds to transaction being
+     * DECLINED, 314 - to missing or invalid payment information
+     * etc.
+     */
+}
+```
+
+See examples.php for more examples.
+
+## Tips
+
+### Authentication
+
+Beanstream defines separate API access passcodes for payment, profile and reporting API requests. It is possible 
+to use the same value for all of them, and create a single instance of \Beanstream\Gateway. You can also 
+initialize separate \Beanstream\Gateway instances for each type of request.  API access passcodes are 
+configured via the Beanstream dashboard (See *administration -> account settings -> order settings* 
+for payment and search passcodes, *configuration -> payment profile configuration* for profile passcode).
+
+
+### Billing Address Province
+
+Beanstream requires the *province* field submitted along with *billing* data to be a two-letter code. It only requires it when
+the specified *country* is *US* or *CA*, for other country codes set it to *--* (two dashes) even if the corresponding country 
+does have states or provinces.
+
+
+### Backwards Compatibility
+The default `$platform` value assigned is `'api'`, which sends your requests to the endpoint `'api.na.bambora.com'`. The ensure backwards compatibility, you may assign `$platform = 'www'` which will send your requests to the legacy endpoint `'www.beanstream.com/api'`.
+
+
+### Ensuring TLS 1.2-Only Compatibility
+If you would like to test compatibility with the LIVE TLS 1.2-only environment, assign `$platform = 'tls12-api'`, instead of `'api'`; This will point your requests to the endpoint `'tls12-api.na.bambora.com'`. Please be advised that this endpoint is provided for a limited time, and is intended for integration compatibility testing only, and is not intended for any type of load tests. More details can be found on the [Bambora North America Knowledge Base](https://help.na.bambora.com/hc/en-us/articles/115015460087-TLS-Upgrade-TLS-1-2).
+
+