README

重要： 此 SDK 已弃用。Amazon Pay 将继续支持此版本，但不会更新新功能。新的集成应使用 Amazon Pay API SDK (PHP) 并参考此文档了解更多详情。

Amazon Pay SDK (PHP)

Amazon Pay API 集成

要求

Amazon Pay 账户
美国 - 注册
英国 - 注册
德国 - 注册
日本 - 注册
PHP 5.5 或更高版本
Curl 7.18 或更高版本

正在弃用对 PHP 5.3 和 5.4 的支持。SDK 将在这些旧环境中工作，但未来版本可能不会。我们鼓励商家尽快迁移到 PHP 的新版本。

文档

集成步骤如下

示例

查看 Amazon Pay SDK 示例

快速开始

客户端以以下格式接收参数

关联数组
包含配置信息的 JSON 文件路径。

使用 Composer 安装

composer require amzn/amazon-pay-sdk-php

目录树

.
├── composer.json - Configuration for composer
├── LICENSE.txt
├── NOTICE.txt
├── AmazonPay
│   ├── Client.php - Main class with the API calls
│   ├── ClientInterface.php - Shows the public function definitions in Client.php
│   ├── HttpCurl.php -  Client class uses this file to execute the GET/POST
│   ├── HttpCurlInterface.php - Shows the public function definitions in the HttpCurl.php
│   ├── IpnHandler.php - Class handles verification of the IPN
│   ├── IpnHandlerInterface.php - Shows the public function definitions in the IpnHandler.php
│   ├── Regions.php -  Defines the regions that is supported
│   ├── ResponseParser.php -  Parses the API call response
│   └── ResponseInterface.php - Shows the public function definitions in the ResponseParser.php
├── README.md
└── UnitTests
    ├── ClientTest.php
    ├── config.json
    ├── coverage.txt
    ├── IpnHandlerTest.php
    └── Signature.php

参数列表

必填参数

可选参数

设置配置

您的 Amazon Pay 密钥可在您的卖家中心账户中找到

在实例化客户端对象时设置配置

<?php
namespace AmazonPay;

require_once 'Client.php';
// or, instead of using require_once, you can use the phar file instead
// include 'amazon-pay.phar';

// PHP Associative array
$config = array(
    'merchant_id' => 'YOUR_MERCHANT_ID',
    'access_key'  => 'YOUR_ACCESS_KEY',
    'secret_key'  => 'YOUR_SECRET_KEY',
    'client_id'   => 'YOUR_LOGIN_WITH_AMAZON_CLIENT_ID',
    'region'      => 'REGION');

// or, instead of setting the array in the code, you can
// initialze the Client by specifying a JSON file
// $config = 'PATH_TO_JSON_FILE';

// Instantiate the client class with the config type
$client = new Client($config);

沙盒模式下测试

未指定时，沙盒参数默认为 false

<?php
namespace AmazonPay;

$config = array(
    'merchant_id' => 'YOUR_MERCHANT_ID',
    'access_key'  => 'YOUR_ACCESS_KEY',
    'secret_key'  => 'YOUR_SECRET_KEY',
    'client_id'   => 'YOUR_LOGIN_WITH_AMAZON_CLIENT_ID',
    'region'      => 'REGION',
    'sandbox'     => true);

$client = new Client($config);

// Also you can set the sandbox variable in the config() array of the Client class by

$client->setSandbox(true);

设置代理值

可以使用以下设置器在实例化客户端对象后设置代理参数

$proxy =  array();
$proxy['proxy_user_host'] // Hostname for the proxy
$proxy['proxy_user_port'] // Hostname for the proxy
$proxy['proxy_user_name'] // If your proxy requires a username
$proxy['proxy_user_password'] // If your proxy requires a password

$client->setProxy($proxy);

进行 API 调用

以下是如何进行 GetOrderReferenceDetails API 调用的示例

<?php
namespace AmazonPay;

$requestParameters = array();

// AMAZON_ORDER_REFERENCE_ID is obtained from the Amazon Pay Address/Wallet widgets
// ACCESS_TOKEN is obtained from the GET parameter from the URL.

// Required Parameter
$requestParameters['amazon_order_reference_id'] = 'AMAZON_ORDER_REFERENCE_ID';

// Optional Parameter
$requestParameters['address_consent_token']  = 'ACCESS_TOKEN';
$requestParameters['mws_auth_token']         = 'MWS_AUTH_TOKEN';

$response = $client->getOrderReferenceDetails($requestParameters);

有关解析 API 响应的信息，请参阅 API 响应部分。

以下是如何进行 GetMerchantAccountStatus API 调用的示例

$requestParameters = array();

// Optional Parameter
$requestParameters['mws_auth_token']         = 'MWS_AUTH_TOKEN';

$response = $client->getMerchantAccountStatus($requestParameters);
echo $response->toXml() . "\n";

// Sample Response
<GetMerchantAccountStatusResponse xmlns="http://mws.amazonservices.com/schema/OffAmazonPayments/2013-01-01">
  <GetMerchantAccountStatusResult>
    <AccountStatus>ACTIVE</AccountStatus>
  </GetMerchantAccountStatusResult>
  <ResponseMetadata>
    <RequestId>b0a141f7-712a-4830-8014-2aa0c446b04e</RequestId>
  </ResponseMetadata>
</GetMerchantAccountStatusResponse>

有关解析 API 响应的信息，请参阅 API 响应部分。

以下是如何进行 ListOrderReference API 调用的示例

$requestParameters = array();

// Required Parameter
$configArray['query_id']             = 'SELLER_ORDER_ID';
$configArray['query_id_type']        = 'SellerOrderId';

// Optional Parameter
$requestParameters['mws_auth_token'] = 'MWS_AUTH_TOKEN';
$configArray['page_size']            = "1";

$response = $client->listOrderReference($requestParameters);
echo $response->toXml() . "\n";

// Sample Response
<ListOrderReferenceResponse xmlns="http://mws.amazonservices.com/schema/OffAmazonPayments/2013-01-01">
  <ListOrderReferenceResult>
    <OrderReferenceList>
      <OrderReference>
        <ReleaseEnvironment>Sandbox</ReleaseEnvironment>
        <OrderReferenceStatus>
          <LastUpdateTimestamp>2018-08-06T22:45:37.314Z</LastUpdateTimestamp>
          <State>Open</State>
        </OrderReferenceStatus>
        <AmazonOrderReferenceId>S01-6649662-0708590</AmazonOrderReferenceId>
        <CreationTimestamp>2018-08-06T22:45:28.203Z</CreationTimestamp>
        <SellerOrderAttributes>
          <StoreName>PHP SDK Test goGetOrderReferenceDetails</StoreName>
          <CustomInformation>PHP SDK Custom Information Testing</CustomInformation>
          <SellerOrderId>PHP SDK ID# 12345</SellerOrderId>
        </SellerOrderAttributes>
        <OrderTotal>
          <CurrencyCode>USD</CurrencyCode>
          <Amount>0.01</Amount>
        </OrderTotal>
      </OrderReference>
    </OrderReferenceList>
    <NextPageToken>eyJuZXh0UGFn...=</NextPageToken>
  </ListOrderReferenceResult>
  <ResponseMetadata>
    <RequestId>5749768d-307b-493b-90b0-8b5b9f2ea436</RequestId>
  </ResponseMetadata>
</ListOrderReferenceResponse>

有关解析 API 响应的信息，请参阅 API 响应部分。

以下是如何进行 ListOrderReferenceByNextToken API 调用的示例

$requestParameters = array();

// Required Parameter
$configArray['next_page_token']            = "NEXT_PAGE_TOKEN";

$response = $client->listOrderReferenceByNextToken($requestParameters);
echo $response->toXml() . "\n";

// Sample Response
<ListOrderReferenceByNextTokenResponse xmlns="http://mws.amazonservices.com/schema/OffAmazonPayments/2013-01-01">
  <ListOrderReferenceByNextTokenResult>
    <OrderReferenceList>
      <OrderReference>
        <ReleaseEnvironment>Sandbox</ReleaseEnvironment>
        <OrderReferenceStatus>
          <LastUpdateTimestamp>2018-08-06T22:42:50.191Z</LastUpdateTimestamp>
          <State>Open</State>
        </OrderReferenceStatus>
        <AmazonOrderReferenceId>S01-1662310-7599388</AmazonOrderReferenceId>
        <CreationTimestamp>2018-08-06T22:42:35.904Z</CreationTimestamp>
        <SellerOrderAttributes>
          <StoreName>PHP SDK Test goGetOrderReferenceDetails</StoreName>
          <CustomInformation>PHP SDK Custom Information Testing</CustomInformation>
          <SellerOrderId>PHP SDK ID# 12345</SellerOrderId>
        </SellerOrderAttributes>
        <OrderTotal>
          <CurrencyCode>USD</CurrencyCode>
          <Amount>0.01</Amount>
        </OrderTotal>
      </OrderReference>
    </OrderReferenceList>
    <NextPageToken>eyJuZXh0UGFnZVRva2VuIjoiQUFBQUFBQUFBQ...</NextPageToken>
  </ListOrderReferenceByNextTokenResult>
  <ResponseMetadata>
    <RequestId>8e06c852-4072-4cfb-99a3-060ec1ef7be8</RequestId>
  </ResponseMetadata>
</ListOrderReferenceByNextTokenResponse>

有关解析 API 响应的信息，请参阅 API 响应部分。

IPN 处理

要成功接收 IPN，您需要在您的域上有一个有效的 SSL。
您可以通过以下方式设置您的通知端点：(a) 使用卖家中心集成设置页面的设置选项卡，或(b) 使用 SetMerchantNotificationConfiguration API 调用。
IpnHandler.php 类处理 IPN 的来源和数据验证

将以下代码添加到任何文件中，并通过访问设置选项卡中的集成设置页面在“商家/集成器 URL”中设置文件的位置。

<?php
namespace AmazonPay;

require_once 'IpnHandler.php';

// Get the IPN headers and Message body
$headers = getallheaders();
$body = file_get_contents('php://input');

// Create an object($ipnHandler) of the IpnHandler class
$ipnHandler = new IpnHandler($headers, $body);

有关解析 IPN 响应的信息，请参阅 IPN 响应部分。

使用 SetMerchantNotificationConfiguration API 设置通知端点

$client = new AmazonPay\Client($config);

// possible array values: ALL, ORDER_REFERENCE, PAYMENT_AUTHORIZE, PAYMENT_CAPTURE, PAYMENT_REFUND, BILLING_AGREEMENT, CHARGEBACK_DETAILED
$notificationConfiguration['https://dev.null/ipn/onetime'] = array('ORDER_REFERENCE', 'PAYMENT_AUTHORIZE', 'PAYMENT_CAPTURE');
$notificationConfiguration['https://dev.null/ipn/recurring'] = array('BILLING_AGREEMENT');
$notificationConfiguration['https://dev.null/ipn/refunds'] = array('PAYMENT_REFUND', 'CHARGEBACK_DETAILED');
$requestParameters['notification_configuration_list'] = $notificationConfiguration;

// or, if you prefer all IPNs come to the same endpoint, do this one-liner instead:
// $requestParameters['notification_configuration_list'] = array('https://dev.null/ipn' => array('ALL'));

// if you are calling on behalf of another merhcant using delegated access, be sure to set the merchant ID and auth token:
// $requestParameters['merchant_id'] = 'THE_MERCHANT_ID';
// $requestParameters['mws_auth_token'] = 'THE_MWS_AUTH_TOKEN';

$response = $client->setMerchantNotificationConfiguration($requestParameters);
if ($response->toArray()['ResponseStatus'] !== '200') {
    print "error occured calling API";
}

// to troubleshoot, you can call GetMerchantNotificationConfiguration to view current IPN settings
$response = $client->getMerchantNotificationConfiguration($requestParameters);
print $response->toXml();

便捷方法

收费方法

收费方法结合以下 API 调用

标准支付/定期支付

SetOrderReferenceDetails / SetBillingAgreementDetails
ConfirmOrderReference / ConfirmBillingAgreement
Authorize / AuthorizeOnBillingAgreement

对于标准支付，第一次调用charge将执行SetOrderReferenceDetails、ConfirmOrderReference和Authorize API调用。对于同一订单参考ID的后续调用到charge方法，只会调用Authorize。

对于周期性支付，第一次调用charge将执行SetBillingAgreementDetails、ConfirmBillingAgreement和AuthorizeOnBillingAgreement API调用。对于同一账单协议ID的后续调用到charge方法，只会调用AuthorizeOnBillingAgreement。

立即捕获可以设置为true用于数字商品。对于实体商品，强烈建议将立即捕获设置为false，并在发货完成后通过执行capture API调用来捕获金额。

// Create an array that will contain the parameters for the charge API call
$requestParameters = array();

// Adding the parameters values to the respective keys in the array
$requestParameters['amazon_reference_id'] = 'AMAZON_REFERENCE_ID';

// Or
// If $requestParameters['amazon_reference_id'] is not provided,
// either one of the following ID input is needed
$requestParameters['amazon_order_reference_id'] = 'AMAZON_ORDER_REFERENCE_ID';
$requestParameters['amazon_billing_agreement_id'] = 'AMAZON_BILLING_AGREEMENT_ID';

$requestParameters['seller_id'] = null;
$requestParameters['charge_amount'] = '100.50';
$requestParameters['currency_code'] = 'USD';
$requestParameters['authorization_reference_id'] = 'UNIQUE STRING';
$requestParameters['transaction_timeout'] = 0;
$requestParameters['capture_now'] = false; //true for Digital goods
$requestParameters['charge_note'] = 'Example item note';
$requestParameters['charge_order_id'] = '1234-Example-Order';
$requestParameters['store_name'] = 'Example Store';
$requestParameters['platform_Id'] = null;
$requestParameters['custom_information'] = 'Any_Custom_String';
$requestParameters['mws_auth_token'] = null;

// Get the Authorization response from the charge method
$response = $client->charge($requestParameters);

有关解析 API 响应的信息，请参阅 API 响应部分。

获取配置文件信息（getUserInfo方法）

使用按钮小部件返回的访问令牌从Amazon获取用户的配置文件信息。
当用户登录到网站时，授权服务器会授予访问令牌。
访问令牌针对客户端、用户和访问范围是特定的。客户端必须使用访问令牌来检索客户配置文件数据。

<?php namespace AmazonPay;

// config array parameters that need to be instantiated
$config = array(
    'client_id' => 'YOUR_LWA_CLIENT_ID',
    'region'    => 'REGION');

$client = new Client($config);

// Client ID can also be set using the setter function setClientId($client_id)
$client->setClientId(‘YOUR_LWA_CLIENT_ID’);

// Get the Access Token from the URL
$access_token = 'ACCESS_TOKEN';
// Calling the function getUserInfo with the access token parameter returns object
$userInfo = $client->getUserInfo($access_token);

// Buyer name
$userInfo['name'];
// Buyer Email
$userInfo['email'];
// Buyer User Id
$userInfo['user_id'];

响应解析

响应以3种格式提供

XML/原始响应
关联数组
JSON格式

API响应

// Returns an object($response) of the class ResponseParser.php
$response = $client->getOrderReferenceDetails($requestParameters);

// XML response
$response->toXml();

// Associative array response
$response->toArray();

// JSON response
$response->toJson();

IPN响应

$ipnHandler = new IpnHandler($headers, $body);

// Raw message response
$ipnHandler->returnMessage();

// Associative array response
$ipnHandler->toArray();

// JSON response
$ipnHandler->toJson();

日志记录

SDK对清洗后的请求和响应进行日志记录，可以与任何PSR-3兼容的记录器（如Monolog）一起使用。

API响应

namespace AmazonPay;
require 'vendor/autoload.php';
include 'amazon-pay.phar';
 
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

date_default_timezone_set('America/Los_Angeles');
$log = new Logger('TestSDK');

$log->pushHandler(new StreamHandler('php://stdout', Logger::DEBUG));

$client = new Client('us.config');
$client->setLogger($log);

$response = $client->getServiceStatus();

amzn / amazon-pay-sdk-php

维护者

详细信息

README

Amazon Pay SDK (PHP)

要求

文档

示例

快速开始

使用 Composer 安装

目录树

参数列表

必填参数

可选参数

设置配置

沙盒模式下测试

设置代理值

进行 API 调用

IPN 处理

使用 SetMerchantNotificationConfiguration API 设置通知端点

便捷方法

收费方法

获取配置文件信息（getUserInfo方法）

响应解析

API响应

IPN响应

日志记录

API响应