EcommerceBBVA / BBVA-PHP

EcommerceBBVA: PHP Library
Apache License 2.0
4 stars 8 forks source link

Bbva PHP

PHP client for Bbva API services (version 1.0.0)

This is a client implementing the payment services for Bbva at bbva.mx

What's new?

Compatibility

PHP 5.2 or later

Requirements

PHP 5.2 or later cURL extension for PHP JSON extension for PHP Multibyte String extension for PHP

Installation

Composer

The preferred method is via composer. Follow the installation instructions if you do not already have composer installed.

Once composer is installed, execute the following command in your project root to install this library:

composer require bbva/sdk dev-master

Finally, be sure to include the autoloader:

require_once '/path/to/your-project/vendor/autoload.php';

Manual installation

To install, just:

require(dirname(__FILE__) . '/Bbva/Bbva.php');

NOTE: In the example above, the library is located in the directory named Bbva, located inside the same directory that the PHP file which is including the cliente. Make sure to adjust the paths inside your project, otherwise the library will not work.

Implementation

Configuration

Before use the library will be necessary to set up your Merchant ID and Private key. There are three options:

Bbva::setId('moiep6umtcnanql3jrxp');
Bbva::setApiKey('sk_3433941e467c4875b178ce26348b0fac');
Bbva::setPublicIp('127.0.0.1'); //Tu ip publica
$bbva = Bbva::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c4875b178ce26348b0fac', '127.0.0.1');

NOTE: please, refer to PHP documentation for further information about this method.

Sandbox/Production Mode

By convenience and security, the sandbox mode is activated by default in the client library. This allows you to test your own code when implementing Bbva, before charging any credit card in production environment. Once you have finished your integration, use the method Bbva::setProductionMode(FLAG) which will allow you to active/inactivate the sandbox mode.

Bbva::setProductionMode(true);

Also you can use environment variables for this purpose:

SetEnv BBVA_PRODUCTION_MODE true

If its necessary, you can use the method Bbva::getProductionMode() to determine anytime, which is the sandbox mode status:

// will return TRUE/FALSE, depending on if sandbox mode is activated or not.
Bbva::getProductionMode(); 

PHP client library intro

Once configured the library, you can use it to interact with Bbva API services. The first step is get an instance with the generator:

$bbva = Bbva::getInstance('mptdggroasfcmqs8plpy', 'sk_326c6d0443f6457aae29ffbd48f7d1be', '127.0.0.1');

In this example $bbva will be an instance of a merchant (root), wich will be used to call any derived child resource. According to the current version of the Bbva API, these resources are:

You can access all of these resources as public variables of the root instance, so, if you want to add a new customer you will be able to do it as follows:

$bbva->tokens->add(PARAMETERS);

Every call to any resource will return an instance of that resource. In the example above, calling the method add() in the resource tokens will return an instance of Token, calling the method add() in the resource tokens will return an instance of Card, and so on. The only exception occurs when you retrieve a list of resources using the method getList(), in which case an array of instances will be returned:

// a SINGLE instance of Customer will be returned
$charge = $bbva->charges->add(PARAMETERS);

// an ARRAY of instances of Customers will be returned
chargersList = $bbva->charges->getList(PARAMETERS);

On the other hand, the resources derived from Charge, according to Bbva API documentation, are:

Parameters

Those methods which receive more than one parameter (for example, when trying to add a new customer or a new customer's card), must be passed as associatives arrays:

array('PARAMETER_INTEGER' => VALUE,
      'PARAMETER_STRING'  => 'VALUE');
      'PARAMETER_DERIVED' => array('PARAMETER_INTEGER' => VALUE), 
                                   'PARAMETER_STRING'  => 'VALUE'));

NOTE: Please refer to Bbva API docuemntation to determine wich parameters are accepted, wich required and which of those are optional, in every case.

Error handling

The Bbva API generates several types of errors depending on the situation, to handle this, the PHP client has implemented five type of exceptions:

All these error exceptions make available all the information returned by the Bbva API, with the following methods:

The following is an more complete example of error catching:

try {
    Bbva::setProductionMode(true);

    // the following line will generate an error because the
    // private key is empty. The exception generated will be
    // a BbvaApiAuthError
    $bbva = Bbva::getInstance('mptdggroasfcmqs8plpy', '');

    $customer = $bbva->customers->get('a9ualumwnrcxkl42l6mh');
    $customer->name = 'Juan';
    $customer->last_name = 'Godinez';
    $customer->save();

} catch (BbvaApiTransactionError $e) {
    error_log('ERROR on the transaction: ' . $e->getMessage() . 
          ' [error code: ' . $e->getErrorCode() . 
          ', error category: ' . $e->getCategory() . 
          ', HTTP code: '. $e->getHttpCode() . 
          ', request ID: ' . $e->getRequestId() . ']', 0);

} catch (BbvaApiRequestError $e) {
    error_log('ERROR on the request: ' . $e->getMessage(), 0);

} catch (BbvaApiConnectionError $e) {
    error_log('ERROR while connecting to the API: ' . $e->getMessage(), 0);

} catch (BbvaApiAuthError $e) {
    error_log('ERROR on the authentication: ' . $e->getMessage(), 0);

} catch (BbvaApiError $e) {
    error_log('ERROR on the API: ' . $e->getMessage(), 0);

} catch (Exception $e) {
    error_log('Error on the script: ' . $e->getMessage(), 0);
}

Examples

Customers

Add a new customer to a merchant:

$bbva = Bbva::getInstance('mptdggroasfcmqs8plpy', 'sk_326c6d0443f6457aae29ffbd48f7d1be', '127.0.0.1');

$customerData = array(
    'name' => 'Teofilo',
    'last_name' => 'Velazco',
    'email' => 'teofilo@payments.com',
    'phone_number' => '4421112233',
    'address' => array(
            'line1' => 'Privada Rio No. 12',
            'line2' => 'Co. El Tintero',
            'line3' => '',
            'postal_code' => '76920',
            'state' => 'Querétaro',
            'city' => 'Querétaro.',
            'country_code' => 'MX'));

Tokens

On a merchant:

Add a token:

$bbva = Bbva::getInstance('mptdggroasfcmqs8plpy', 'sk_326c6d0443f6457aae29ffbd48f7d1be');

$tokenData = array(
    'holder_name' => 'Luis Pérez',
    'card_number' => '4111111111111111',
    'cvv2' => '123',
    'expiration_month' => '12',
    'expiration_year' => '15',
    'address' => array(
        'line1' => 'Av. 5 de Febrero No. 1',
        'line2' => 'Col. Felipe Carrillo Puerto',
        'line3' => 'Zona industrial Carrillo Puerto',
        'postal_code' => '76920',
        'state' => 'Querétaro',
        'city' => 'Querétaro',
        'country_code' => 'MX'));

$token = $bbva->tokens->add($tokenData);

Get a token:

$bbva = Bbva::getInstance('mptdggroasfcmqs8plpy', 'sk_326c6d0443f6457aae29ffbd48f7d1be', '127.0.0.1');

$token = $bbva->tokens->get('k9pn8qtsvr7k7gxoq1r5');

Charges

On a Merchant:

Make a charge on a merchant:

$bbva = Bbva::getInstance('mptdggroasfcmqs8plpy', 'sk_326c6d0443f6457aae29ffbd48f7d1be', '127.0.0.1');

$chargeData = array(
    'affiliation_bbva' => '781500',
    'amount' => 100,
    'currency' => 'MXN',
    'order_id' => 'ORDEN-00071',
    'customer' => array(
        'name' => 'Teofilo',
        'last_name' => 'Velazco',
        'email' => 'teofilo@payments.com',
        'phone_number' => '4421112233',
        'address' => array(
            'line1' => 'Privada Rio No. 12',
            'line2' => 'Co. El Tintero',
            'line3' => '',
            'postal_code' => '76920',
            'state' => 'Querétaro',
            'city' => 'Querétaro.',
            'country_code' => 'MX')),
    'description' => 'Cargo inicial a mi merchant'
    'redirect_url' => 'https://sand-portal.ecommercebbva.com/'
    );

$charge = $bbva->charges->create($chargeData);

Get a charge:

$bbva = Bbva::getInstance('mptdggroasfcmqs8plpy', 'sk_326c6d0443f6457aae29ffbd48f7d1be', '127.0.0.1');

$charge = $bbva->charges->get('tvyfwyfooqsmfnaprsuk');

Make a capture:

$bbva = Bbva::getInstance('mptdggroasfcmqs8plpy', 'sk_326c6d0443f6457aae29ffbd48f7d1be', '127.0.0.1');

$captureData = array('amount' => 150.00 );

$charge = $bbva->charges->get('tvyfwyfooqsmfnaprsuk');
$charge->capture($captureData);

Make a refund:

$bbva = Bbva::getInstance('mptdggroasfcmqs8plpy', 'sk_326c6d0443f6457aae29ffbd48f7d1be', '127.0.0.1');

$refundData = array('description' => 'Devolución' );

$charge = $bbva->charges->get('tvyfwyfooqsmfnaprsuk');
$charge->refund($refundData);