ebethus/bbvasdk

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

维护者

详细信息

github.com/EBethus/BBVALibPHP

源代码

问题

安装: 195

依赖项: 0

建议者: 0

安全: 0

星星: 0

关注者: 1

分支: 8

dev-master 2020-10-13 22:51 UTC

Requires

  • php: >=5.2.1
  • ext-curl: *
  • ext-hash: *

Requires (Dev)

Apache-2.0 454a4d6e01f0dcc0baa4e6a22e7acc31fbb906bc

  • BBVA <plataformas.especiales.mx.woop@bbva.com>

This package is auto-updated.

Last update: 2024-09-14 07:09:54 UTC

README

Bbva PHP

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

这是一个在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');
  • 将商户ID和私钥作为参数传递给方法 Bbva::getInstance()，这是一个实例生成器
$bbva = Bbva::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c4875b178ce26348b0fac');
  • 同时配置商户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');

在这个示例中，$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');

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

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

费用

在商户处

对商户进行收费

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

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

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

进行捕获

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

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

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

退款

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

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

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