payarc/payarc-sdk-php

Payarc PHP Sdk

维护者

详细信息

github.com/Payarc/payarc-sdk-php

主页

源代码

问题

安装: 23

依赖: 0

建议者: 0

安全性: 0

星标: 0

关注者: 0

分支: 0

开放问题: 0

v1.5.0-alpha.1 2024-08-17 07:24 UTC

Requires

MIT 5243c837768f888b7958ac8c196bfec56ede82f1

  • Payarc and contributors

apipayment processingpayarc

This package is not auto-updated.

Last update: 2024-09-28 08:12:04 UTC

README

Payarc SDK 允许开发人员轻松地将 Payarc 的支付处理功能集成到他们的应用程序中。此 SDK 提供了一套全面的 API，用于处理交易、客户管理和候选商户管理。

目录

要求

PHP 8.1 或更高版本。

安装

您可以使用 composer 安装 Payarc SDK。运行以下命令

警告

此包尚无稳定版本。使用以下命令安装包。

composer config minimum-stability dev && composer require payarc/payarc-sdk-php:dev-master --prefer-stable && composer config --unset minimum-stability

要使用绑定，请使用 Composer 的 autoload

require_once('vendor/autoload.php');

依赖关系

为了正确运行，绑定需要以下扩展

  • curl，尽管您可以选择使用自己的非 cURL 客户端
  • json
  • mbstring (多字节字符串)

如果使用 Composer，这些依赖关系应该会自动处理。如果您手动安装，请确保这些扩展可用。

使用

在使用 Payarc SDK 之前，您需要使用您的 API 密钥和 URL 基础点对其进行初始化。这用于验证您的请求并指定 API 的端点。对于每个环境（prod、sandbox），这两个参数都有不同的值。此信息应保留在您的服务器上，并采取措施确保不要与您的客户共享。提供的示例使用包 symfony/dotenv 来存储此信息并在构造函数中提供。这不是强制性的，因为您的设置可能不同。如果您想利用所谓的代理识别令牌来使用候选商户功能，您可以从门户中获取此令牌。

您必须在项目的根目录中创建 .env 文件，并在以下行之后更新以下内容

PAYARC_BASE_URL=''
PAYARC_KEY=''
AGENT_KEY=''
PAYARC_VERSION=1

然后安装 symfony/dotenv 包

$ composer require symfony/dotenv

您必须从 SDK 创建对象以调用不同的方法，具体取决于业务需求。可选地，您可以通过添加以下代码将 .env 文件加载到配置中

use Symfony\Component\Dotenv\Dotenv;
$dotenv = new Dotenv();
$dotenv->load('.env');

然后您创建 SDK 的实例

/**
 * Creates an instance of Payarc.
 * @param {string} bearer_token - The bearer token for authentication.Mandatory parameter to construct the object
 * @param {string} [base_url='sandbox'] - The url of access points possible values prod or sandbox, as sandbox is the default one. Vary for testing playground and production. can be set in environment file too.
 * @param {string} [api_version='/v1/'] - The version of access points for now 1(it has default value thus could be omitted).
 * @param {string} [version='1.0'] - API version.
 * @param {string} bearer_token_agent - The bearer token for agent authentication. Only required if you need functionality around candidate merchant
 * 
 */
require_once '../vendor/autoload.php';
use Payarc\PayarcSdkPhp\Payarc;
use Symfony\Component\Dotenv\Dotenv;

$dotenv = new Dotenv();
$dotenv->load('.env');

$payarc = new Payarc(
    bearer_token: $_ENV['PAYARC_KEY'],
    base_url: $_ENV['PAYARC_BASE_URL'],
    version: $_ENV['PAYARC_VERSION'],
    bearer_token_agent: $_ENV['AGENT_KEY']
);

如果没有错误，您可以继续。

API 参考

示例

SDK 是围绕 payarc 对象构建的。从这个对象中，您可以访问支持您操作的属性和函数。

Object Payarc 有以下服务

charges - to manipulate payments
customers - to manipulate customers
applications - to manipulate candidate merchants
split_campaigns - to manipulate split campaigns
billing
   - plan - to manipulate plans
   - plan_subscription - to manipulate Plan subscriptions

服务 Payarc->charges 用于在系统中操作支付。此服务有以下函数

create - this function will create a payment intent or charge accepting various configurations and parameters. See examples for some use cases. 
retrieve - this function returns json object 'Charge' with details
list - returns an object with attribute 'charges' a list of json object holding information for charges and object in attribute 'pagination'
createRefund - function to perform a refund over existing charge

服务 Payarc->customer

服务 Payarc->customer 代表您的客户，包括个人信息、地址以及信用卡和/或银行账户。信息已保存供未来使用。

create - this function will create object stored in the database for a customer. it will provide identifier unique for each in order to identify and inquiry details. See examples and docs for more information
retrieve - this function extract details for specific customer from database
list - this function allows you to search amongst customers you had created. It is possible to search based on some criteria. See examples and documentation for more details  
update - this function allows you to modify attributes of customer object.

服务 Payarc->applications

服务 Payarc->applications 由代理商和独立软件供应商（ISVs）用于管理新客户的潜在商户。因此，您可以创建、列出、获取详细信息以及管理boarding流程中所需的文档。
create - this function add new candidate into database. See documentation for available attributes, possible values for some of them and which are mandatory. 
list - returns a list of application object representing future merchants. Use this function to find the interested identifier. 
retrieve - based on identifier or an object returned from list function, this function will return details 
delete - in case candidate merchant is no longer needed it will remove information for it.
add_document - this function is adding base64 encoded document to existing candidate merchant. For different types of document required in the process contact Payarc. See examples how the function could be invoked
delete_document - this function removes document, when document is no longer valid.
list_sub_agents - this function is usefull to create candidate in behalf of other agent.
submit - this function initialize the process of sing off contract between Payarc and your client

服务 Payarc->billing

此服务聚合其他负责周期性支付的服务。目前，这些服务是 plan 和 plan_subscription。

服务 Payarc->billing->plan

此服务包含每个计划的特定信息，例如识别详情、支付请求规则和附加信息。此服务有如下方法：

create - you can programmatically created new objects to meet client's needs,
list - inquiry available plans,
retrieve - collect detailed information for a plan,
update - modify details of a plan,
delete - remove plan when no longer needed,
create_subscription: issue a subscription for a customer from a plan.

根据计划，您可以创建订阅。定时作业将根据计划安排向客户请求和收取（费用）。

创建费用

示例：使用最少信息创建费用

要从客户处创建 payment(charge)，所需的最少信息是

  • amount 转换为分（cent）
  • currency 等于 'usd'（美元）
  • source 是将被扣除上述金额的信用卡

对于信用卡，所需的最少属性是 卡号 和 到期日期。完整属性列表请参阅API文档。此示例演示了如何使用最少信息创建费用

try {
    $charge = $payarc->charges->create(
        [
            'amount' => 2860,
            'currency' => 'usd',
            'source' => [
                "card_number" => "4012******5439",
                "exp_month" => "03",
                "exp_year" => "2025",
            ]
        ],
    );
    echo "Charge created: " . json_encode($charge) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

示例：通过令牌创建费用

要从客户处创建支付（费用），所需的最少信息是

  • amount 转换为分（cent）
  • currency 等于 'usd'（美元）
  • source 是一个具有属性 token_id 的对象。这可以通过 CREATE TOKEN API 获取。此示例展示了如何使用令牌创建费用
 $charge_data = [
    'amount' => 1285,
    'currency' => 'usd',
    'source' => [
        "token_id" => "tok_mE*****LL8wYl"
    ]
];
try {
    $charge = $payarc->charges->create($charge_data);
    echo "Charge created: " . json_encode($charge) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

示例：通过卡ID创建费用

如果知道特定信用卡（cc）的ID以及该卡所属的客户ID，则可以在该信用卡上生成费用。此示例演示了如何使用卡ID创建费用

$charge_data = [
    'amount' => 3985,
    'currency' => 'usd',
    'source' => [
        'card_id' => 'card_Ly9*****59M0m1',
        'customer_id' => 'cus_j*******PVnDp'
    ]
];
try {
    $charge = $payarc->charges->create($charge_data);
    echo "Charge created: " . json_encode($charge) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

示例：通过银行账户ID创建费用

此示例展示了当您知道银行账户时如何创建ACH费用

try {
    $customer = $this->payarc->customers->retrieve('cus_j*******p');
    $charge_data = [
        'amount' => 3785,
        'sec_code'=> 'WEB',
        'source' => [
            'bank_account_id'=> 'bnk_eJjbbbbbblL'
        ]
    ];
    $charge =  $customer['charges']['create'](charge_data);
    echo "Charge created: " . json_encode($charge) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

示例：使用新银行账户创建ACH费用

try {
    $customer = $this->payarc->customers->retrieve('cus_j*******p');
    $charge_data = [
        'amount' => 3785,
        'sec_code'=> 'WEB',
        'source' => [
             'account_number' =>'123432575352',
             'routing_number'=>'123345349',
             'first_name'=> 'FirstName III',
             'last_name'=>'LastName III',
             'account_type'=> 'Personal Savings',
        ]
    ];
    $charge =  $customer['charges']['create'](charge_data);
    echo "Charge created: " . json_encode($charge) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

列出费用

示例：无约束列出费用

此示例演示了如何列出所有费用，没有任何约束

try {
    $charges = $payarc->charges->list();
    echo "Charges listed: " . json_encode($charges) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

检索费用

示例：检索费用

此示例展示了如何通过其ID检索特定费用

try {
    $charge = $payarc->charges->retrieve('ch_1J*****3');
    echo "Charge retrieved: " . json_encode($charge) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

示例：检索ACH费用

此示例展示了如何通过其ID检索特定ACH费用

try {
    $charge = $payarc->charges->retrieve('ach_1J*****3');
    echo "Charge retrieved: " . json_encode($charge) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

退款费用

示例：退款费用

此示例演示了如何通过其ID退款费用或ACH费用

  • 对于常规费用使用 ch_ 前缀，对于ACH费用使用 ach_ 前缀。
try {
    $id = 'ach_g**********08eA';
    $options = ['reason' => 'requested_by_customer',
                'description'=> 'The customer returned the product, did not like it']
    $charge = $payarc->charges->createRefund($id, $options);
    echo "Charge refunded: " . json_encode($charge) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

管理客户

示例：使用信用卡信息创建客户

此示例展示了如何使用信用卡信息创建新客户

 $customer_data = [
            "email" => "anon+50@example.com",
            "cards" => [
                [
                    "card_source" => "INTERNET",
                    "card_number" => "4012000098765439",
                    "exp_month" => "07",
                    "exp_year" => "2025",
                    "cvv" => "997",
                    "card_holder_name" => "Bat Doncho",
                    "address_line1" => "123 Main Street",
                    "city" => "Greenwich",
                    "state" => "CT",
                    "zip" => "06830",
                    "country" => "US",
                ],
                [
                    "card_source" => "INTERNET",
                    "card_number" => "4012000098765439",
                    "exp_month" => "01",
                    "exp_year" => "2025",
                    "cvv" => "998",
                    "card_holder_name" => "Bat Gancho",
                    "address_line1" => "123 Main Street Apt 44",
                    "city" => "Greenwich",
                    "state" => "CT",
                    "zip" => "06830",
                    "country" => "US",
                ]
            ]
        ];

        try {
            $customer = $payarc->customers->create($customer_data);
            echo "Customer created: " . json_encode($customer) . "\n";
        } catch (Throwable $e) {
            echo "Error detected: " . $e->getMessage() . "\n";
        }

示例：更新客户

此示例演示了当仅知道ID时如何更新现有客户的信息

 
 try {
    $id = 'cus_j*******p';
    $customer = $payarc->customers->update($id, [
        "name" => "Bai Doncho 3",
        "description" => "Example customer",
        "phone" => "1234567890"
    ]);
    echo "Customer updated: " . json_encode($customer) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

示例：更新已找到的客户

此示例展示了如何更新客户对象

try {
    $customer = $payarc->customers->retrieve('cus_j*******p');
    $customer = $customer['update']([
        "name" => "Bai Doncho 4",
        "description" => "Senior Example customer",
        "phone" => "1234567895"
    ]);
    echo "Customer updated: " . json_encode($customer) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

示例：有限制列出客户

此示例演示了如何列出具有指定限制的客户

try {
    $customers = $payarc->customers->list(['limit' => 3]);
    echo "Customers retrieved: " . json_encode($customers) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

示例：向客户添加新卡

此示例展示了如何向现有客户添加新卡

 $card_data = [
            "card_source" => "INTERNET",
            "card_number" => "4012000098765439",
            "exp_month" => "01",
            "exp_year" => "2025",
            "cvv" => "998",
            "card_holder_name" => "Bat Gancho",
            "address_line1" => "123 Main Street Apt 44",
            "city" => "Greenwich",
            "state" => "CT",
            "zip" => "06830",
            "country" => "US",
        ];
try {
    $customer = $payarc->customers->retrieve($id);
    $card = $customer['cards']['create']($card_data);
    echo "Card added: " . json_encode($card) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

示例：向客户添加新银行账户

本示例展示了如何向客户添加新的银行账户。有关API文档中银行账户属性的完整列表，请参阅。

 $acc_data = [
            "account_number" => "1234567890",
            "routing_number" => "110000000",
            'first_name' => 'Bat Petio',
            'last_name' => 'The Tsar',
            "account_type" => "Personal Savings",
            'sec_code' => 'WEB'
        ];
try {
    $customer = $payarc->customers->retrieve($id);
    $acc = $customer['bank_accounts']['create']($acc_data);
    echo "Bank account added: " . json_encode($acc) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

管理候选商家

创建新的候选商家

在与Payarc连接客户的过程中，根据Payarc的标准进行选择。过程从填写商家信息并在数据库中创建条目开始。以下是一个如何启动此过程的示例

 $merchant_candidate = [
            "Lead" => [
                "Industry" => "cbd",
                "MerchantName" => "Kolio i sie",
                "LegalName" => "Best Co in w",
                "ContactFirstName" => "Joan",
                "ContactLastName" => "Dhow",
                "ContactEmail" => "contact+25@mail.com",
                "DiscountRateProgram" => "interchange"
            ],
            "Owners" => [
                [
                    "FirstName" => "First",
                    "LastName" => "Last",
                    "Title" => "President",
                    "OwnershipPct" => 100,
                    "Address" => "Somewhere",
                    "City" => "City Of Test",
                    "SSN" => "4546-0034",
                    "State" => "WY",
                    "ZipCode" => "10102",
                    "BirthDate" => "1993-06-24",
                    "Email" => "nikoj@negointeresuva2.com",
                    "PhoneNo" => "2346456784"
                ]
            ]
        ];

try {
    $merchant = $payarc->applications->create($merchant_candidate);
    echo "Merchant candidate created: " . json_encode($merchant) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

在此示例中，属性Lead是一个表示业务的对象，正如属性Owners是一个表示此业务所有者的对象数组一样。请注意，这是所需的最小信息。为了成功注册，您应尽可能提供更多信息，请参阅文档。在某些情况下，登录用户必须代表其他代理创建应用程序。在这种情况下，必须将此代理的object_id发送到函数payarc->applications->create中发送的对象中。要获取代理列表，可以使用函数list_sub_agents，如示例中所示

 $merc_candidate = [
            "Lead" => [
                "Industry" => "cbd",
                "MerchantName" => "chichovoto",
                "LegalName" => "Best Co in w",
                "ContactFirstName" => "Lubo",
                "ContactLastName" => "Penev",
                "ContactEmail" => "penata@chichovoto.com",
                "DiscountRateProgram"=> "interchange"
            ],
            "Owners" => [
                [
                    "FirstName" => "First",
                    "LastName" => "Last",
                    "Title" => "President",
                    "OwnershipPct" => 100,
                    "Address" => "Somewhere",
                    "City" => "City Of Test",
                    "SSN" => "4546-0034",
                    "State" => "WY",
                    "ZipCode" => "10102",
                    "BirthDate" => "1993-06-24",
                    "Email" => "nikoj@negointeresuva.com",
                    "PhoneNo" => "2346456784"
                ]
            ]
        ];
try {
    $sub_agent = $payarc->applications->list_sub_agents();
    $merc_candidate['agentId'] = $sub_agent['sub_agents'][0]['object_id'] ?? null;
    $candidate = $this->payarc->applications->create($merc_candidate);
    echo "Merchant candidate created: " . json_encode($candidate) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

检索候选商家的信息

要继续注册流程，您可能需要提供更多信息或查询现有线索。在SDK中，以下函数存在：list和retrieve。

列出当前代理的所有候选商家

try {
    $applications = $payarc->applications->list();
    echo "Applications retrieved: " . json_encode($applications) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

检索当前候选商家的数据

try {
    $id = 'app_1J*****3';
    $merchant = $payarc->applications->retrieve($id);
    echo "Merchant candidate retrieved: " . json_encode($merchant) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

更新候选商家的属性

$id = 'app_1J*****3';
$payload = [
            "MerchantBankAccountNo"=> "999999999",
            "MerchantBankRoutingNo"=> "1848505",
            "BankInstitutionName"=> "Bank of Kolio"
        ];
try{
    $updated_candidate = $payarc
                            ->applications
                            ->update($id, $payload);
    echo "Candidate merchant updated: " . json_encode($updated_candidate) . "\n";
}catch (Throwable $e){
    echo "Error detected: " . $e->getMessage() . "\n";
}

文档管理

SDK提供了通过add_document和delete_document分别添加或删除文档的功能。

添加支持性文档到候选商家的示例

$doc_data = [
            "DocumentType"=> "Business Bank Statement",
            "DocumentName"=> "sample document 1",
            "DocumentIndex"=> 12246,
            "DocumentDataBase64"=> "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAMcAAAAvCAYAAABXEt4pAAAABHNCSVQICAgIfAhkiAAAC11JREFUeF7tXV1yHDUQlsZrkjccB2K/sZwA5wSYil3FG+YEcU6AcwLMCeKcAHMCNm9U2SmcE2CfgPWbHYhZvxHsHdE9O7OZ1WpGX2tmdjA1U0VBsfppfeqv1Wq1ZL26tmVUjR81dsLNaaUHsV56Nbr4ZVhj80lTK+tf9yMz/sYoszPpS22mfZxS/6OivlfWt79EZBldHL1J+lnZXFH3l79A6qi/b85Go5MRVDYtxONQavwZUieTqaisHxN1GuveS3s+Vj7d3lBL6mOfDK7+C+uO1fXoj6PTsjY/Wd/aHBv1HcNM87fB/6Z/RleXxw98sti/sxxRpL7M6UPWHhdNdUKdUj8n4/e3b9B50nWTwxacyWJ071kdJGEQdGRe5MhQiiP1PaC+n2d9o2OlCaIuJh/VYYX3Kg+VeU71DiQTu/po+1Bp89RXh4R58+7yeNNVjkmhze2PAkxm5uPh2tYJ4eQ1GnlMMjk8dQk3vX91efQyL/fDR092jFYv6DcyDPOfqx/nuMlwRR/1viP8dovaKsTVmMMo0j/9eXF8UoZ94+SYdm7U/tXb4x98ilAIxL3e9/TbXkD9kdb6+buLo8Mgcqxv7SujuG/PZ4ZXl68/95XKfp9Y+tvfkfLamG/fvX09sMuuPtr6npbNfaQNq8wUkwbJkXSZl53w5/kjYhR/CDkerj95aoxmQ8SrTfCXGM/3t8+KVpLFkYOHQIyN/xk/R5c1rsKuTXSv9yv9Jy+VwR8R5Jkx5kekgfwEpf3/hdSLtPrKZ42ydlZh0qlzkqef7z+R6aOlF0rrXUSuojKMCc3JbkMrR9btKcn/GB1vGTl43Ppej1fJxJ2u6ZsaCrs9IscT8g015lfXI00CFtJUXcRA+sqXsScIdX9IyV79dXkMTRzhTquGnlF6l5yswLzq5X8jC/xbVWORa4/dRq8FDnCrpl3EsX4cRYZl9n5F5GhaF1w4a5TR3lGJCpiX5IJ4XaQHa1s/12wlICntCZps+LDJpU3v57791cTv1j8DwlzH72/7+ZWWSEXuhOaN7EK/KuQgQXlzDq38rn6aJkYGpE0QnXY8pALIprO2CfG5IA/Xt3dRN6g2odKGKimCVj9cXRzvl8lEpP8V20DPGhGO8MRGsYu58K8SJgJpXf0s0EiOyLg9zoxbEpVJLePJYglSvIFNCcubVe9yL8AdLupUBNjal2/MJRtxexVCXTF4oIKCbZFj0UaSo6vkGn/F0ExDlsmkxeN9JLQowLS0qMvP4wpIVKMuGVztFPm9JBevsN5ziaLo0mRsoFtk9E9Xb492M/kWrSQ2Lm2Row2DkHk1U3JkYLDV7t3vQf5hVifmQ7hY94lYvBmF3bM8S/OTEQDItTJ6oCIzjIj5LI8xaoMG900IiUrI4Q1Fcn9lG3MiGEe+vCui7Xbirth0xHOYhMxR1lob5JDuh/k8iCJ4h+OxOuVDSDb4S/HNhlHRjsjop4ZpjhwhyjQl1uRA6kCilLbrIParaSDxPzd7rvBwekAmkofH4omY8OrhNQCujTlq/e1DP4krlpGT4ve7TkySMPDygUhZCjBBz0gcOnVOJmSgjTrRkZ7JKsiHwoVGsvQQVrp1oEDIg1rJkYGAhj65vO1ayawFHPUaSAhbFmuHx+bYmKMhWBsTlFQJ/pY7VmTs4HGkDdS0clzT2Pbs0LRLRqFBgLITJIaXV+5GyJFuqDl85/XP7clErVFZSoUNtjQiV3oQBZ9sz27MBeHguUM/gSKfk8XbQA9Z0T1U0WqKzlU6H9d03rHpy7maGljgND0tO4dXmfcDy0zGrRFysHCotbOVHE3xKNv0usARrEhesMn/h1aimdQJMI+KQiRzoWB0QosCHEXKgs5RHeSQzldTY+YVqadu+77tw63qDXWSn1PwxUa/Qpk+Z61hCzubiYmSA8nBycuEWm5kRUKX52xjLghNzx368RjQTTxyADmDySQ1B0qNqeZWmTM69BUFeVBy8Ol7qI76COLPraJ8qKu3r5/5GnJaazAd3sqC9abQIwocKg/aNuqSsMIuqTFFz4C8roL9QlMGIyXeEHF/K5EDOBi15wvdn0mNpESP/eSg1qTL9Qe/EcvbygaIWmRUgR2A10Y82CUhxaDkPkpL196lvMjyY+SQW+fE/W0uZX0Kvy8bItSQFbl7EgKUlYXIQQ3AyYL5zrBJ/RA6RTNg/wvkSK0uctcDSuwrG5MUR4lyVLHQKLECyRG8oknGXwc5CmP/RY2jim6zH1QE8Y0xNDQoIZ5gk++drzIFAjFRHJtHI1UfVnfsJmgVtypELpR40n2WdyJyBdCVY+bSCtIB6nYsKloVKk/ZWFHCAXiVRshQRZG6v4LsYKdxROUK2RegbUvHDMzFtAhMjqJUj6LO0HQHO9UCvV8ilQc9bZWsHIlrhYZoS2bFN8Fo6FiKCTpHRb49qsAh5EBX5cbGzOcc6JLNAPkmcbpU47fcuMrM6SacmNeQPFJyoCHiEm44w7fW3g3K6UrqgJEhdCXN5KjiVoWQQ4IreoYibVNEjglQes++ND8zkcJ7zXacWrLUQ/KsbfGdZe/FqmwMUnJwPdSCOgkCKLNkUpM+PPf1V9e26bKUET0GsWhyJKsy/rjFiPZs35ZdUU4x5Lsw3qRP7jvJrZKsHB8m1wyVig5indzwSr6IsmCpSVJC3Xcqgft/On1tAShpqw55YrMZ8jJFEDkqXMxCN5TouUoDc5Q02Qo5ZB7I5I0CE73MHwpOrmLcPqUVlQ0kRIxMBwLJIVD/kqKF9zmkoNQjTtJKCDlSK0cGA8gly8sKJglyFakbVCMkrZFDmhNnjRkKobtwyty0NslR6GvXGAUS60gFcuD7glQqSepDRUUR42BXaGPlSIzO4g3l1JtpkxylacYtgFJp5ZAqbwgJ27wh2RY5JrgunSzqhZy8wWqFHOgTNmhYt7JZzDUQorRZdUlYF4382WNDw7p1YtLWniMbg9TwBI/dCo60QA5zFr8fbyInual7xZt+7827YECsipXIgbsA3rT4ovEs2pJmcrS1ckwJMnkeiVaQhnTBsf+DyMEKQ88vDqVXK+cnGCdG7aDQ4BH5Q8khSEvnoUE31xonCGGitek3/OKhOPWocNzJNYibQQMulnM+YHLwQ8YSt8EeICsdvXC9g6wYdl1WvKV7vQEyiU5gU6uAhK1DySGIJnkP/ZBVsC5M0DOatleOGRcr4A68G1NzFtG13aLzERE5uIP0kO5QsLydU2hsz/UQMqIE+TKpAvLhFepmndPh0G42+CbJgaanoHe8UWzS+WBM/FeSJ41e03zsZvNx18gxJUmlp6TMmdbRge8uu5gcLFxite4v78TG7BQ8XJA8C6NVPKiDFLaiJAoxeW7F+RQQb/gjOhCy+04iYJ6P/rbH0AeaUx7seU96Hcf/XKhPRtfvECZaD8Z/3wzyq3dicJTp+/p0veJYpa6vP/R3Sxc3iwxnsjXQ9GzTWA/Qm4NB5HAJnvwhk5ubYYjbhAJRVC75IzDj8Qo66Kr92fXRBD40SleHfMkf3lle7reFSR1jqNIGX5zje+C+d4vL+qiNHFUGcpfrSg4sQy793GVs7rrsHTkqziAepAi7xlpRvK56BQQ6clQAT3LbMfTQr4J4XdWKCHTkqACgIMXlmkKhUEZoBXG6qjUj0JGjAqBw+Ba4s1FBjK5qQwh05AgEVnDoF/TwQaBYXbUaEejIEQgm+qRN3Yd+geJ21QIQ6MgRABr6+Bw3LbmzESBKV6VBBDpyBICLhm9D87QCROqqNIBARw4hqJJDP/RVDKEIXfEFIdCRQwi04Omg4DsbQpG64g0h0JFDAOwi72wIxOqKNoSA5pRlX9uUtUkPSb+G337ytXdXf+fMV3rZDsIh9O7KXcXm/yj3v5rg2VF0wF/HAAAAAElFTkSuQmCC "
        ];
try {
    $merchant = $payarc->applications->retrieve($id);
    $doc = $merchant['data']['add_document']($doc_data);
    echo "Document added: " . json_encode($doc) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

在此示例中，我们搜索所有候选商家，并在系统中最后添加的商家上附加一个文档（Payarc标志），该文档将在注册过程中使用。请参阅文档中关于文档属性的说明。如果文档不再需要，您可以查看以下示例

try{
   $response = $payarc->applications->list();
      $applicant = $response['applications'][0];
      $details = $applicant['retrieve']();
      $document = $details['Documents']['data'][0] ?? null;
      if($document){
          $doc = $document['delete']();
          echo "Document deleted: " . json_encode($doc) . "\n";
      } else {
          echo "No document to delete\n";
      }
}catch (Throwable $e) {
   echo "Error detected: " . $e->getMessage() . "\n";
}

我们再次搜索最后一个候选商家，并移除找到的第一个文档（如果存在）。如果已经知道文档ID，例如在检索候选商家信息时，可以使用

try{
    $id = 'doc_1J*****3';
    $doc = $payarc->applications->delete_document($id);
    echo "Document deleted: " . json_encode($doc) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

签名

作为代理或ISV，一旦Payarc与您的客户之间的合同发送给客户进行签名，流程即完成。一旦收集了所有文档和数据，必须调用候选商家的submit方法，以下是一个示例

try{
    $id = 'app_1J*****3';
    $applicant = $payarc->applications->submit($id);
    echo "Applicant submitted for signature: " . json_encode($applicant) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

分割支付

作为ISV，您可以创建活动来管理您处理商家的财务细节。在SDK中，表示此功能的对象是split_campaigns，该对象具有创建、列表、更新活动的函数。以下是与活动操作相关的示例。

列出所有活动

查询您代理的所有可用活动

try{
    $campaigns = $payarc->split_campaigns->list();
    echo "Campaigns retrieved: " . json_encode($campaigns) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

结果返回一个活动列表。基于此列表，您可以更新详细信息

列出所有处理商家

使用此功能获取处理商家的集合。之后，您可以将其分配给活动

try{
    $merchants = $payarc->split_campaigns->list_accounts();
    echo "Merchants retrieved: " . json_encode($merchants) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

创建和检索活动的详细信息

使用此功能创建新活动

try{
    $campaign = $payarc->split_campaigns->create(
        [
            'name'=> 'Mega bonus',
            'description'=> "Compliment for my favorite customers",
            'notes'=> "Only for VIPs",
            'base_charge'=> 63.33,
            'perc_charge'=> 5.7,
            'is_default'=> '0',
            'accounts'=> []
        ]
    );
    echo "Campaign created: " . json_encode($campaign) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

结果返回新活动，使用它作为object_id的引用对象。如果您需要查询活动的详细信息，请参阅以下示例。

try{
    $id = 'cmp_o3**********86n5';
    $campaign = $payarc->split_campaigns->retrieve($id);
    echo "Campaign retrieved: " . json_encode($campaign) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

更新活动详细信息

如果您需要更新活动的详细信息，请使用update函数。以下示例中，您可以通过ID或作为对象引用活动。

 try{
    $payload = [
        'notes'=> "new version of notes"
    ];
    $campaign = $payarc
        ->split_campaigns
        ->update($id, $payload);
    echo "Campaign updated: " . json_encode($campaign) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

设置周期性支付

循环付款，也称为订阅计费，对于任何需要定期自动向客户计费的服务型业务至关重要。通过我们的SDK设置循环付款，您可以让客户轻松管理订阅计划，确保收入流的及时和一致性。此设置包括创建订阅计划、管理客户订阅和处理自动计费周期。以下是我们如何使用我们的SDK将循环付款集成到您的应用程序中的步骤。

创建订阅计划

设置循环付款的第一步是创建订阅计划。这些计划定义了计费频率、价格以及任何试用期或折扣。使用我们的SDK，您可以创建多个订阅计划，以满足不同客户的需求。以下是如何创建计划的示例

try{
    $data = [
            'name' => 'Monthly billing regular',
            'amount' => 999,
            'interval' => 'month',
            'statement_descriptor' => '2024 MerchantT. srvces'
     ];
    $plan = $payarc->billing->plan->create($data);
    echo "Plan created: " . json_encode($plan) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

在此示例中，通过属性name创建一个新的计划，必须提供计划的客户友好名称。属性amount是美分的数字。在interval中，您指定请求收费发生的频率。在statement_descriptor中的信息将显示在支付请求的理由中。有关更多属性和详细信息，请参阅API文档。

更新订阅计划

一旦创建了计划，有时需要更改其中的详细信息。SDK允许您操作对象plan或通过ID引用对象。以下是如何更改计划详情的示例

try{
    $plans = $payarc->billing->plan->list();
    $plan = $plans['plans'][0];
    if($plan){
        $plan = $plan['update'](['name'=> 'New plan name']);
        echo "Plan updated: " . json_encode($plan) . "\n";
    }
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

已知ID时更新计划

try{
    $id = 'plan_3aln*******8y8';
    $plan = $payarc->billing->plan->update($id, ['name'=> 'New plan name']);
    echo "Plan updated: " . json_encode($plan) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

创建订阅

创建了订阅计划后，下一步是管理客户订阅。这包括将客户订阅到他们选择的计划以及管理他们的计费信息。我们的SDK使这些任务变得容易处理。以下是如何将客户订阅到计划的示例

通过plan对象创建订阅

try{
    $plans = $payarc->billing->plan->list(['search'=> 'iron']);
    $subscriber = [
        'customer_id'=> 'cus_*******AMNNVnjA',
    ];
    $plans = $plans['plans'];
    if($plans){
        $plan = $plans[0];
        if($plan){
            $subscription = $plan['create_subscription']($subscriber);
            echo "Subscription created: " . json_encode($subscription) . "\n";
        }
    }
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

通过计划ID创建订阅

try{
    $subscriber = [
        'customer_id'=> 'cus_DPNMVjx4AMNNVnjA',
    ];
    $subscription = $payarc->billing->plan->create_subscription($id, $subscriber);
    echo "Subscription created: " . json_encode($subscription) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

此代码使用客户保存的支付方式将其订阅到高级计划。SDK处理其余部分，包括存储订阅详情和安排计费周期。

列出订阅

要收集已创建的订阅，您可以使用方法list，如示例所示

try{
    $subscriptions = $payarc->billing->plan_subscription->list(['limit'=> 3, 'plan'=>'plan_7****f']);
    echo "Subscriptions: " . json_encode($subscriptions) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

更新订阅

要操作订阅，SDK提供了几个方法update和cancel，都可以使用订阅标识符或通过订阅对象使用。这些方法的调用示例

使用ID更新订阅

try{
    $id = 'sub_7****f';
    $subscription = $payarc->billing->plan_subscription->update($id, ['description'=> 'Monthly for VIP']);
    echo "Subscription updated: " . json_encode($subscription) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

使用ID取消订阅

try{
    $id = 'sub_7****f';
    $subscription = $payarc->billing->plan_subscription->cancel($id);
    echo "Subscription canceled: " . json_encode($subscription) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

管理争议

支付处理过程中的争议指的是持卡人对账单上出现的交易的有效性提出质疑的情况。这可能导致退款，即交易金额从商户账户中撤销并退还给持卡人。持卡人在其账户上看到他们认为不正确或未经授权的交易。这可能是由于各种原因，例如欺诈活动、计费错误或对购买的 dissatisfaction。持卡人联系其发卡行以对交易提出争议。他们可能提供他们认为交易无效的详细信息。发卡行调查争议。这可能涉及从持卡人那里收集信息并审查交易细节。发卡行通过卡网络（在你的情况下为Payarc）将争议传达给收单行（商户的银行）。然后，商户必须提供证据以证明交易的有效性，例如收据、运输信息或与客户的通信。根据持卡人和商户提供的证据，发卡行做出决定。如果争议有利于持卡人，则发生退款，并从商户的账户中扣除交易金额并退还给持卡人。如果有利于商户，则交易有效。本文件应帮助您了解如何使用Payarc SDK来管理收费和客户。如果您有任何问题，请参阅Payarc API文档或联系支持。

查询争议

SDK提供了一个列出您争议的功能。您可以通过提供查询参数来指定该函数的约束条件。在没有参数的情况下发送，它将返回过去一个月内的所有争议。

try{
    $cases = $payarc->disputes->list();
    echo "Cases: " . json_encode($cases) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

您可以通过retrieve函数获取争议的详细信息。标识符由list函数返回。

try{
    $id = 'dis_7****f';
    $cases = $payarc->disputes->retrieve($id);
    echo "Case: " . json_encode($cases) . "\n";
}catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

提交案例

为了以您（商户）的喜好解决争议，商户必须提供证据以证明交易的有效性，例如收据、运输信息或与客户的通信。SDK提供了一个add_document函数，允许您提供文件并写入消息以证明您有权保留交易的资金。此函数的第一个参数是用于证据的争议标识符。下一个参数是一个对象，具有以下属性：

  • DocumentDataBase64：用作证据的文件的Base46表示形式
  • text：描述证据的简短文本
  • mimeType：提供的文件类型
  • message：提交案例的描述。有关参数及其属性的更多信息，请参阅文档。
$document_base64 = "iVBORw0KGgoAAAANSUhEUgAAAIUAAABsCAYAAABEkXF2AAAABHNCSVQICAgIfAhkiAAAAupJREFUeJzt3cFuEkEcx/E/001qUQ+E4NF48GB4BRM9+i59AE16ANlE4wv4Mp5MjI8gZ+ONEMJBAzaWwZsVf2VnstPZpfb7STh06ewu5JuFnSzQ8d5vDfiLa3sHcHiIAoIoIIgCgiggitwbWM/f2vniTe7NoIZ7Dz9Y0X0qy7NHYfbLtn6dfzOoYXPlUl4+IIgCooGXj10ngzM77p81vVmY2Y9vL+xi9Tn4f41HYVZYx3Wb3yws9oWBlw8IooAgCgiigCAKCKKAIAoIooAgCoikGU3nqpvy3qesPvv6+/2+LZfLpHUcsrrPD0cKCKKAIAoIooAgCgiigCAKCOecs7q3iJXbZDLZWVaWZfR4733lLbfZbBbchzZvvV4vy+PmSAFBFBBEAUEUEEQBQRQQRAFR5DzfD81FxMxVpMg9l3HT938fjhQQRAFBFBBEAUEUEEQBQRQQRe5z7SptnYejGkcKCKKAIAoIooAgCgiigCAKiKQoYj6bMB6Pd8aMRqPoz22kfCalzfmXm45nDoIoIIgCgiggiAKCKCCIAiJrFKnfTxHS9vdX5P7+ibZwpIAgCgiigCAKCKKAIAoIooDomNl2352hc+WY3+NYzyf2c345V3EyGNmdwevo8anbr3Lbfu/j+9fndrH69Ofv+48+WtF9JuM4UkAQBQRRQBAFBFFAEAUEUUBUfo9m6jUPzjl7eWr26vRyWVmW9u59GT2+Suo1B4vFImn8/4ojBQRRQBAFBFFAEAUEUUAQBUTHe7/3eorUeYrQ9RSprmP/UtZ/6OP/xfUUqI0oIIgCgiggiqY36Ddz25x/uZZ1PXmcNj60H6H1H/p4sV1F/VvjZx84HJx9IFrl733wexy3U/b3FO7ogR0dD7OsezqdVt4/HFZvNzQ+t9T9C40P6ty9erElfEKsbblnDHNrekYzFu8pIIgCgiggiAKCKCAqzz5Ccr+7T3133fb1DG0//ro4UkAQBQRRQBAFBFFAEAXEb3wL3JblytFeAAAAAElFTkSuQmCC";
try {
    $case = $payarc->disputes->add_document('dis_MV***********AW0', [
        'DocumentDataBase64' => $document_base64,
        'text' => 'test doc evidence 3'
    ]);
    echo "Document added: " . json_encode($case) . "\n";
} catch (Throwable $e) {
    echo "Error detected: " . $e->getMessage() . "\n";
}

许可证 MIT