README

这是PHP的SDK。像所有BlockChyp SDK一样，它为BlockChyp网关和BlockChyp支付终端提供完整的客户端。

安装

安装BlockChyp的首选方法是通过composer。从您的项目根目录中输入以下命令，将BlockChyp添加到您的composer.json文件中。

composer require blockchyp/blockchyp-php

面向公众的网页

如果您使用PHP，那么您的前端很可能是一个网页。这个SDK非常适合与终端和BlockChyp网关通信，但仅凭自身不足以处理电子商务场景。

对于电子商务，请考虑使用我们的Web Tokenizer补充SDK。这是一个纯JavaScript库，允许您通过跨源iframe对电子商务支付进行令牌化。这可以使您不在PCI范围内。在GitHub上查看。

简单示例

运行您的第一个交易很简单。确保您有BlockChyp终端，激活它，并生成一组API密钥。下面的示例代码展示了如何运行基本的终端交易。

<?php
  require_once('vendor/autoload.php');

  use \BlockChyp\BlockChyp;

  BlockChyp::setApiKey('SPBXTSDAQVFFX5MGQMUMIRINVI');
  BlockChyp::setBearerToken('7BXBTBUPSL3BP7I6Z2CFU6H3WQ');
  BlockChyp::setSigningKey('bcae3708938cb8004ab1278e6c0fcd68f9d815e1c3c86228d028242b147af58e');

  $request = [
    'test' => TRUE,
    'terminalName' => 'Test Terminal',
    'amount' => '55.00',
  ];

  $response = BlockChyp::charge($request);

  echo 'Response: ' . print_r($response, TRUE) . PHP_EOL;

其他文档

完整的文档可以在我们的开发者文档门户上找到。

获取开发套件

为了测试您与真实终端的集成，您需要一个BlockChyp开发套件。我们的套件包括一个功能齐全的支付终端，带有测试PIN加密密钥。每个套件都包括一套完整的测试卡，包括每个主要卡品牌和输入方法（包括非接触式和接触EMV磁条卡）的测试卡。每个套件还包括我们区块链礼品卡系统的测试礼品卡。

BlockChyp的开发者计划目前仅限邀请，但您可以通过联系我们的工程团队在 nerds@blockchyp.com 请求邀请。

您还可以在我们的YouTube频道上查看许多长篇演示，并了解更多关于我们的信息。

交易代码示例

您不想阅读文字。您需要示例。以下是您可以使用BlockChyp PHP SDK和几个基本示例完成的操作快速概述。

支付端点

这些是用于在BlockChyp中执行和操作支付交易的核心理解API。

Charge

API凭证类型：商家
所需角色：支付API访问

我们最受欢迎的交易执行标准授权和捕获。这是最基本的支付交易，通常用于传统零售。

Charge交易可以使用支付终端捕获支付或使用之前注册的支付令牌。

终端交易

对于终端交易，请确保使用terminalName属性传入终端名称。

令牌交易

如果您有支付令牌，则省略terminalName属性，并使用token属性传入令牌。

卡号和磁条

您还可以传入PAN和磁条卡，但您可能不应该这样做，因为这会使您进入PCI范围，而POS系统最常见的漏洞攻击方式是键盘记录。如果您使用终端进行手动卡输入，您将绕过可能恶意运行的POS系统上的任何键盘记录器。

常见变体

礼品卡兑换：在BlockChyp中，没有特殊的API用于礼品卡兑换。只需执行一个普通交易即可，如果客户刷了礼品卡，我们的终端将识别礼品卡并执行礼品卡兑换。另外，请注意，如果由于某种原因，礼品卡的原购买交易与欺诈或退货有关，则该交易将被拒绝。
EBT：将CardType字段设置为BlockChyp::CARD_TYPE_EBT以处理EBT SNAP交易。请注意，测试EBT交易始终假设余额为100.00美元，因此超过该金额的测试EBT交易可能会被拒绝。
现金退还：要启用借记交易的现金退还，请设置CashBack字段。如果出示的卡片不是借记卡，则忽略CashBack字段。
手动卡输入：将ManualEntry字段设置为启用手动卡输入。当芯片和磁条读取器不工作时，作为备份或在更安全的电话订单中使用。您甚至可以将ManualEntry字段与CardType字段设置为BlockChyp::CARD_TYPE_EBT结合使用，以进行手动EBT卡输入。
即时令牌化：您可以通过设置Enroll字段在交易过程中将支付方式注册到令牌保险库中。您将在响应中收到一个令牌。如果您还传递了客户数据，您甚至可以将令牌绑定到客户记录。
提示小费：如果您想在授权之前提示客户支付小费，请设置PromptForTip字段。这对于桌面支付和其他与服务相关的场景非常有用。
现金折扣和附加费：可以使用Surcharge和CashDiscount字段一起支持现金折扣或附加费问题。有关详细信息，请参阅现金折扣文档。
加密货币：可以使用Cryptocurrency字段将标准卡支付屏幕切换到加密货币屏幕。字段值可以是ANY以启用任何支持的加密货币，或单个货币代码，例如BTC表示比特币。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'amount' => '55.00',
];


$response = BlockChyp::charge($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

预先授权

API凭证类型：商家
所需角色：支付API访问

预先授权将冻结资金，必须在稍后捕获。这用于最终交易金额可能发生变化的情况。一个常见的例子是高级餐厅，在最终结算之前需要调整小费。

预先授权的另一个用例是电子商务。通常，在线订单在订单时进行预先授权，然后在发货时进行捕获。

预先授权可以使用支付终端进行捕获支付或使用先前注册的支付令牌。

终端交易

对于终端交易，请确保使用terminalName属性传入终端名称。

令牌交易

如果您有支付令牌，则省略terminalName属性，并使用token属性传入令牌。

卡号和磁条

加密货币

请注意，预先授权不支持加密货币。

常见变体

手动卡输入：将ManualEntry字段设置为启用手动卡输入。当芯片和磁条读取器不工作时，作为备份或在更安全的电话订单中使用。您甚至可以将ManualEntry字段与CardType设置为BlockChyp::CARD_TYPE_EBT结合使用，以进行手动EBT卡输入。
行内令牌化：您可以通过设置 Enroll 字段，将支付方式与交易一起在令牌保险库中注册。您将在响应中获得一个令牌。如果您还传入客户数据，您甚至可以将令牌绑定到客户记录。
提示小费：如果您想在授权前提示客户支付小费，请设置 PromptForTip 字段。您可以在预授权过程中提示小费，尽管这不是一个非常常见的做法。
现金折扣和附加费：可以使用Surcharge和CashDiscount字段一起支持现金折扣或附加费问题。有关详细信息，请参阅现金折扣文档。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'amount' => '27.00',
];


$response = BlockChyp::preauth($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

捕获预授权

API凭证类型：商家
所需角色：支付API访问

此API允许您捕获先前批准的预授权。

您需要确保传入原始预授权交易返回的交易ID，以便我们知道要捕获哪个交易。如果您想按照预授权的确切金额捕获交易，则只需要传入交易ID。

如果您需要调整总额，可以通过传入新的 amount 来实现。我们还建议您传入更新后的 tax 和 tip 金额，因为它有时可以降低您的交易费。（例如，二级处理。）

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'transactionId' => '<ORIGINAL TRANSACTION ID>',
    'amount' => '32.00',
];


$response = BlockChyp::capture($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

退款

API凭证类型：商家
所需角色：支付API访问

这并不理想，但有时客户想要退款。

我们的退款API允许您通过在几种不同场景中执行退款来应对这一不愉快的现实。

最具抗欺诈性的方法是执行在先前交易上下文中的退款。您应该始终跟踪BlockChyp响应中返回的交易ID。要全额退款上一笔交易，只需传入原始交易ID和退款请求。

部分退款

对于部分退款，只需传入金额和交易ID。唯一的规定是金额必须等于或小于原始交易。只要总退款金额不超过原始金额，您就可以针对同一原始交易执行多个部分退款。

令牌化退款

您也可以使用令牌来执行退款。传入令牌而不是交易ID和所需的退款金额。

自由范围退款

当您在没有引用先前交易的情况下执行退款时，我们称这为 自由范围退款。

我们不推荐这种退款方式，但它是被允许的。如果您绝对坚持这样做，请传入终端名称和金额。

您可以通过将 ManualEntry 字段传递给自由范围退款请求来执行手动或按键退款。

礼品卡退款

在先前交易上下文中允许礼品卡退款，但不允许自由范围礼品卡退款。如果您需要向礼品卡添加更多资金，请使用礼品卡激活API。

存储和转发支持

当终端回退到存储和转发模式时，不允许退款。

自动取消授权

如果在一个原始交易的批次关闭之前，对引用先前交易的退款执行了全额退款，则退款将自动转换为取消授权。这可以为商家节省一些费用。

加密货币

请注意，不支持加密货币退款。您必须从您的加密货币钱包手动退款加密货币交易。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'transactionId' => '<PREVIOUS TRANSACTION ID>',

    // Optional amount for partial refunds.
    'amount' => '5.00',
];


$response = BlockChyp::refund($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

取消授权

API凭证类型：商家
所需角色：支付API访问

错误是难免的。如果交易是错误的，您可以使用此API取消授权。所需的所有内容只是传入交易ID并在原始交易的批次关闭之前执行取消授权。

取消授权与EBT和礼品卡交易一起使用时无需额外参数。

加密货币

请注意，不支持加密货币取消授权。您必须从您的加密货币钱包手动退款加密货币交易。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'transactionId' => '<PREVIOUS TRANSACTION ID>',
];


$response = BlockChyp::void($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

超时撤销

API凭证类型：商家
所需角色：支付API访问

支付交易需要一个稳定的网络才能正常工作，而且没有网络是始终稳定的。超时撤销是在网络条件不稳定时重新尝试支付时，防止意外向消费者重复收费的绝佳防御措施。

我们强烈建议开发者在遇到收费、预授权或退款交易超时时使用此API。如果您没有从BlockChyp收到明确的响应，您不能确定交易是否已成功进行。

在这种情况下，最佳实践是发送超时撤销请求。超时撤销会检查交易，如果存在则取消。

唯一的注意事项是，在执行收费、预授权和退款交易时，开发者必须使用transactionRef属性（CLI中使用txRef）。

这项要求的原因是，如果系统从未收到交易的确切响应，系统就永远不会收到BlockChyp生成的交易ID。我们必须回退到交易Ref来识别交易。

加密货币

请注意，不支持加密货币退款。您必须从您的加密货币钱包手动退款加密货币交易。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'transactionRef' => '<LAST TRANSACTION REF>',
];


$response = BlockChyp::reverse($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

礼品卡激活

API凭证类型：商家
所需角色：支付API访问

此API激活或向BlockChyp礼品卡添加价值。只需传入终端名称和要添加到卡上的金额。一旦顾客刷卡，终端将使用磁条上的密钥向卡上添加价值。

您不需要以任何特殊方式处理新的礼品卡激活或礼品卡充值。终端固件将自行处理，同时返回礼品卡的新余额。

这是系统中BlockChyp区块链DNA最接近表面的部分。BlockChyp礼品卡系统实际上并不使用礼品卡号码。这意味着它们无法被盗。

BlockChyp使用椭圆曲线公钥来识别卡片。礼品卡交易实际上是使用这些密钥签名的块。这意味着网络上没有共享的秘密。要跟踪BlockChyp礼品卡，请保留在礼品卡激活期间返回的公钥。这就是礼品卡的椭圆曲线公钥。

我们有时会在礼品卡上打印数字，但这些实际上是公钥一部分的十进制编码散列，以使礼品卡看起来对普通人来说更正常。它们可用于余额检查，并在在线礼品卡授权中发挥作用，但除此之外几乎没有其他用途。

撤销和退款

礼品卡激活可以像其他任何BlockChyp交易一样被撤销和退款。使用交易ID或交易Ref来识别礼品卡激活交易，就像通常用于撤销或退款传统支付交易一样。

导入礼品卡

BlockChyp确实有从传统礼品卡平台导入礼品卡责任的能力。遗憾的是，BlockChyp不支持在第三方系统上激活卡片。但是，您可以导入您的未结礼品卡，顾客可以在终端上刷卡，就像BlockChyp的标准礼品卡一样。

访问此功能不需要特殊编码。网关和终端固件会为您处理一切。

第三方礼品卡网络

BlockChyp目前不提供对其他礼品卡平台的任何原生支持，除了导入礼品卡责任。我们确实有一个白名单系统，可以用于支持您自己的自定义礼品卡实现。在我们允许BIN范围白名单之前，我们需要进行安全审查，因此如果您需要白名单一个BIN范围，请联系support@blockchyp.com。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'amount' => '50.00',
];


$response = BlockChyp::giftActivate($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

余额

API凭证类型：商家
所需角色：支付API访问

此API检查礼品卡或EBT卡的余额。

礼品卡余额检查

对于礼品卡，传入终端名称，顾客将被提示在该终端上刷卡。剩余余额将短暂显示在终端屏幕上，API响应将包括礼品卡的公钥和剩余余额。

EBT余额检查

所有EBT交易都需要PIN码，因此要检查EBT卡余额，您需要像正常EBT收费交易一样传入ebt标志。客户将被提示刷卡并输入PIN码。如果一切检查无误，卡上的剩余余额将在终端上显示给客户，并通过API响应返回。

测试礼品卡余额检查

测试礼品卡余额检查与实时礼品卡没有区别。您必须首先激活一个测试礼品卡来测试余额检查。测试礼品卡是真实的区块链卡，位于我们的并行测试区块链上。

测试EBT礼品卡余额检查

所有测试EBT交易都假定起始余额为100.00美元。因此，测试EBT余额检查总是返回100.00美元的余额。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'cardType' => BlockChyp::CARD_TYPE_EBT,
];


$response = BlockChyp::balance($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

关闭批次

API凭证类型：商家
所需角色：支付API访问

如果批次目前是打开的，此API将关闭商家的批次。

默认情况下，商家批次将在当地时间凌晨3点自动关闭。自动批次关闭时间可以在商家配置文件中更改或完全禁用。

如果禁用了自动批次关闭，您需要使用此API手动关闭批次。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
];


$response = BlockChyp::closeBatch($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

发送支付链接

API凭证类型：商家
所需角色：支付API访问

此API允许您向客户发送发票并通过BlockChyp托管支付页面捕获支付。

如果您设置了autoSend标志，BlockChyp将为您向客户发送包含支付链接的基本发票电子邮件。如果您想对电子邮件消息的外观有更多控制权，您可以省略autoSend标志并自行发送客户电子邮件。

此API有许多可选参数，但至少您需要传入总计、客户姓名和电子邮件地址。（除非您使用cashier标志。）

客户信息

除非您使用cashier标志，否则您必须指定一个客户；通过创建新的客户记录或传入现有的客户ID或客户引用来完成。

行项目级别数据

这不是强制性的，但我们强烈建议在每次请求中都发送行项目级别细节。这将使发票看起来更完整，行项目级别数据的格式与终端行项目显示使用的格式完全相同，因此可以使用相同的代码支持这两个区域。

描述

您还可以提供自由形式的描述或消息，在发票底部附近显示。通常这是一种感谢或指示。

条款和条件

您可以在请求中包含长格式合同语言，同时捕获支付时接受的条款和条件。

界面与终端基于的条款和条件API相同，您可以直接通过tcContent传入内容，或通过tcAlias传入预先配置的模板。当将协议接受纳入发送链接请求时，条款和条件日志也将更新。

自动发送

BlockChyp不会自动发送电子邮件通知。这种安全措施可以防止在您可能没有预料到的时候发送真实电子邮件。如果您希望BlockChyp为您发送电子邮件，只需在所有请求中添加autoSend标志。

加密货币

如果商家配置为支持加密货币交易，支付页面将显示额外的UI小部件，允许客户切换到加密货币支付方式。

令牌化

将enroll标志添加到发送链接请求中，将支付方式注册到令牌库中。

将enrollOnly标志添加到支付方式注册到令牌库中，而不立即进行任何支付。支付链接将要求用户输入他们的支付信息，并通知他们他们将不会立即被收费，但他们的支付可能会用于未来的交易。

收银员面对卡输入

BlockChyp 可以用于生成面向内部/收银台的卡信息录入页面。这适用于你可能需要接听电话订单但没有可用终端的情况。

如果你传入 cashier 标志，则不会发送电子邮件，并且你可以在浏览器或iframe中加载链接进行支付录入。当使用 cashier 标志时，将忽略 autoSend 标志。

请注意，收银台支付录入不支持加密货币。

支付通知

当客户成功提交支付时，商户将收到一封电子邮件通知他们已收到支付。

实时回调通知

电子邮件通知很好，但你可能希望系统在支付事件发生时立即通知你。通过使用可选的 callbackUrl 请求属性，你可以在用户提交支付（无论批准与否）时，指定一个URL，授权响应将被发送到该URL。

响应将以JSON编码的POST请求的形式发送，并且与所有BlockChyp费用和预授权交易响应的格式完全相同。

状态轮询

如果你的环境不实用或不必要实时回调，你可以始终使用后面描述的支付链接状态API。

使用发送链接API和状态轮询的常见用例是路边取货。当客户到达时，你的系统可以检查支付链接的状态，以确保已支付，而不必创建后台线程不断轮询状态更新。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'transactionRef' => '<TX REF>',
    'amount' => '199.99',
    'description' => 'Widget',
    'subject' => 'Widget invoice',
    'transaction' => [
        'subtotal' => '195.00',
        'tax' => '4.99',
        'total' => '199.99',
        'items' => [
            [
                'description' => 'Widget',
                'price' => '195.00',
                'quantity' => 1,
            ],
        ],
    ],
    'autoSend' => true,
    'customer' => [
        'customerRef' => 'Customer reference string',
        'firstName' => 'FirstName',
        'lastName' => 'LastName',
        'companyName' => 'Company Name',
        'emailAddress' => 'notifications@blockchypteam.m8r.co',
        'smsNumber' => '(123) 123-1231',
    ],
];


$response = BlockChyp::sendPaymentLink($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

重新发送支付链接

API凭证类型：商家
所需角色：支付API访问

此API将重新发送之前创建的支付链接。如果支付链接已过期、已取消或已被支付，则返回错误。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'linkCode' => '<PAYMENT LINK CODE>',
];


$response = BlockChyp::resendPaymentLink($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

取消支付链接

API凭证类型：商家
所需角色：支付API访问

此API取消支付链接。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'linkCode' => '<PAYMENT LINK CODE>',
];


$response = BlockChyp::cancelPaymentLink($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

支付链接状态

API凭证类型：商家
所需角色：支付API访问

此API允许你检查支付链接的状态，包括交易数据和尝试交易的完整历史。

当你想要检查支付链接的状态时（而不是交易状态），此API是首选的真实来源和最佳实践。交易状态API不是理想的选择，因为当有多个交易与单个支付链接相关联时，存在歧义。

你必须传入与支付链接相关的 linkCode 值。它包含在BlockChyp在原始创建支付链接时返回的响应中。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'linkCode' => '<PAYMENT LINK CODE>',
];


$response = BlockChyp::paymentLinkStatus($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

交易状态

API凭证类型：商家
所需角色：支付API访问

此API返回任何交易的当前状态。你可以通过BlockChyp分配的交易ID或你自己的交易引用来查找交易。

你应该始终使用全局唯一的交易引用值，但在重复交易引用的情况下，将返回与你的交易引用匹配的最新交易。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'transactionId' => '<TRANSACTION ID>',
];


$response = BlockChyp::transactionStatus($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

现金折扣

API凭证类型：商家
所需角色：支付API访问

此API计算现金交易的附加费、现金折扣和总金额。

如果你使用BlockChyp的现金折扣功能，可以使用此端点确保真实现金交易的数量和收据与BlockChyp处理的交易一致。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'amount' => '100.00',
    'cashDiscount' => true,
    'surcharge' => true,
];


$response = BlockChyp::cashDiscount($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

批量历史记录

API凭证类型：商家
所需角色：支付API访问

此端点允许开发人员查询网关的商户批量历史记录。数据将按开放日期降序返回，最近批次的批次首先返回。结果将包括有关批次的简要信息。考虑使用批量详细信息API以获取有关特定批次的更多详细信息。

限制结果

此API将返回最多250个结果。使用 maxResults 属性进一步限制最大结果，并使用 startIndex 属性浏览跨越多个查询的结果。

例如，如果您想获取最近的十个批次，请将maxResults参数的值设为10。请注意，startIndex是从0开始的。使用0的值来获取数据集中的第一个批次。

按日期范围过滤

您还可以通过日期来过滤结果。使用startDate和endDate属性，只返回那些在指定日期之间打开的批次。您可以同时使用startDate和endDate，并且可以将日期过滤器与maxResults和startIndex一起使用。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'maxResults' => 250,
    'startIndex' => 0,
];


$response = BlockChyp::batchHistory($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

批次详情

API凭证类型：商家
所需角色：支付API访问

此API允许开发者获取特定批次的详细信息，包括捕获的量、礼品卡活动、预期存款以及按终端拆分的捕获量。

唯一必需的请求参数是batchId。批次ID在每个交易响应中都会返回，并且可以使用批次历史API找到。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'batchId' => '<BATCH ID>',
];


$response = BlockChyp::batchDetails($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

交易历史

API凭证类型：商家
所需角色：支付API访问

此端点提供几种不同的方法来筛选交易历史。

默认情况下，如果没有过滤属性，此端点将返回最近的250笔交易。

限制结果

此API将每次查询返回最多50个结果。使用maxResults属性进一步限制最大结果数量，并使用startIndex属性分页浏览跨越多个查询的结果。

例如，如果您想获取最近的十个批次，请将maxResults参数的值设为10。请注意，startIndex是从0开始的。使用0的值来获取数据集中的第一个交易。

按日期范围过滤

您还可以通过日期来过滤结果。使用startDate和endDate属性，只返回那些在指定日期之间进行的交易。您可以同时使用startDate或endDate，并且可以将日期过滤器与maxResults和startIndex一起使用。

按批次过滤

要限制结果为单个批次，请传入batchId参数。

按终端过滤

要限制结果为在单个终端上执行的结果，请传入终端名称。

组合过滤器

上述任何过滤器都不是互斥的。您可以在单个请求中组合上述任何属性，以限制交易结果为更窄的结果集。

搜索交易历史

您可以通过传递带有query选项的搜索标准来搜索交易历史。搜索系统将与金额（请求和授权）、卡号最后四位、持卡人姓名和授权码进行匹配。

请注意，当使用搜索查询时，不支持终端名称或批次ID过滤器。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'maxResults' => 10,
    'batchId' => '<BATCH ID>',
];


$response = BlockChyp::transactionHistory($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

列出排队交易

API凭证类型：商家
所需角色：支付API访问

返回在终端上排队的交易的交易引用列表。可以使用交易状态API检索交易详情。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalName' => 'Test Terminal',
];


$response = BlockChyp::listQueuedTransactions($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

删除排队交易

API凭证类型：商家
所需角色：支付API访问

从终端中删除一个或所有排队交易。如果传入的*作为交易引用，则整个终端队列将被清除。如果传入的交易引用未在终端上排队，则返回错误。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalName' => 'Test Terminal',
    'transactionRef' => '*',
];


$response = BlockChyp::deleteQueuedTransaction($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

终端管理端点

这些API支持终端管理功能以及额外的终端功能，如行项显示、消息和交互式提示。
这些功能可以用来扩展销售点系统的功能。

终端Ping

API凭证类型：商家
所需角色：支付API访问

这个简单的测试交易有助于确保与支付终端的良好通信，通常是在开发过程中运行的第一项测试。

它测试与终端的通信，如果一切正常，则返回积极响应。它以相同的方式在本地或云中继模式下工作。

如果您得到积极响应，您已成功验证以下所有内容

终端在线。
到终端的有效路由存在。
API凭证有效。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalName' => 'Test Terminal',
];


$response = BlockChyp::ping($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

终端定位

API凭证类型：商家
所需角色：支付API访问

此端点返回终端的路径和位置信息。

结果将指示终端是否处于云中继模式，如果终端处于本地模式，将返回本地IP地址。

终端还将返回终端的公钥。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalName' => 'Test Terminal',
];


$response = BlockChyp::locate($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

终端清除

API凭证类型：商家
所需角色：支付API访问

此API中断终端可能正在进行的任何操作，并将其返回到空闲状态。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
];


$response = BlockChyp::clear($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

终端状态

API凭证类型：商家
所需角色：支付API访问

此API返回支付终端的当前状态。这通常用于在发送新交易之前确定终端是否忙碌。

如果终端忙碌，则idle将为false，status字段将返回指示当前正在进行的交易类型的简短字符串。系统还会在since字段中返回上次状态更改的时间戳。

响应中的cardInSlot字段将指示卡片是否当前在读卡器插槽中。

如果系统正在运行支付交易，并且您明智地传递了交易引用号，此API还将返回正在进行的交易的交易引用号。

下表列出了所有可能的状态响应。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalName' => 'Test Terminal',
];


$response = BlockChyp::terminalStatus($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

捕获签名

API凭证类型：商家
所需角色：支付API访问

此端点从终端捕获手写签名并返回图像。

与条款和条件API不同，此端点执行基本的签名捕获，没有显示协议或签名存档。

在底层，签名以专有矢量格式捕获，必须转换为常用光栅格式才能对大多数应用程序有用。至少，您必须使用sigFormat参数指定图像格式。目前支持JPG和PNG。

默认情况下，图像以十六进制编码的二进制格式返回JSON响应中。您可以使用sigFile参数将二进制图像输出重定向到文件。

您还可以通过传递sigWidth参数来调整输出图像的宽度。图像将调整到该宽度，同时保持原始图像的宽高比。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalName' => 'Test Terminal',

    // File format for the signature image.
    'sigFormat' => BlockChyp::SIGNATURE_FORMAT_PNG,

    // Width of the signature image in pixels.
    'sigWidth' => 200,
];


$response = BlockChyp::captureSignature($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

新交易显示

API凭证类型：商家
所需角色：支付API访问

此API将总计和行项目级数据发送到终端。

至少，您应该在显示请求中发送总计信息，包括total、tax和subtotal。

您还可以发送行项目级数据，每个行项目可以具有description、qty、price和extended价格。

如果您未能发送扩展价格，BlockChyp将乘以qty和price。但是，我们强烈建议您预先计算所有字段以确保一致性。例如，您处理浮点数乘法和舍入的方式可能与BlockChyp略有不同。

折扣

您可以选择以单个行项目形式显示折扣，具有负值，或者将折扣与特定行项目关联。您可以应用任何数量的折扣到单个行项目，包括描述和金额。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'transaction' => [
        'subtotal' => '60.00',
        'tax' => '5.00',
        'total' => '65.00',
        'items' => [
            [
                'description' => 'Leki Trekking Poles',
                'price' => '35.00',
                'quantity' => 2,
                'extended' => '70.00',
                'discounts' => [
                    [
                        'description' => 'memberDiscount',
                        'amount' => '10.00',
                    ],
                ],
            ],
        ],
    ],
];


$response = BlockChyp::newTransactionDisplay($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

更新交易显示

API凭证类型：商家
所需角色：支付API访问

与新交易显示类似，此变体允许开发人员更新终端上当前显示的行项目级数据。

此功能旨在处理在扫描项目时更新终端显示的情况。您只需要向终端发送更改的信息，通常意味着新的行项目和更新的总计。

如果终端不在行项目显示模式，并且您调用此端点，则第一次调用将类似于新交易显示调用。

至少，您应该在显示请求中发送总计信息，包括total、tax和subtotal。

您还可以发送行项目级数据，每个行项目可以具有description、qty、price和extended价格。

折扣

您可以选择以单个行项目形式显示折扣，具有负值，或者将折扣与特定行项目关联。您可以应用任何数量的折扣到单个行项目，包括描述和金额。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'transaction' => [
        'subtotal' => '60.00',
        'tax' => '5.00',
        'total' => '65.00',
        'items' => [
            [
                'description' => 'Leki Trekking Poles',
                'price' => '35.00',
                'quantity' => 2,
                'extended' => '70.00',
                'discounts' => [
                    [
                        'description' => 'memberDiscount',
                        'amount' => '10.00',
                    ],
                ],
            ],
        ],
    ],
];


$response = BlockChyp::updateTransactionDisplay($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

显示消息

API凭证类型：商家
所需角色：支付API访问

此API在支付终端上显示消息。

请指定message参数。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'message' => 'Thank you for your business.',
];


$response = BlockChyp::message($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

布尔提示

API凭证类型：商家
所需角色：支付API访问

此API提示客户回答是或否的问题。

您可以使用prompt参数指定问题或提示，响应将返回在response字段中。

这可以用于多种用例，包括启动忠诚度注册工作流程或面向客户的建议式销售提示。

自定义标题

您可以使用yesCaption和noCaption请求参数来覆盖“是”和“否”按钮的标题。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
    'prompt' => 'Would you like to become a member?',
    'yesCaption' => 'Yes',
    'noCaption' => 'No',
];


$response = BlockChyp::booleanPrompt($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

文本提示

API凭证类型：商家
所需角色：支付API访问

此API提示客户输入数字或字母数字数据。

由于PCI规则，当响应可以是任何有效字符串时，不允许使用自由格式提示。原因是恶意开发者（当然不是您）可能会使用文本提示要求客户输入卡号或PIN码。

这意味着您不是提供提示，而是提供promptType。

目前支持以下提示类型：

phone：捕获电话号码。
email：捕获电子邮件地址。
first-name：捕获名。
last-name：捕获姓。
customer-number：捕获客户编号。
rewards-number：捕获奖励编号。

您可以使用promptType参数指定提示，响应将返回在response字段中。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',

    // Type of prompt. Can be 'email', 'phone', 'customer-number', or
    // 'rewards-number'.
    'promptType' => BlockChyp::PROMPT_TYPE_EMAIL,
];


$response = BlockChyp::textPrompt($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

列出终端

API凭证类型：商家 & 合作伙伴
所需角色：终端管理

此API返回与商家账户关联的终端的详细信息。

返回所有终端的状态和资源信息，以及当前在终端上显示的品牌预览图像

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::terminals($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

停用终端

API凭证类型：商家 & 合作伙伴
所需角色：终端管理

此API停用支付终端。

如果终端存在并且目前在线，它将从商家的终端库存中删除。终端将远程清除并工厂重置。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalId' => '<TERMINAL ID>',
];


$response = BlockChyp::deactivateTerminal($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

激活终端

API凭证类型：商家 & 合作伙伴
所需角色：终端管理

此API激活支付终端。

如果成功，支付终端将重新启动，生成新的加密密钥，并下载为添加到其中的商家账户激活的任何品牌资产。

激活请求需要激活代码和唯一的终端名称。所有终端名称必须在商家账户范围内是唯一的。

可选参数

merchantId：对于合作伙伴范围内的API凭证，需要商家ID。对于商家范围内的API凭证，商家ID是隐含的，不能被覆盖。
cloudRelay：以云中继模式激活终端。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalName' => 'Test Terminal',
    'activationCode' => '<ACTIVATION CODE>',
];


$response = BlockChyp::activateTerminal($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

重启终端

API凭证类型：商家
所需角色：支付API访问

此API重启终端。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'terminalName' => 'Test Terminal',
];


$response = BlockChyp::reboot($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

条款和条件端点

开发者可以使用BlockChyp显示和捕获与交易相关的合同或协议的接受。这些协议可以是任何长格式合同，从租赁协议到HIPAA披露。

捕获条款和条件的两种基本方法。商家可以将合同模板存储在BlockChyp中，或者他们可以在每次API调用中将完整协议文本作为一部分发送。正确的方法将主要取决于与BlockChyp集成的系统是否已经具有组织和管理的协议的机制。对于已经内置此功能的系统，可能没有必要使用条款和条件。

当协议在终端上显示时，消费者可以滚动浏览并阅读整个协议，并提供签名。结果作为API响应的一部分返回，但BlockChyp还会存储协议的记录，包括签名图像、时间戳以及同意的协议全文。

使用条款和条件日志API可以用于搜索和检索接受记录。如果原始API请求中提供了交易ID，则这些记录还可以与交易相关联。

条款和条件捕获

API凭证类型：商家
所需角色：条款和条件管理

此API允许您在终端上提示客户接受法律协议，并且（通常）捕获他们的签名。

协议内容可以通过两种方式指定。您可以使用之前配置的T&C模板，或者在每次请求中传递完整的协议文本。

使用模板

如果您的应用程序不跟踪协议，您可以利用BlockChyp的模板系统。您可以在商户仪表板中创建任意数量的T&C模板，并通过传递tcAlias标志来指定应该显示哪个模板。

原始内容

如果您的系统跟踪协议语言或执行复杂的合并和渲染逻辑，您可以绕过我们的模板系统，并在每次交易中传递完整的文本。使用tcName传递协议名称，使用tcContent传递合同文本。请注意，只支持纯文本。

绕过签名

默认情况下会捕获签名图像。如果出于某种原因这不适合您的用例，并且您想在不实际捕获签名图像的情况下捕获接受，请将请求中的disableSignature标志设置为。

条款和条件日志

每次用户在终端上接受协议时，签名图像（如果捕获），将被上传到网关。图像也将添加到日志中，以及协议的完整文本。这保留了历史记录，以防标准协议或模板随着时间的推移而更改。

将协议与交易关联

要将条款和条件日志条目与交易关联，只需传递关联交易的交易ID或交易引用。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',

    // Alias for a Terms and Conditions template configured in the BlockChyp
    // dashboard.
    'tcAlias' => 'hippa',

    // Name of the contract or document if not using an alias.
    'tcName' => 'HIPPA Disclosure',

    // Full text of the contract or disclosure if not using an alias.
    'tcContent' => 'Full contract text',

    // File format for the signature image.
    'sigFormat' => BlockChyp::SIGNATURE_FORMAT_PNG,

    // Width of the signature image in pixels.
    'sigWidth' => 200,

    // Whether or not a signature is required. Defaults to true.
    'sigRequired' => true,
];


$response = BlockChyp::termsAndConditions($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

列出模板

API凭证类型：商家
所需角色：条款和条件管理

此API返回与商户账户关联的所有条款和条件模板。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::tcTemplates($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

获取模板

API凭证类型：商家
所需角色：条款和条件管理

此API返回单个条款和条件模板。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'templateId' => '<TEMPLATE ID>',
];


$response = BlockChyp::tcTemplate($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

更新模板

API凭证类型：商家
所需角色：条款和条件管理

此API更新或创建条款和条件模板。

条款和条件模板相对简单，基本上由名称、内容和别名组成。

名称是将在屏幕顶部显示的标题。别名是用于后续API调用中引用模板的代码或简短描述。

内容是合同或协议的完整文本。目前不支持特殊格式化或合并行为。只支持纯文本。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'alias' => 'HIPPA',
    'name' => 'HIPPA Disclosure',
    'content' => 'Lorem ipsum dolor sit amet.',
];


$response = BlockChyp::tcUpdateTemplate($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

删除模板

API凭证类型：商家
所需角色：条款和条件管理

此API删除条款和条件模板。

如果删除模板，其别名可以被重用，并且从要删除的模板生成的任何以前的条款和条件日志条目都将得到完全保留，因为日志条目始终包括协议文本的完整独立副本。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'templateId' => '<TEMPLATE ID>',
];


$response = BlockChyp::tcDeleteTemplate($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

条款和条件日志

API凭证类型：商家
所需角色：条款和条件管理

此API允许开发人员搜索和排序条款和条件日志条目。

默认API调用（无参数）将按降序返回最后250条日志条目。

可以使用可选参数来过滤和查询数据集。

transactionId：如果提供，则仅返回与特定交易关联的日志条目。如果使用此参数，则忽略分页和日期过滤器。
maxResults：单页中返回的最大结果数。默认值为250，最大值为250。
startIndex：要返回的结果集内结果的零起始索引。用于前进页面。例如，如果页面大小为10，并且您希望返回第二页的结果，则发送startIndex为10。
startDate：结果的可选开始日期，提供为ISO 8601时间戳。（例如：2022-05-24T13:51:38+00:00）
endDate：结果提供的可选截止日期，以ISO 8601时间戳格式。例如：2022-05-24T13:51:38+00:00

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'logEntryId' => '<LOG ENTRY ID>',
];


$response = BlockChyp::tcLog($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

条款和条件详情

API凭证类型：商家
所需角色：条款和条件管理

此API返回单个条款和条件日志条目的详细信息。要返回的记录的 logEntryId 是唯一必需的参数。

签名图像以Base 64编码的二进制格式返回，图像格式由 sigFormat 字段指定。默认格式为PNG。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'logEntryId' => '<ENTRY ID>',
];


$response = BlockChyp::tcEntry($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

令牌管理

BlockChyp通过使用令牌支持保存的支付和定期支付。令牌可以通过Enroll API或网页令牌生成器创建。一旦创建，这些令牌就可以用于后续的支付或与客户记录相关联作为保存的支付方式。

默认情况下，令牌限制在一个商家，但通过BlockChyp的特殊安排，可以跨组织共享，适用于多地点商家。请联系您的BlockChyp代表设置令牌共享。

注册

API凭证类型：商家
所需角色：支付API访问

此API允许您在令牌保险库中对支付方式进行令牌化和注册。您还可以传递客户信息，并将支付方式与客户记录相关联。

响应中将返回一个令牌，可用于后续的收费、预授权和退款交易。

礼品卡和EBT

礼品卡和EBT卡不能进行令牌化。

电子商务令牌

Enroll API和电子商务网页令牌生成器返回的令牌是相同的，可以互换使用。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
    'terminalName' => 'Test Terminal',
];


$response = BlockChyp::enroll($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

令牌元数据

API凭证类型：商家
所需角色：支付API访问

此API检索有关令牌的状态和元数据信息，包括任何与客户记录的链接。

此操作还将返回与令牌背后的卡片相关的任何客户记录。如果基础卡片已被令牌化多次，将返回与卡片相关的所有客户，即使这些客户关联与其他令牌有关。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'token' => '<TOKEN>',
];


$response = BlockChyp::tokenMetadata($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

链接令牌

API凭证类型：商家
所需角色：支付API访问

此API将支付令牌与客户记录相关联。通常，这只需要撤销之前的解链操作。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'token' => '<TOKEN>',
    'customerId' => '<CUSTOMER ID>',
];


$response = BlockChyp::linkToken($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

解链令牌

API凭证类型：商家
所需角色：支付API访问

此API从客户记录中删除支付令牌链接。

这将删除客户记录与同一基础卡片的令牌之间的所有链接。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'token' => '<TOKEN>',
    'customerId' => '<CUSTOMER ID>',
];


$response = BlockChyp::unlinkToken($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

删除令牌

API凭证类型：商家
所需角色：支付API访问

此API从网关中删除支付令牌。如果令牌一年内未使用，则会自动删除。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'token' => '<TOKEN>',
];


$response = BlockChyp::deleteToken($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

客户端点

这些API允许开发者在BlockChyp中创建和管理客户记录。希望使用BlockChyp进行令牌化定期支付的开发商，如果他们有自己的客户管理系统，可以直接使用令牌。但是，BlockChyp提供额外的工具来管理客户和跟踪客户的保存支付令牌。

此外，如果使用客户功能，BlockChyp可以检测与现有客户关联的支付方式，并在支付交易中返回客户数据。这可以作为一种被动的方法来检测回头客。

更新客户

API凭证类型：商家
所需角色：支付API访问

此API添加或更新客户记录。

如果您传递了包括 firstName、lastName、email 或 sms 在内的客户信息，但没有任何客户ID或客户引用，则会创建一个新的记录。

如果您传递了 customerRef 和 customerId，如果存在，则会更新客户记录。

客户引用

customerRef 字段是可选的，但强烈推荐使用，因为这允许您使用自己的客户标识符，而不是在系统中存储BlockChyp的客户ID。

使用支付交易创建客户记录

如果在执行支付交易时您有客户信息，您可以将所有相同的客户信息直接传递到支付交易中。BlockChyp将在捕获支付的同时创建客户记录。这种方法的优点是，客户的支付卡可以自动与客户记录相关联，只需一步即可。如果客户将来使用该支付卡，客户数据将自动返回。您无需要求客户提供任何额外信息。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'customer' => [
        'id' => '<CUSTOMER ID>',
        'customerRef' => 'Customer reference string',
        'firstName' => 'FirstName',
        'lastName' => 'LastName',
        'companyName' => 'Company Name',
        'emailAddress' => 'notifications@blockchypteam.m8r.co',
        'smsNumber' => '(123) 123-1231',
    ],
];


$response = BlockChyp::updateCustomer($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

检索客户

API凭证类型：商家
所需角色：支付API访问

使用此API，您可以检索有关客户记录的详细信息，包括（如有）保存的支付方式。

客户可以通过customerId或customerRef进行查找。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'customerId' => '<CUSTOMER ID>',
];


$response = BlockChyp::customer($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

搜索客户

API凭证类型：商家
所需角色：支付API访问

此API搜索客户数据库并返回匹配的结果。

使用query传递搜索字符串，系统将返回所有姓名中包含查询字符串的结果。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'query' => '(123) 123-1234',
];


$response = BlockChyp::customerSearch($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

删除客户

API凭证类型：商家
所需角色：支付API访问

此API删除客户记录。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'customerId' => '<CUSTOMER ID>',
];


$response = BlockChyp::deleteCustomer($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

调查参考

这些API用于处理交易后调查和调查数据。

商家可以配置可伸缩的（1-5）或是/否问题，这些问题可以在每笔批准的Charge和Preauth交易后向消费者展示。调查无需任何自定义编程，商家可以简单地配置它们，无需销售点系统进行任何额外定制。

然而，这些API允许销售点或第三方系统开发人员将调查问题配置或结果可视化集成到自己的系统中。

列出问题

API凭证类型：商家
所需角色：调查管理

此API按终端上展示的顺序返回所有调查问题。

所有问题都会返回，无论是否启用。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::surveyQuestions($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

问题详情

API凭证类型：商家
所需角色：调查管理

此API返回一个带有响应数据的单个调查问题。questionId是必需的。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'questionId' => '<QUESTION ID>',
];


$response = BlockChyp::surveyQuestion($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

更新问题

API凭证类型：商家
所需角色：调查管理

此API更新或创建调查问题。questionText和questionType是必需字段。以下值对questionType有效。

yes_no：用于简单的是/否问题。
scaled：显示带有按钮的问题，允许客户使用从1到5的值进行响应。

问题默认禁用。传递enabled以启用问题。

使用ordinal字段控制多个问题启用时的顺序。我们建议保持问题的数量最少。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'id' => '<QUESTION ID>',
    'ordinal' => 1,
    'questionText' => 'Would you shop here again?',
    'questionType' => 'yes_no',
    'enabled' => true,
];


$response = BlockChyp::updateSurveyQuestion($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

删除问题

API凭证类型：商家
所需角色：调查管理

此API删除调查问题。questionId是必需参数。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'questionId' => '<QUESTION ID>',
];


$response = BlockChyp::deleteSurveyQuestion($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

调查结果

API凭证类型：商家
所需角色：调查管理

此API返回单个问题的调查结果。

返回的结果包括响应率，即消费者提供答案的交易后的百分比。

返回的responses数组按答案分解结果，提供响应总数、答案占总数的百分比以及与特定答案关联的平均交易金额。

默认情况下，返回基于所有响应的所有结果。但是，开发人员可以提供可选的startDate和endDate参数，以仅返回在特定日期范围内提供的响应。

startDate和endDate可以以MM/DD/YYYY或YYYY-MM-DD格式提供。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'questionId' => '<QUESTION ID>',
];


$response = BlockChyp::surveyResults($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

媒体和品牌控制

BlockChyp拥有一个复杂的终端媒体和品牌控制平台。当终端空闲时，终端可以配置为显示标志、图像、视频和幻灯片。如果需要，可以在合作伙伴、组织和商家级别配置品牌资产，以细粒度的小时为单位的计划。

从概念上讲，所有品牌和媒体都从媒体库开始。商家、合作伙伴和组织可以上传图像或视频，并从上传的媒体构建品牌资产。

幻灯片可以结合媒体库中的图像，形成一个重复的定时图像循环。

品牌资产可以用来结合媒体或幻灯片，并按照优先级和时序规则创建我们所说的终端品牌堆栈。

我们将一组品牌资产称为“终端品牌堆栈”，因为存在关于哪些品牌资产具有优先级的隐含规则。例如，未配置任何品牌资产的商家将继承其可能属于的任何组织的品牌规则。如果商家不属于任何组织或组织未配置品牌规则，则系统将退回由拥有商家的销售点或软件合作伙伴设定的品牌默认值。

此功能使合作伙伴和组织（多店运营商和大型全国连锁店）能够从单个界面配置可能成千上万的终端的品牌。

终端品牌也可以在单个终端级别进行配置，商家的终端车队可以被分成组，并在组级别配置品牌。在终端级别配置的品牌将始终覆盖更高级别组的品牌。

终端品牌堆栈的优先级顺序如下。

终端
终端组
商家
组织（地区、连锁店等）
合作伙伴
BlockChyp 默认标志

媒体库

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此API返回与API凭证（商家、合作伙伴或组织）关联的整个媒体库。媒体库结果将包括用于在幻灯片和品牌资产中引用媒体资产的ID、完整的文件URL和缩略图。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::media($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

上传媒体

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此API支持媒体库上传。此API的操作根据SDK平台略有不同。在所有情况下，目的是允许使用可能最低级的I/O原语将文件的二进制数据传递到SDK，以支持开发人员不处理实际文件的情况。使用缓冲区、原始字节或流可能更方便。

例如，Go实现接受一个io.Reader，Java实现接受一个java.io.InputStream。CLI通过-file命令行参数接受字面文件URL。

以下文件格式被接受为有效的上传

.png
.jpg
.jpeg
.gif
.mov
.mpg
.mp4
.mpeg

UploadMetadata对象允许开发者传递有关上传的额外元数据，包括fileName、fileSize和uploadId。

这些值都不是必需的，但提供它们可以解锁一些与媒体上传相关的附加功能。fileName将用于记录媒体库中的原始文件名。fileSize和uploadId用于支持上传状态跟踪，这对于大型视频文件上传尤其有用。

fileSize应该是文件的字节数。

uploadId值可以是任何随机字符串。这是您将用于通过上传状态API检查上传状态的值。此API将返回用于在上传上提供进度反馈和返回视频转码信息所需的信息。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'fileName' => 'aviato.png',
    'fileSize' => 18843,
    'uploadId' => '<RANDOM ID>',
];


$file = file_get_contents('aviato.png');
$response = BlockChyp::uploadMedia($request, $file);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

上传状态

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此API返回正在进行的或最近完成的上传的状态和进度信息。

在调用此API之前，开发人员必须首先使用fileSize和uploadId参数启动文件上传。

返回的数据结构将包括文件大小、上传的字节数、描述性状态以及指示上传是否完成或上传后处理是否正在进行的状态标志。
如果上传完成，将返回分配给媒体资产的ID以及缩略图链接。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'uploadId' => '<UPLOAD ID>',
];


$response = BlockChyp::uploadStatus($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

获取媒体资产

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此API返回详细的媒体资产。返回的数据包括与完整媒体库端点返回的完全相同的媒体信息，包括指向原始媒体文件和缩略图的完全限定URL。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'mediaId' => '<MEDIA ASSET ID>',
];


$response = BlockChyp::mediaAsset($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

删除媒体资产

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此API删除媒体资产。注意，如果媒体资产在幻灯片或终端品牌堆栈中使用，则无法删除。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'mediaId' => '<MEDIA ASSET ID>',
];


$response = BlockChyp::deleteMediaAsset($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

列出幻灯片

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此API返回所有幻灯片。

请注意，此API不返回幻灯片级别的数据。使用获取幻灯片API以获取幻灯片级别详细信息。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::slideShows($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

获取幻灯片

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此API返回单个幻灯片。返回的幻灯片级别详细信息包括每个幻灯片的完全限定缩略图URL。

slideShowId是唯一必需的参数。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'slideShowId' => '<SLIDE SHOW ID>',
];


$response = BlockChyp::slideShow($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

更新幻灯片

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此API更新或创建幻灯片。必需参数包括name、delay和slides。

幻灯片属性是一个幻灯片数组。幻灯片数据结构包含顺序和缩略图URL字段，但在更新或创建幻灯片时这些字段不是必需的。更新或创建幻灯片时，仅必需mediaId字段。

在使用CLI时，可以通过-mediaId参数发送逗号分隔的媒体ID列表来指定幻灯片。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'name' => 'Test Slide Show',
    'delay' => 5,
    'slides' => [
        [
            'mediaId' => '<MEDIA ID>',
        ],
    ],
];


$response = BlockChyp::updateSlideShow($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

删除幻灯片

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此API删除幻灯片，slideShowId是唯一必需的参数。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'slideShowId' => '<SLIDE SHOW ID>',
];


$response = BlockChyp::deleteSlideShow($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

终端品牌

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此API按优先级顺序返回给定API作用域的完整品牌堆栈。

此API的消费者应特别注意editable字段。此字段表示品牌资产是否从特定API凭证作用域的角度为只读。

可以使用thumbnail和previewImage属性来支持构建管理品牌堆栈的用户界面。previewImage与thumbnail不同，因为预览图像旨在显示资产在终端上实际显示时的外观。

activeAsset返回当前在终端上可见的资产。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::terminalBranding($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

更新品牌资产

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此API更新或创建单个品牌资产。

品牌资产代表终端品牌堆栈的单个元素。品牌资产可以是视频或图像，在这种情况下，必须提供引用媒体库中资产的mediaId。品牌资产也可以是幻灯片，在这种情况下，必须提供slideShowId。品牌资产必须具有有效的mediaId或有效的slideShowId。可以使用可选的notes字段提供对品牌资产的简短注释和描述。

可见性标志

为了使品牌资产在终端上可见，必须将enabled标志设置为true，并将preview关闭。preview的目的是在不将其推送到实际终端的情况下显示建议的品牌资产的行为。BlockChyp商家门户中的发布按钮有效地关闭了preview设置。

顺序和排序

使用ordinal字段来指定品牌资产的优先级。具有更高ordinal值的资产将被优先考虑。

填充图像

对于普通图像，有时在图像上添加边距很有帮助。这对于徽标或任何没有在图像内容与图像文件边缘之间添加任何空白或边距的图像文件尤其有帮助。如果希望在终端上显示图像时BlockChyp自动应用边距，请将padded标志设置为true。

计划

默认情况下，放置在品牌层顶部的品牌资产，如果它处于启用状态且不在预览模式下，将全天候立即在终端显示。

品牌资产可以安排具有有效的开始和结束日期，以用于季节性活动。这些资产也可以安排在一天中的特定时间和一周中的特定日子。

startDate: 可选日期，在此日期之后，品牌资产有资格显示。可以是 MM/DD/YYYY 或 YYYY-MM-DD 格式。
endDate: 可选日期，在此日期之前，品牌资产有资格显示。可以是 MM/DD/YYYY 或 YYYY-MM-DD 格式。
startTime 可选时间，在此时间之后，品牌资产有资格显示。必须是 24 小时制时间：HH:MM。
endTime 可选时间，在此时间之前，品牌资产有资格显示。必须是 24 小时制格式：HH:MM。
daysOfWeek 对于只在某些星期几显示的品牌资产，此字段是星期几常数的数组。（常量因 SDK 平台而异。）

只读字段

品牌资产数据结构包含一些只读字段，当检索品牌资产时返回。但当你尝试将它们作为更新的一部分发送时，这些字段将被忽略。这些是从或计算得出的字段，有助于在管理用户界面中显示品牌资产，但不能通过 API 调用来更改。

这些字段包括

ownerId
merchantId
organizationId
partnerId
userId
userName
thumbnail
lastModified
editable
assetType
ownerType
ownerTypeCaption
previewImage
narrativeEffectiveDates
narrativeDisplayPeriod

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'mediaId' => '<MEDIA ID>',
    'padded' => true,
    'ordinal' => 10,
    'startDate' => '01/06/2021',
    'startTime' => '14:00',
    'endDate' => '11/05/2024',
    'endTime' => '16:00',
    'notes' => 'Test Branding Asset',
    'preview' => false,
    'enabled' => true,
];


$response = BlockChyp::updateBrandingAsset($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

删除品牌资产

API凭证类型：商家、合作伙伴和组织
所需角色：媒体管理

此 API 从品牌层中删除品牌资产。

请注意，删除品牌资产不会从媒体库或幻灯片库中删除底层媒体或幻灯片。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'assetId' => '<BRANDING ASSET ID>',
];


$response = BlockChyp::deleteBrandingAsset($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

商户管理

这些 API 允许合作伙伴管理和配置他们的商户组合。

使用这些 API（除商户概要文件 API 之外）需要具有特殊角色和权限的合作伙伴范围 API 凭证，这些权限可能需要与 BlockChyp 进行特殊安排。

例如，合作伙伴通常不能直接登机，而必须使用标准承保流程通过优惠代码和邀请来登机。

商户概要文件

API凭证类型：商家
所需角色：支付API访问

API 返回有关商户配置的详细元数据，包括基本身份信息、终端设置、门店和转发设置，以及支持分账的商户的银行账户信息。

其中一些字段可以通过更新商户 API 进行更新，但许多字段由承保控制，不能在承保和风险流程之外更改。

商户描述性字段

以下字段是基本描述性字段，可用于描述和识别商户。

companyName: 商户的官方企业实体名称。
dbaName: 业务 DBA（doing business as）名称。
contactName: 商户主要控制联系人的姓名。
contactNumber: 主要控制联系人的电话号码。
locationName: 可选位置名称，用于多地点运营商。
storeNumber: 可选门店编号，用于多地点运营商。
partnerRef: 合作伙伴可以添加到商户记录的可选参考编号。通常是合作伙伴对商户的标识符。
timeZone: 商户的 Unix 风格本地时区。例如：America/New_York。
publicKey: 只读字段。商户的区块链公钥。在创建商户账户时生成和分配。
billingAddress: 账单和书面通信的地址。
shippingAddress: 物理发货地址。通常是企业的实际街道地址。
status: 商户账户的当前状态。
tcDisabled: 禁用商户仪表板中所有条款和条件功能。用于隐藏该功能，如果合作伙伴未选择支持它。
gatewayOnly: 指示商户已以网关仅模式上线。不常见。

批量设置和终端设置

以下字段用于控制批量关闭和高级终端配置。

batchCloseTime: 批量自动关闭的24小时HH:MM格式时间，时间为商户的本地时间。默认为凌晨3点。
autoBatchClose: 标记决定是否自动关闭批量。默认为true。
disableBatchEmails: 标记可以选择关闭自动批量关闭通知电子邮件。
cooldownTimeout: 交易响应在终端上显示后的秒数。冷却期过后，终端将返回空闲状态并显示当前活动的终端品牌。
surveyTimeout: 在终端上显示调查问题前的秒数，之后将返回到空闲屏幕。
pinEnabled: 启用借记卡、EBT卡和具有PIN CVM的EMV卡的PIN码输入。如果终端未注入正确的加密密钥，则会被忽略。
pinBypassEnabled: 启用借记交易的PIN码绕过。
cashBackEnabled: 启用借记交易的现金返还。
cashbackPresets: 当启用现金返还时，用于现金返还金额的四个默认值的数组。
storeAndForwardEnabled: 启用网络中断时的自动存储和转发。存储和转发不支持现金返还、退款、EBT或礼品卡交易。
storeAndForwardFloorLimit: 存储和转发交易的最大美元价值。
ebtEnabled: 在BlockChyp终端上启用EBT（SNAP）。
tipEnabled: 在终端上启用小费输入。
promptForTip: 如果为true，则终端将始终提示输入小费，即使API调用没有请求小费提示。
tipDefaults: 用于计算默认小费金额的三个百分比的数组。
giftCardsDisabled: 禁用BlockChyp礼品卡。通常只在商户使用替代礼品卡系统时使用。
digitalSignaturesEnabled: 启用磁条卡和具有签名CVM的EMV卡的电子签名捕获。
digitalSignatureReversal: 如果消费者拒绝提供签名，则将导致交易自动撤销。
manualEntryEnabled: 启用手动卡输入。
manualEntryPromptZip: 对于手动卡输入，需要基于邮编进行地址验证。
manualEntryPromptStreetNumber: 对于手动卡输入，需要基于街道/地址进行验证。

卡品牌和交易设置

freeRangeRefundsEnabled: 启用不引用先前交易的直接退款。
partialAuthEnabled: 指示已启用部分授权（通常用于礼品卡支持）。
splitBankAccountsEnabled: 仅用于律师事务所商户。
contactlessEmv: 在终端上启用非接触式/触控交易。默认为true。
visa: 启用Visa交易。
masterCard: 启用MasterCard交易。
amex: 启用American Express交易。
discover: 启用Discover交易。
jcb: 启用JCB（日本卡局）交易。
unionPay: 启用中国银联交易。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::merchantProfile($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

获取商户

API凭证类型: 合作伙伴 & 组织
必需角色: 商户管理

这是一个合作伙伴或组织级别的API，可用于返回商户投资组合。

默认返回实时商家。使用 test 标志仅返回测试商家。返回的结果包括详细的设置，包括承保控制标志。

默认返回最多 250 家商家。对于大型商家组合，可以使用 maxResults 和 startIndex 字段来减少页面大小并浏览多页结果。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'test' => true,
];


$response = BlockChyp::getMerchants($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

更新商家

API凭证类型：商家、合作伙伴和组织
必需角色: 商户管理

此 API 可用于更新或创建商家账户。

可以使用商家范围 API 凭据来更新商家账户设置。

可以使用合作伙伴范围 API 凭据来更新商家、创建新的测试商家或加入新的网关商家。

商户描述性字段

以下字段是基本描述性字段，可用于描述和识别商户。

companyName: 商户的官方企业实体名称。
dbaName: 商业的 DBA（作为）名称。
contactName: 商户主要控制联系人的姓名。
contactNumber: 主要控制联系人的电话号码。
locationName: 多地点操作员的可选位置名称。
storeNumber: 多地点操作员的可选商店编号。
partnerRef: 合作伙伴可以添加到商户记录的可选参考编号。通常是合作伙伴对商户的标识符。
timeZone: 商户的 Unix 风格本地时区。例如：America/New_York。
publicKey: 只读字段。商户的区块链公钥。在创建商户账户时生成和分配。
billingAddress: 账单和书面通信的地址。
shippingAddress: 物理发货地址。通常是企业的实际街道地址。
status: 商户账户的当前状态。
tcDisabled: 禁用商户仪表板中所有条款和条件功能。用于隐藏该功能，如果合作伙伴未选择支持它。
gatewayOnly: 指示商户已以网关仅模式上线。不常见。

批量设置和终端设置

以下字段用于控制批量关闭和高级终端配置。

batchCloseTime: 批量自动关闭的24小时HH:MM格式时间，时间为商户的本地时间。默认为凌晨3点。
autoBatchClose: 标记决定是否自动关闭批量。默认为true。
disableBatchEmails: 标记可以选择关闭自动批量关闭通知电子邮件。
cooldownTimeout: 交易响应在终端上显示后的秒数。冷却期过后，终端将返回空闲状态并显示当前活动的终端品牌。
surveyTimeout: 在终端上显示调查问题前的秒数，之后将返回到空闲屏幕。
pinEnabled: 启用借记卡、EBT卡和具有PIN CVM的EMV卡的PIN码输入。如果终端未注入正确的加密密钥，则会被忽略。
pinBypassEnabled: 启用借记交易的PIN码绕过。
cashBackEnabled: 启用借记交易的现金返还。
cashbackPresets: 当启用现金返还时，用于现金返还金额的四个默认值的数组。
storeAndForwardEnabled: 启用网络中断时的自动存储和转发。存储和转发不支持现金返还、退款、EBT或礼品卡交易。
storeAndForwardFloorLimit: 存储和转发交易的最大美元价值。
ebtEnabled: 在BlockChyp终端上启用EBT（SNAP）。
tipEnabled: 在终端上启用小费输入。
promptForTip: 如果为true，则终端将始终提示输入小费，即使API调用没有请求小费提示。
tipDefaults: 用于计算默认小费金额的三个百分比的数组。
giftCardsDisabled: 禁用BlockChyp礼品卡。通常只在商户使用替代礼品卡系统时使用。
digitalSignaturesEnabled: 启用磁条卡和具有签名CVM的EMV卡的电子签名捕获。
digitalSignatureReversal: 如果消费者拒绝提供签名，则将导致交易自动撤销。
manualEntryEnabled: 启用手动卡输入。
manualEntryPromptZip: 对于手动卡输入，需要基于邮编进行地址验证。
manualEntryPromptStreetNumber: 对于手动卡输入，需要基于街道/地址进行验证。

卡品牌和交易设置

freeRangeRefundsEnabled: 启用不引用先前交易的直接退款。
partialAuthEnabled: 指示已启用部分授权（通常用于礼品卡支持）。
splitBankAccountsEnabled: 仅用于律师事务所商户。
contactlessEmv: 在终端上启用非接触式/触控交易。默认为true。
visa: 启用Visa交易。
masterCard: 启用MasterCard交易。
amex: 启用American Express交易。
discover: 启用Discover交易。
jcb: 启用JCB（日本卡局）交易。
unionPay: 启用中国银联交易。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'merchantId' => '<MERCHANT ID>',
    'test' => true,
    'dbaName' => 'Test Merchant',
    'companyName' => 'Test Merchant',
    'billingAddress' => [
        'address1' => '1060 West Addison',
        'city' => 'Chicago',
        'stateOrProvince' => 'IL',
        'postalCode' => '60613',
    ],
];


$response = BlockChyp::updateMerchant($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

商家用户

API凭证类型: 合作伙伴 & 组织
必需角色: 商户管理

此 API 返回与商家账户相关联的所有用户和挂起的邀请，包括任何分配的角色代码。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'merchantId' => '<MERCHANT ID>',
];


$response = BlockChyp::merchantUsers($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

邀请商家用户

API凭证类型: 合作伙伴 & 组织
必需角色: 商户管理

邀请新用户加入商家账户。必须提供 email、firstName 和 lastName。

用户将收到一封邀请电子邮件，其中包含创建 BlockChyp 账户并将其链接到商家账户的步骤。如果用户已经拥有 BlockChyp 用户账户，则将跳过新用户注册，并将现有用户账户链接到商家账户。

开发者可以选择通过发送一个或多个角色代码来限制用户的访问级别。否则，用户将被赋予默认的商家用户角色。（STDMERCHANT）

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'email' => 'Email address for the invite',
];


$response = BlockChyp::inviteMerchantUser($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

添加测试商家

API 凭证类型：合作伙伴
必需角色: 商户管理

这是一个合作伙伴级别的 API，可用于创建测试商家账户。这创建了一个具有默认设置的测试商家。

可以通过使用更新商家 API 来更改设置。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'dbaName' => 'DBA Name',
    'companyName' => 'Corporate Entity Name',
];


$response = BlockChyp::addTestMerchant($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

删除测试商家

API 凭证类型：合作伙伴
必需角色: 商户管理

此合作伙伴 API 可用于删除未使用的测试商家账户。必须提供 merchantId 参数。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
    'merchantId' => '<MERCHANT ID>',
];


$response = BlockChyp::deleteTestMerchant($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

合作伙伴实用工具

这些仅限合作伙伴的 API 为 ISV 合作伙伴提供高级报告和管理其组合的工具。

以下大部分 API 都用于组合报告，从基本的合作伙伴佣金报表到包含所有底层卡品牌数据的个人报表。

我们还提供定价策略 API，允许合作伙伴获取其组合中任何商家的当前有效定价规则。

货币数据

所有合作伙伴 API 以两种格式返回货币和百分比值：浮点数和格式化字符串。

建议所有开发人员使用格式化字符串，因为这将确保最精确的值。浮点数通常不适用于货币或定点小数，因为底层的二进制编码可能导致精度错误。我们仅提供浮点值，作为开发人员节省开发时间的便利，并且可以在他们的用例中接受近似值。

检索定价策略

API 凭证类型：合作伙伴
所需角色：合作伙伴 API 访问

此 API 返回商家的当前定价策略。此 API 对合作伙伴范围 API 凭证有效，且必须提供 merchantId 参数。默认情况下，此 API 返回商家当前有效的定价策略，但可以通过提供 id 参数返回其他不活动的策略。

始终返回互换加和固定费率定价的买入汇率，但实际用于费用计算的仅是定价模型类型（固定费率或互换加）相关的定价。

每个定价级别返回三个值：buyRate、current 和 limit。商家实际支付的金额在 current 字段中给出。其他值反映了合作伙伴在更改价格时可以使用的合同最低值（buyRate）和最高值（limit）范围。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::pricingPolicy($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

合作伙伴报表

API 凭证类型：合作伙伴
所需角色：合作伙伴 API 访问

API返回合作伙伴剩余账单列表。默认情况下，所有账单按最新账单排列返回。可选日期参数（startDate和endDate）可以过滤账单到特定日期范围。

账单列表返回关于账单的基本信息，如交易量、交易次数和赚取的佣金。

使用每个账单摘要返回的id，通过合作伙伴账单详情API来获取详细信息。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::partnerStatements($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

合作伙伴账单详情

API 凭证类型：合作伙伴
所需角色：合作伙伴 API 访问

API返回关于特定合作伙伴账单的详细信息。除了每项底层商户账单的明细数据外，还返回汇总数据。

使用商户账单详情API和合作伙伴佣金细分API，用商户发票id分别获取商户账单和卡品牌费用细分。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::partnerStatementDetail($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

商户发票

API凭证类型：合作伙伴或商户
所需角色：合作伙伴API访问或商户API

API返回商户账单和发票列表。默认情况下，所有发票按最新账单排列返回。可选日期参数（startDate和endDate）可以用于按日期范围过滤账单。

invoiceType参数也可以用于按类型过滤发票。发票可以是常规发票，例如在订购终端或礼品卡时生成的发票，也可以是商户账单。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::merchantInvoices($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

商户发票详情

API 凭证类型：合作伙伴
所需角色：合作伙伴 API 访问

API返回关于特定商户账单或发票的详细信息。

所有明细项都按地形排序的树形结构返回，模拟发票的嵌套明细项结构。返回发票上任何已发布的付款的详细信息。

如果发票是商户账单，则也返回账单期间发生的每个商户存款的详细信息。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::merchantInvoiceDetail($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

合作伙伴佣金细分

API 凭证类型：合作伙伴
所需角色：合作伙伴 API 访问

此API允许合作伙伴获取用于计算特定商户账单的合作伙伴佣金的底层数据。

statementId是必需的，必须是类型为statement的有效商户发票的id。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::partnerCommissionBreakdown($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

商户凭证生成

API 凭证类型：合作伙伴
所需角色：合作伙伴 API 访问

此API允许合作伙伴为商户生成API凭证。

merchantId是必需的，必须是有效商户的id。

默认情况下，凭证不受删除保护。传入deleteProtected以启用删除保护。

可选的notes字段将填充凭证中的注释。

默认情况下，除非在roles字段中传递有效的逗号分隔的角色代码，否则不会分配任何角色。

<?php

// For composer based systems
require_once('vendor/autoload.php');

// For manual installation
#require_once('/path/to/blockchyp/init.php');

use BlockChyp\BlockChyp;

BlockChyp::setApiKey(getenv('BC_API_KEY'));
BlockChyp::setBearerToken(getenv('BC_BEARER_TOKEN'));
BlockChyp::setSigningKey(getenv('BC_SIGNING_KEY'));

// Populate request values
$request = [
];


$response = BlockChyp::merchantCredentialGeneration($request);


// View the result
echo 'Response: ' . print_r($response, true) . PHP_EOL;

运行集成测试

如果您想运行集成测试，请在系统上创建一个名为sdk-itest-config.json的新文件，其中包含您将要使用的API凭证，如下例所示。

{
 "gatewayHost": "https://api.blockchyp.com",
 "testGatewayHost": "https://test.blockchyp.com",
 "apiKey": "PZZNEFK7HFULCB3HTLA7HRQDJU",
 "bearerToken": "QUJCHIKNXOMSPGQ4QLT2UJX5DI",
 "signingKey": "f88a72d8bc0965f193abc7006bbffa240663c10e4d1dc3ba2f81e0ca10d359f5"
}

此文件可以位于几个不同的位置，但通常位于<USER_HOME>/.config/blockchyp/sdk-itest-config.json。所有BlockChyp SDK都使用相同的配置文件。

要使用make运行集成测试套件，请键入以下命令

make integration

通过Composer运行集成测试

如果您想绕过make并直接运行集成测试套件，请使用以下命令

BC_TEST_DELAY=5 ./vendor/bin/phpunit --bootstrap vendor/autoload.php tests/itests

您可以通过将测试名称添加到上一个命令来运行单个测试。以下示例运行TerminalChargeTest

./vendor/bin/phpunit --bootstrap vendor/autoload.php tests/itests/TerminalChargeTest

贡献

BlockChyp欢迎开源社区的贡献，但请注意，此存储库是由我们的内部SDK生成器工具生成的。如果我们选择接受PR或贡献，您的代码将被移动到我们的SDK生成器项目，这是一个私有仓库。

许可协议

根据MIT许可协议分发，blockchyp-php是免费和开源软件。

其他SDK

BlockChyp已正式支持八种不同开发平台的SDK，并持续增加。以下是完整的列表，包括其GitHub仓库链接。

Go SDK

Node.js/JavaScript SDK

iOS (Objective-C/Swift) SDK

Rust SDK

blockchyp / blockchyp-php

维护者

详细信息

README

安装

面向公众的网页

简单示例

其他文档

获取开发套件

交易代码示例

支付端点

Charge

预先授权

捕获预授权

退款

取消授权

超时撤销

礼品卡激活

余额

关闭批次

发送支付链接

重新发送支付链接

取消支付链接

支付链接状态

交易状态

现金折扣

批量历史记录

批次详情

交易历史

列出排队交易

删除排队交易

终端管理端点

终端Ping

终端定位

终端清除

终端状态

捕获签名

新交易显示

更新交易显示

显示消息

布尔提示

文本提示

列出终端

停用终端

激活终端

重启终端

条款和条件端点

条款和条件捕获

列出模板

获取模板

更新模板

删除模板

条款和条件日志

条款和条件详情

令牌管理

注册

令牌元数据

链接令牌

解链令牌

删除令牌

客户端点

更新客户

检索客户

搜索客户

删除客户

调查参考

列出问题

问题详情

更新问题

删除问题

调查结果

媒体和品牌控制

媒体库

上传媒体

上传状态

获取媒体资产

删除媒体资产

列出幻灯片

获取幻灯片

更新幻灯片