129 lines
4.8 KiB
Markdown
129 lines
4.8 KiB
Markdown
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).
|
|
|
|
|