README

PHP 实现 @Pay 的 Token 协议。更多详情请访问 @Pay 开发者网站。

Token 是一个包含金融交易（例如发票或产品销售报价）信息的值。当 Token 从与 支付方式 相关的地址发送到 transaction@processor.atpay.com 时，将创建一个 交易。

@Pay 处理两种 Token 类别 - 目标 Token，用于发送发票或仅适用于单个接收者的交易（专业优惠等），以及 批量 Token，适用于电子邮件营销列表。

电子邮件按钮 是嵌入电子邮件消息中的链接。激活后，此链接将打开一个新邮件，收件人、主题和消息正文已预先填写。默认情况下，此电子邮件包含两种 Token 类型之一。点击“发送”将电子邮件发送到 @Pay 并触发 交易 处理。发送者将收到收据或进一步说明。

安装

此库需要安装 PHP Sodium 扩展。

PHP 归档

$ curl -O -L http://github.com/atpay/atpay_php/releases/download/2.0.2/atpay_php.phar

然后在您的应用程序中引入 atpay_php

require_once 'atpay_php.phar';        # include php archive.

Composer

{
  "require": {
    "atpay/atpay_php": "2.0.5"
  }
}

$ curl -s http://getcomposer.org/installer | php
$ php composer.phar install

require 'vendor/autoload.php';

配置

所有 Token 生成函数都需要一个 Session 对象。从 https://dashboard.atpay.com/（API 设置）获取您的 API 凭证。

$session = new \AtPay\Session(partner_id, public_key, private_key);

目标 Tokens

一个 目标 Token 适用于发送发票或仅适用于单个接收者的交易（专业优惠等）。

以下代码为金额为 20 美元的交易创建了一个针对与 'test@example.com' 相关的信用卡的 Token

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'customer@example.com');
echo $invoice_token->to_s();

注意：以前称为 Invoice Token 的 目标 Token。请使用 目标 Token，因为 Invoice Token 将被弃用。

批量 Tokens

大多数商家可以在 @Pay 商户仪表板 上手动生成 批量电子邮件按钮，但对于需要自动化这些消息生成的案例，您可以在不直接与 @Pay 服务器通信的情况下创建 批量 Tokens。

批量 Token 适用于大型邮件列表。您可以向任何数量的接收者发送相同的 Token。它适用于“每日优惠”类型的产品或一般营销。

为 30 美元搅拌机创建 批量 Token

$bulk_token = new \AtPay\Token\Bulk($session, 30);
echo $bulk_token->to_s();

如果 Token 接收者尝试通过电子邮件购买产品但尚未配置信用卡，他们将会收到一条消息，要求他们完成交易。如果您希望将来允许他们在该页面上创建两步电子邮件交易，则应在该页面上集成 @Pay JS SDK。

通用 Token 属性

仅授权

Token 将同时触发资金授权和资金捕获。如果您正在运输实物商品或出于其他原因想要延迟捕获，请使用 auth_only! 方法来调整此行为

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'customer@example.com');
$invoice_token->auth_only();
echo $invoice_token->to_s();

过期时间

令牌在2周内过期，除非另有说明。令牌过期后尝试使用会导致向发送者发送礼貌的错误信息。要调整过期时间

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'customer@example.com');
$invoice_token->expires_in_seconds(60 * 60 * 24 * 7); // one week
echo $invoice_token->to_s();

注册页面

当新客户或拥有过期或无效信用卡信息的客户尝试通过电子邮件购买时，他们将被重定向到令牌的注册页面，在那里他们可以输入新的信用卡信息。默认情况下，@Pay将托管该注册页面，但您可能希望将客户引导到您自己网站上的产品页面（使用@Pay JS SDK在您的页面上启用@Pay卡令牌化）。要指定自定义URL

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->url('https://example.com/invoices/123');
echo $invoice_token->to_s();

在托管注册页面上请求自定义信息

如果您选择使用托管支付捕获页面（未指定上述URL），您可以在Web上的购买过程中从您的客户那里获取更多信息。例如，以下请求了一个可选的礼品信息

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->request_custom_data('gift_message', true); //Input name , required (defaults to false)
echo $invoice_token->to_s();

请求托管注册页面的URL

托管支付捕获页面直接与令牌相关。它是在令牌首次收到transaction@processor.atpay.com或在使用前从@Pay请求URL时创建的。要请求URL，您必须联系@Pay的服务器

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$registration = $invoice_token->register();

echo $registration->url();
=> "https://example.secured.atpay.com/{token_identifier}"

echo $registration->short();
=> "atpay://{token_identifier}"

注意：对于高流量，此解决方案可能不足。请联系@Pay进行咨询。

项目名称

您可以为将在托管支付捕获页面上显示的项目名称进行设置

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->name("A Cool Offer");
echo $invoice_token->to_s();

项目详情

您可以为将在托管支付捕获页面上显示的项目详情进行设置

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->set_item_details("Lorem Ipsum ...");
echo $invoice_token->to_s();

收集地址

请求托管支付捕获页面收集任何组合的发货或账单地址，使用requires_shipping_address(true)和requires_billing_address(true)

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->requires_billing_address(true);
$invoice_token->requires_shipping_address(true);
echo $invoice_token->to_s();

设置项目数量

如果您使用@Pay的webhook进行库存控制，您可以指定您创建的报价的初始数量。

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$invoice_token->set_item_quantity(3);
echo $invoice_token->to_s();

履行时间

@Pay的交易详情可能包括一个估计履行时间。@Pay在需要履行时期望进行授权交易。只有在履行完成后才应捕获交易。

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'test@example.com');
$token_token->estimated_fulfillment_days(3)      # The token is now auth-only!
email(token.to_s, receipient_address)

自定义用户数据

自定义用户数据是一个令牌属性，包含您希望在@Pay处理令牌时获取回的任何字符串。它的限制为2500个字符。

$invoice_token = new \AtPay\Token\Targeted($session, 20, 'customer@example.com');
$invoice_token->custom_user_data("{foo => bar}");
echo $invoice_token->to_s();

按钮生成

PHP客户端目前不支持按钮生成。

完整示例

<?php
  // Include @Pay's PHP SDK
  require_once 'atpay_php.phar';        # include php archive.
  //require 'vendor/autoload.php';      # when using composer.

  // Configure with your keys:
  $partner_id       = '';
  $public_key       = '';
  $private_key      = '';

  $session = new \AtPay\Session($partner_id, $public_key, $private_key);

  // Generate a new Invoice Token for $150
  $total_price    = 150;
  $customer_email = "customer@example.com";


  $invoice_token = new \AtPay\Token\Targeted($session, $total_price, $customer_email);
  $token         = $invoice_token->to_s();

  // Send an Email to the Customer
  $subject = "You Abandoned Your Cart!";
  $from    = "merchant@example.com";

  $headers  = 'MIME-Version: 1.0' . "\r\n";
  $headers .= 'Content-type: text/html; charset=iso-8859-1' . "\r\n";
  $headers .= 'From: '.$from."\r\n";
  $message  = '<a href="mailto:transaction@processor.atpay.com?subject='.urlencode('PHP Token').'&body='.urlencode($token).'">Click to Buy</a>'; # creates a mailto with generated invoice token that will send to @Pay to process

  // Send the email
  mail($customer_email, $subject, $message, $headers);

  // Done
  echo "Invoice Sent!";
?>