README

以下项目是一个PHP SDK，它简化了Sipay电商服务的调用。

2. 快速入门

通过以下示例，您可以快速安装SDK并在终端执行一笔销售。在执行快速入门之前，我们需要创建配置文件，可参考配置部分

  $ git clone https://github.com/sipay/php-sdk
  $ echo '
  <?php
  require_once "php-sdk/src/autoload.php";
  $ecommerce = new \Sipay\Ecommerce("php-sdk/etc/config.ini"); // Configurar el archivo de configuración como se indica en la sección Ecommerce
  $amount = new \Sipay\Amount(100, "EUR");
  $card = new \Sipay\Paymethods\Card("4242424242424242", 2050, 12);
  $options = array(
    "order" => "order-test",
    "reference" => "1234",
    "token" => "new-token"
  );
  $auth = $ecommerce->authorization($card, $amount, $options);
  if($auth->code == 0){
    print("Autorización aceptada, el pago ha sido completado!\n");
  }else{
    print("Error: ".$auth->description."\n");
  }
  ' > quickstart.php
  $ php quickstart.php

3. 安装

3.1 预先要求

PHP >= 7.x

3.2 步骤

我们可以手动安装（请参阅“代码提取”）或使用Composer（请参阅“Composer”）。

3.2.1 代码提取

如果使用Composer安装，则省略此步骤。

  $ git clone https://github.com/sipay/php-sdk.git

然后设置“path_autoload”变量为“<php-sdk下载目录>/src/autoload.php”

$path_autoload = "<directorio_de_descarga_de_php-sdk>/src/autoload.php";

3.2.2 Composer

如果使用手动方法，则省略此步骤。

$ composer require sipay/php-sdk

然后设置“path_autoload”变量为“vendor/autoload.php”

$path_autoload = "vendor/autoload.php";

4. 配置

安装SDK后，需要更新与以下相关的配置参数

跟踪系统。
访问凭证（由Sipay集成部门管理）。
API环境和版本。
响应超时时间（Timeout）。

4.1 从文件中

以下是一个配置示例

; **************************************************************
; LOGGER
; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
; Configuración asociada al sistema de trazas.
;
; path: ruta del directorio de logs (Nota: Aconsejable usar rutas absolutas, en caso contrario los logs estaran dentro del paquete)
; level: nivel mínimo de trazas [debug, info, warning, error, critical]
; prefix: prefijo
; extension: extensión del archivo
; date_format: formato de fecha de las trazas
; backup_file_rotation: Número de ficheros de backup
; ------------------------------------------------------------//

[logger]
path=logs
level=warning
prefix=logger
extension=log
date_format=d/m/Y H:i:s
backup_file_rotation = 5

; **************************************************************
; CREDENTIALS
; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
; Credenciales para obtener acceso al recurso.
;
; key: Key del cliente
; secret: Secret del cliente
; resouce: Recurso al que se quiere acceder
; ------------------------------------------------------------//

[credentials]
key=api-key
secret=api-secret
resource=resource

; **************************************************************
; API
; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
; Configuracion de la API.
;
; environment: Entorno al que se deben enviar las peticiones ['sandbox', 'staging', 'live']
; version: Versión de la api a usar actualmente solo existe v1
; mode: Modo de encriptacion de la firma, [sha256, sha512]
; ------------------------------------------------------------//

[api]
environment=sandbox
version=v1
mode=sha256

; **************************************************************
; Connection
; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
; Cofiguracion de la conexión.
;
; timeout: Tiempo máximo de espera a la respuesta de la petición
; ------------------------------------------------------------//

[connection]
timeout=30

4.2 从变量中

在某些情况下，我们可能希望从变量中而不是从文件中加载配置。以下是一个示例

  <?php
  $config = array(
      'logger' => array(
          'path' => 'logs',  // Nombre del directorio donde se crearan los logs (Nota: si la ruta es relativa se creará en el directorio del paquete)
          'level' => 'warning',  // Nivel mínimo de trazas [debug, info, warning, error, critical]
          'prefix' => 'logger',  // Prefijo del nombre del archivo
          'extension' => 'log',  // Extensión del archivo
          'date_format' => 'd/m/Y H:i:s',  // Formato de fecha de las trazas de log
          'backup_file_rotation' => 5  // Número de ficheros de backup
      ),
      'credentials' => array(
          'key' => 'api-key',  // Key del cliente
          'secret' => 'api-secret',  // Secret del cliente
          'resource' => 'resource' // Recurso al que se quiere acceder
      ),
      'api' => array(
          'environment' => 'sandbox',  // Entorno al que se deben enviar las peticiones ['sandbox', 'staging', 'live']
          'version' => 'v1',  // Versión de la api a usar actualmente solo existe v1
          'mode' => 'sha256'  // Modo de encriptacion de la firma, [sha256, sha512]
      ),
      'connection' => array(
          'timeout' => 30  // Tiempo máximo de respuesta de la petición.
      )
  );

5. 扩展文档

通过向Sipay发送电商请求，可以执行以下操作

电子商务操作所需的对象（第5.1节）。
金额（第5.1.1节）。
卡（第5.1.2节）。
卡令牌化（第5.1.3节）。
FastPay捕获的卡（第5.1.4节）。
电子商务操作（第5.2节）。
身份验证（第5.2.1节）。
确认（第5.2.2节）。
取消（第5.2.3节）。
退款（第5.2.4节）。
操作或查询搜索（第5.2.5节）。
卡令牌化（第5.2.6节）。
搜索卡令牌化（第5.2.7节）。
取消卡令牌化（第5.2.8节）。

令牌化：这是一个将卡PAN（主要账户号码）替换为称为令牌的值的进程。此功能允许Sipay保存客户的卡数据，以简化支付过程并避免在重复支付中每次都输入卡数据。Sipay以安全的方式存储数据，符合PCI规范。

为了正确执行电子商务操作，需要掌握对象Amount、Card、StoredCard和FastPay的用法，它们标识金额和要使用的支付方式。

5.1. 电子商务操作所需的对象

5.1.1. `Amount(amount,currency)`

定义

此对象表示一个货币金额，因此该金额必须大于零（0）。要实例化此类对象，需要一个金额（amount）和一个货币（currency），格式为ISO4217（《https://zh.wikipedia.org/wiki/ISO_4217》）。金额可以以三种方式指定：

使用一个表示金额的标准字符串，其中用点（.）作为小数点分隔符（例如："1.56"），或者
使用一个表示货币的基本不可分割单位的字符串（例如："156"），或者
使用一个表示货币的基本不可分割单位的整数值，即欧元货币为分（例如：156）。

参数

amount: [必需] 是要处理的金额。可以用字符串或整数值表示。假设我们要处理1.56欧元，金额（1.56）作为字符串可以是'1.56'或'156'；作为整数值是156。
currency: [必需] 是一个表示货币代码（ISO4217）的字符串。

属性

amount: int，表示处理金额。无论是以前用字符串实例化还是不是，都将使用此类数据（受保护）。
currency: string，表示货币代码（ISO4217）（受保护）。

方法

set(amount, currency): 分配在参数部分指定的金额和货币。
get_amount(): 返回amount属性。
get_currency(): 返回currency属性。
get_array(): 以关联数组的形式返回amount和currency。

示例

  <?php
  require_once $path_autoload;

  // Con string
  $amount = new \Sipay\Amount('1.56', 'EUR');

  print($amount."\n")
  // Imprime 1.56EUR
  print($amount->get_amount()."\n")
  // Imprime 156
  print($amount->get_currency()."\n")
  // Imprime EUR

  // Con unidad indivisible
  $amount = new \Sipay\Amount(156, 'EUR');

  print($amount."\n")
  // Imprime 1.56EUR
  print($amount->get_amount()."\n")
  // Imprime 156
  print($amount->get_currency()."\n")
  // Imprime EUR

  // Con string en unidad indivisible
  $amount = new \Sipay\Amount('156', 'EUR');

  print($amount."\n")
  // Imprime 1.56EUR
  print($amount->get_amount()."\n")
  // Imprime 156
  print($amount->get_currency()."\n")
  // Imprime EUR

注意：如果用包含点的字符串初始化，则必须具有ISO4217标准所指示的小数位数。例如：对于欧元（€）货币，它设定了两位小数，则表示金额为"1.40"是正确的，但"1.4"是不正确的。

5.1.2. `Card(card_number, year, month, [cvv])`

定义

此对象表示一张可以在不同的电子商务操作中使用的水果。要获取Card实例，参数如下所示。

参数

card_number: [必需] 是一个长度在14到19位之间的字符串。代表卡片号码。
year: [必需] 是一个4位数的整数，表示卡片的到期年份。
month: [必需] 是一个介于1和12之间的2位数整数，对应于卡片的到期月份。
cvv: [可选] 是一个3到4位数的整数，代表卡片背面的CVV值。

属性

card_number: 在Card实例中是卡片号码。它是一个长度在14到19位之间的字符串（受保护）。
year: 在Card实例中是卡片到期年份。它是一个4位数的整数（受保护）。
month: 在Card实例中是卡片到期月份。它是一个1到12之间的2位数整数（受保护）。
cvv: 是一个3到4位数的整数，代表卡片背面的CVV值（受保护）。

方法

set_card_number(card_number): 允许分配卡片的PAN。
set_expiration_date(year, month): 允许分配卡片的到期日期。
get_year(): 返回年份属性。
get_month(): 返回月份属性。
get_card_number(): 返回卡号属性。
to_json(): 返回对象的全部属性。

示例

  <?php
  require_once $path_autoload;

  $card = new \Sipay\Paymethods\Card('4242424242424242', 2018, 12);

5.1.3. `StoredCard(token)`

定义

此对象表示Sipay中存储的可用于Ecommerce操作的卡。要获取StoredCard实例，需要以下参数。

参数

token: [必填] 是一个长度在6到128个字符之间的字母数字和短划线（protected）字符串。

属性

token: 长度在6到128个字符之间的字符串。

方法

set_token: 允许分配令牌。
get_token: 返回令牌。

示例

  <?php
  require_once $path_autoload;

  $card = new \Sipay\Paymethods\StoredCard('token-card');

5.1.4. `FastPay(token)`

定义

此对象表示通过FastPay方法获得的卡。它在该方法的支付操作后续步骤中使用。

参数

token: [必填] 是一个32个字符的十六进制字符字符串。

属性

token: 长度为32个字符的十六进制字符字符串（protected）。

方法

set_token: 允许分配令牌。
get_token: 返回令牌。

示例

  <?php
  require_once $path_autoload;

  $card = new \Sipay\Paymethods\FastPay('token-fast-pay');

5.2. Ecommerce操作 - `Ecommerce($config_file)` 或 `Ecommerce($config_var)`

描述

Ecommerce操作是定义在Ecommerce类中的方法的一部分。要实例化此类对象，需要配置文件。

示例

  <?php
  require_once $path_autoload;

  $ecommerce = \Sipay\Ecommerce('etc/config.ini');

参数

config_file [必填] 是配置文件的路径的字符串。

属性

以下属性（protected）在配置文件中分配。然而，它们在Ecommerce实例中是可访问的。建议以查询模式使用它们。

key: 对应于凭证的key。
secret: 对应于凭证的secret。
resource: 对应于凭证的resource。
environment: 对应于目标环境。
mode: 对应于请求的加密模式。
version: 对应于指向的API版本。
timeout: 从发送请求的那一刻起，接收响应的最大等待时间。

方法

所有指示的属性都有相应的set_[属性名]分配方法和get_[属性名]查询方法。

authentication(parameters): 允许使用PSD2参数进行认证和授权请求（参见5.2.1节）。
confirm(parameters): 是在认证后触发的资金捕获确认步骤（参见5.2.2节）。
cancellation(parameters): 允许发送取消请求（参见5.2.3节）。
refund(parameters): 允许进行退款（参见5.2.4节）。
query(parameters): 允许进行操作搜索请求（参见5.2.5节）。
register(parameters): 允许对卡进行令牌化（参见5.2.6节）。
card(parameters): 用于搜索已令牌化的卡（参见5.2.7节）。
unregister(parameters): 用于注销已令牌化的卡（参见5.2.8节）。

5.2.1 `authentication(Paymethods\Paymethod $paymethod, Amount $amount, array $array_options = array())`

定义

Ecommerce的这个方法允许向Sipay发送一个认证请求。

参数

paymethod: [必填] 是一个Card、StoredCard或FastPay的实例，指示要使用的支付方式。
amount : [必需] 对应于表示操作金额的 Amount 实例。如果使用金额 0，则会自动尝试执行 AVS 操作。
array_options:
- order : [可选] 是表示操作票据的 string。
- reconciliation : [可选] 是标识银行对账的 string。
- custom_01 : [可选] 是表示可定制字段的 string。
- custom_02 : [可选] 是表示可定制字段的 string。
- token: [可选] 是表示要存储的 token 的 string。当支付方式为 Card 或 Fpay 时使用，并且希望为使用的卡片分配一个特定的 token。
- sca_exemptions: [可选] 是表示 PSD2 可用豁免之一：LWV、TRA、COR、MIT 的 string。
- reason: [可选] 是表示执行豁免 MIT 操作的业务原因的 string：R、I、C、D、E、H、M、N。
- sca_preference: [可选] 是按优先级应用的豁免列表。
- previously_authenticated: [可选] 如果存在该字段，则应具有 'true' 值，以指示我们希望使用当前认证执行未来授权操作。

输出

authentication 方法返回一个 Authentication 对象。

示例

- 卡片认证

  $amount = \Sipay\Amount(100, 'EUR'); // 1€
  $card = \Sipay\Paymethods\Card('4242424242424242', 2050, 2);

  $auth = $ecommerce->authorization($card, $amount);

- 快速支付授权

   $amount = \Sipay\Amount(100, 'EUR'); // 1€
   $fp = \Sipay\Paymethods\FastPay('830dc0b45f8945fab229000347646ca5');

   $auth = $ecommerce->authorization($fp, $amount);

5.2.2 `confirm(request_id)`

定义

此方法允许在完成认证过程后执行资金捕获（授权）。

参数

request_id:[必需] 是在认证操作中返回的请求标识符。位于认证返回的目标中的 request_id 属性中。

输出

confirm 方法返回一个 Confirm 对象。

示例

- 卡片认证

  $auth = $ecommerce->authentication($card, $amount, $options);
  $auth1 = $ecommerce->confirm(array('request_id' => $auth->request_id));

5.2.3 `cancellation(string $transaction_id)`

定义

此方法允许向 Sipay 发送取消请求。

参数

transaction_id: [必需] 是表示交易标识符的 string。

输出

cancellation 方法返回一个 Cancellation 对象。

示例

  $cancel = $ecommerce->cancellation('transaction_id');

5.2.4 `refund($identificator, Amount $amount, array $array_options = array())`

定义

此 Ecommerce 方法允许向 Sipay 发送退款请求。

参数

identificator: [必需] 是表示支付方法（Card、StoredCard 或 FastPay）或表示交易标识符的 string。
amount : [必需] 是表示操作金额的 Amount 实例。
array_options:
- order : [可选] 是表示操作票据的 string。
- reconciliation : [可选] 是标识银行对账的 string。
- custom_01 : [可选] 是表示可定制字段的 string。
- custom_02 : [可选] 是表示可定制字段的 string。
- token: [可选] 是表示要存储的 token 的 string。当支付方式为 Card 或 Fpay 时使用，并且希望为使用的卡片分配一个特定的 token。

输出

refund 方法返回一个 Refund 对象。

示例

- 卡片退款

  $amount = \Sipay\Amount(100, 'EUR'); // 1€
  $card = \Sipay\Paymethods\StoredCard('bd6613acc6bd4ac7b6aa96fb92b2572a');
  $refund = $ecommerce->refund($card, $amount);

- 使用 transaction_id 的退款

  $amount = \Sipay\Amount(100, 'EUR'); // 1€

  $refund = $ecommerce->refund('transaction_id', $amount);

5.2.5 `query(array $query)`

定义

此 Ecommerce 方法允许向 Sipay 发送请求以搜索特定操作。

参数

此方法可以具有以下参数

order: [可选] 表示操作票据的 string。
transaction_id: [可选] 表示交易标识符的 string。

如果没有发送任何参数，则返回客户的全部交易。

输出

query 方法返回一个 Query 对象。

示例

- 搜索交易

  $query = array('transaction_id' => 'transaction_id');
  $query = $ecommerce->query($query);

5.2.6 `register(Paymethods\Paymethod $card, string $token)`

定义

此 Ecommerce 方法允许向 Sipay 发送卡片令牌化请求。

参数

card: [必需] 是表示要令牌化的卡片的 Card 类型实例或 FastPay。
token:[必需] 是表示将关联到卡片的 token 的 string。

输出

El método `register` devuelve un objeto `Register`.

示例

- 注册卡片

  $card = \Sipay\Paymethods\Card('4242424242424242', 2050, 2);

  $masked_card = $ecommerce->register($card, 'newtoken');

5.2.7 `card(string $token)`

定义

此方法 Ecommerce 允许向 Sipay 发送请求以获取已token化的卡片的详细信息。

参数

token: [必填] 表示与卡片关联的token的 string。

输出

card 方法返回 Responses 部分的 Card 对象。

示例

- 搜索卡片

   $masked_card = $ecommerce->card('newtoken');

5.2.8 `unregister(string $token)`

定义

此方法 Ecommerce 允许向 Sipay 发送请求以注销已token化的卡片。

参数

token: [必填] 表示与卡片关联的token的 string。

输出

unregister 方法返回 Unregister 对象。

示例

- 从注册表中删除一张卡片

  $unregister = $ecommerce->unregister('newtoken');

5.3 响应

所有作为 Ecommerce 操作响应获得的对象都具有以下属性。

5.3.1 公共属性

type: 这是一个标识响应类型的 enum[string]。
- success
- warning
- error
code: 这是一个表示结果标识符的 int。它是一个指示性代码，并不严格绑定到响应原因，即代码并不唯一标识响应。
- 如果 code 为 0，则表示结果为 success
- 如果 code 大于 0，则表示结果为 warning
- 如果 code 小于 0，则表示结果为 error
detail: 这是一个表示唯一标识响应的代码的 string，由字母数字组成，并用下划线分隔，且不使用大写字母。这对于管理操作的多种用例非常有用。
description: 这是一个表示响应消息的文本描述的 string。
uuid: 这是一个表示请求唯一标识符的 string，对于跟踪至关重要。
request_id: 这是一个在完成某些操作时使用的 string。将在需要时说明。
request: 这是一个包含已向服务器发送的请求数据的 dictionary（受保护）。
response: 这是一个包含响应原始数据的 dictionary（受保护）。

5.3.2 `Authorization`

此对象添加以下属性

amount: 表示操作金额的 Amount 类型对象。
order: 表示操作票据的 string。
card_trade: 表示卡片发行者的 string。
card_type: 表示卡片类型的 string。
masked_card: 表示已屏蔽的卡片号的 string。
reconciliation: 表示银行对账标识符的 string（第37页）。
transaction_id: 表示交易标识符的 string。
approval: 表示实体批准代码的 string。
authorizator: 表示操作授权实体的 string。

5.3.3 `Refund`

此对象添加以下属性

amount 表示操作金额的 Amount 类型对象。
order: 表示操作票据的 string。
card_trade: 表示卡片发行者的 string。
card_type: 表示卡片类型的 string。
masked_card: 表示已屏蔽的卡片号的 string。
reconciliation: 表示银行对账标识符的 string（第37页）。
transaction_id: 表示交易标识符的 string。
approval: 表示实体批准代码的 string。
authorizator: 表示操作授权实体的 string。

5.3.4 `Query`

此对象添加一个交易列表，每个交易对象都有

Transaction

description: 表示操作状态的文本描述的 string。
date: 表示操作日期和时间的 datetime。
order: 表示操作票据的 string。
masked_card: 表示已屏蔽的卡片号的 string。
operation_name: 表示操作类型的文本名称的 string。
operation: 它是一个表示操作类型的 string 标识符。
transaction_id: 表示交易标识符的 string。
status: 它是一个表示操作状态的 string 标识符。
amount: 它是一个包含操作金额的 Amount 对象。
authorization_id: 它是一个表示授权实体的 string 标识符。
channel_name: 它是一个表示支付渠道名称的 string。
channel: 它是一个表示支付渠道的 string 标识符。
method: 它是一个表示支付方式的 string 标识符。
method_name: 它是一个表示支付方式的 string 文字标识符。

5.3.5 `Register`

此对象添加以下属性

card_mask: 它是一个表示被屏蔽的卡号的 string。
expired_at: 它是一个表示过期日期的 date。
token: 它是一个表示卡号的 string 标识符。
card: 它是一个包含关联卡的 StoredCard 对象。

5.3.6 `Cancellation`

此对象不添加任何共同属性。

5.3.7 `Card`

card_mask: 它是一个表示被屏蔽的卡号的 string。
expired_at: 它是一个类型为 date 的参数，表示卡的过期日期。
token: 它是一个表示卡号的 string 标识符。
card: 它是一个包含返回的卡相关数据的 StoredCard 对象。

5.3.8 `Unregister`

此对象不添加任何共同属性。

5.3.9 `Card`

cvv: 它是一个表示卡号的 string 标识符。

sipay / php-sdk

维护者

详细信息

README

2. 快速入门

3. 安装

3.1 预先要求

3.2 步骤

3.2.1 代码提取

3.2.2 Composer

4. 配置

4.1 从文件中

4.2 从变量中

5. 扩展文档

5.1. 电子商务操作所需的对象

5.1.1. Amount(amount,currency)

定义

参数

属性

方法

示例

5.1.2. Card(card_number, year, month, [cvv])

定义

参数

属性

方法

示例

5.1.3. StoredCard(token)

定义

参数

属性

方法

示例

5.1.4. FastPay(token)

定义

参数

属性

方法

示例

5.2. Ecommerce操作 - Ecommerce($config_file) 或 Ecommerce($config_var)

描述

示例

参数

属性

方法

5.2.1 authentication(Paymethods\Paymethod $paymethod, Amount $amount, array $array_options = array())

定义

参数

输出

示例

5.2.2 confirm(request_id)

定义

参数

输出

示例

5.2.3 cancellation(string $transaction_id)

定义

参数

输出

示例

5.2.4 refund($identificator, Amount $amount, array $array_options = array())

定义

参数

输出

示例

5.2.5 query(array $query)

定义

参数

输出

示例

5.2.6 register(Paymethods\Paymethod $card, string $token)

定义

参数

输出

示例

5.2.7 card(string $token)

定义

参数

输出

示例

5.1.1. `Amount(amount,currency)`

5.1.2. `Card(card_number, year, month, [cvv])`

5.1.3. `StoredCard(token)`

5.1.4. `FastPay(token)`

5.2. Ecommerce操作 - `Ecommerce($config_file)` 或 `Ecommerce($config_var)`

5.2.1 `authentication(Paymethods\Paymethod $paymethod, Amount $amount, array $array_options = array())`

5.2.2 `confirm(request_id)`

5.2.3 `cancellation(string $transaction_id)`

5.2.4 `refund($identificator, Amount $amount, array $array_options = array())`

5.2.5 `query(array $query)`

5.2.6 `register(Paymethods\Paymethod $card, string $token)`

5.2.7 `card(string $token)`

5.2.8 `unregister(string $token)`

5.3.2 `Authorization`

5.3.3 `Refund`

5.3.4 `Query`

5.3.5 `Register`

5.3.6 `Cancellation`

5.3.7 `Card`

5.3.8 `Unregister`

5.3.9 `Card`