README

Bbva PHP

Bbva API服务的PHP客户端（版本1.0.0）

这是一个在bbva.mx实现Bbva支付服务的客户端

新增功能？

兼容性

PHP 5.2或更高版本

需求

PHP 5.2或更高版本，cURL扩展，PHP JSON扩展，PHP多字节字符串扩展

安装

Composer

首选方法是使用composer。如果您尚未安装composer，请遵循安装说明。

一旦安装了composer，请在您的项目根目录中执行以下命令来安装此库

composer require bbva/sdk dev-master

最后，请确保包含自动加载器

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

手动安装

要安装，只需

克隆存储库或下载库，并在您的项目文件夹结构中创建一个名为'Bbva'的文件夹。如果您以压缩文件的形式下载了客户端库，请解压缩它并创建正确的文件夹结构。
在将使用客户端库的PHP脚本顶部（或包含其他库的部分），添加客户端库的主脚本

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

注意：在上面的示例中，库位于名为Bbva的目录中，该目录位于包含客户端的PHP文件相同的目录中。请确保调整您项目中的路径，否则库将无法工作。

实现

配置

在使用库之前，将需要设置您的商户ID和私钥。有三个选项

使用方法 Bbva::setId() 和 Bbva::setApiKey()。只需将适当的参数传递给每个函数即可

Bbva::setId('moiep6umtcnanql3jrxp');
Bbva::setApiKey('sk_3433941e467c4875b178ce26348b0fac');
Bbva::setPublicIp('127.0.0.1'); //Tu ip publica

将商户ID和私钥作为参数传递给方法 Bbva::getInstance()，这是实例生成器

$bbva = Bbva::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c4875b178ce26348b0fac', '127.0.0.1');

将商户ID和私钥以及环境变量一起配置。这种方法有其自身的优点，因为敏感数据不会直接在任何脚本中暴露。

注意：请参阅PHP文档以获取有关此方法的更多信息。

沙箱/生产模式

为了方便和安全起见，客户端库默认激活沙箱模式。这允许您在实施Bbva时测试自己的代码，在生产环境中不对任何信用卡进行扣费。一旦完成集成，使用方法 Bbva::setProductionMode(FLAG) 将允许您激活/禁用沙箱模式。

Bbva::setProductionMode(true);

您还可以使用环境变量来达到这个目的

SetEnv BBVA_PRODUCTION_MODE true

如果需要，您可以使用方法 Bbva::getProductionMode() 在任何时候确定沙箱模式的状态

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

PHP客户端库简介

配置库后，您可以使用它与Bbva API服务进行交互。第一步是使用生成器获取实例

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

在这个例子中 $bbva 将是一个商户（根）的实例，将用于调用任何派生的子资源。根据当前版本的Bbva API，这些资源是

收费
令牌

您可以通过根实例的公共变量访问所有这些资源，因此，如果您想添加新客户，可以像以下这样做

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

每次调用任何资源都会返回该资源的实例。在上面的例子中，调用资源 tokens 中的 add() 方法将返回一个 Token 实例，调用资源 tokens 中的 add() 方法将返回一个 Card 实例，依此类推。唯一的例外是在使用 getList() 方法检索资源列表时，此时将返回一个实例数组。

// 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);

另一方面，根据 Bbva API 文档，从 Charge 派生的资源是

收费
令牌

参数

那些接收多个参数的方法（例如，尝试添加新客户或新客户的卡时），必须作为关联数组传递

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

注意：请参阅 Bbva API 文档，以确定每个情况下接受的参数、必须的参数以及哪些是可选的。

错误处理

Bbva API 会根据情况生成多种类型的错误，为了处理这些错误，PHP 客户端实现了五种类型的异常

BbvaApiTransactionError。此类包括交易未成功完成时发生的错误：卡片被拒绝、资金不足、目标账户无效等。
BbvaApiRequestError。它指的是请求 API 失败时生成的错误。例如：数据请求格式无效、请求参数不正确、Bbva 内部服务器错误等。
BbvaApiConnectionError。这些异常是在库尝试连接到 API 但连接失败时生成的。例如：超时、域名服务器等。
BbvaApiAuthError。当身份验证数据以无效格式指定或在 Bbva 服务器（商户 ID 或私钥）上未完全验证时生成的错误。
BbvaApiError。此类包括处理客户端库时发生的所有通用错误。

所有这些错误异常都通过以下方法提供 Bbva API 返回的所有信息

getDescription()：Bbva 服务器生成的错误描述。
getErrorCode()：Bbva 服务器生成的错误代码。当错误在请求之前生成时，此值等于零。
getCategory()：由 Bbva 服务器生成并确定的错误类别。当错误在请求之前或请求过程中生成时，此值为空字符串。
getHttpCode()：请求 Bbva 服务器时生成的 HTTP 错误代码。当错误在请求之前或请求过程中生成时，此值等于零。
getRequestId()：Bbva 服务器在处理请求时生成的 ID。当错误在请求之前生成时，此值为空字符串。

以下是一个更完整的错误捕获示例

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);
}

示例

客户

向商户添加新客户

$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'));

令牌

在商户中

添加令牌

$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);

获取令牌

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

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

费用

在商户中

对商户进行收费

$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);

获取收费

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

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

进行捕获

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

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

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

进行退款

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

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

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

bbva / sdk

维护者

详细信息