README

简介
- 工作原理
集成链接
创建用户数据
创建高级应用程序
将文档附加到高级应用程序

简介

欢迎！我们非常感谢您对 Payfully 平台的关注！在本指南中，我们将带您了解我们的集成功能。

如果您有任何问题，请随时联系我们。

工作原理

我们提供 URL 生成器，它将根据提供的信息创建一个高级应用程序。如果用户在我们的平台上不存在，我们将自动创建它。

Payfully 有两个（2）环境

生产：实时环境
预发布：测试环境

我们将为您提供测试环境的密钥，当集成准备就绪时，我们将发送生产环境的密钥。

说明

您需要获取特定环境的凭证： relativeUrl 和 aesKey。
收集所需信息（用户、应用程序和文档）。
将每个组件添加到 $urlGenerator。
生成一个特殊 URL（称为 IntegrationURL）。
将它们放置在您的平台上，以便代理可以点击。

当登录到您的平台的代理（用户）点击链接时，他们将被重定向到 Payfully，我们将自动登录代理（并在需要时创建账户）。最后，高级应用程序也将同时自动生成。代理只需填写通过链接生成器未提供的信息。

重要：集成 URL 应被视为敏感信息，不应向除用户（为这些用户生成）之外的人透露。因为使用集成 URL 可以登录 Payfully 账户。

集成链接

生成的集成 URL 看起来像

https://<环境>.payfully.co/integrations/[relativeUrl]/[encodedData]

**relativeUrl**：这是为我们特定环境提供的。
**encodedData**：这是首先进行 AES 加密 然后 Base64 编码 的 JSON 数据。

一个示例集成 URL 看起来像

https://integration-stage.payfully.co/integrations/SuperAgency/VTJGc2RHVmtYMTlDSlo0Uk16TjJKOFZNZU4rcmc3VWNobUVXMjNtQzQ4ST0=

数据结构

URLGenerator 期望您传递以下数据

$urlgenerator->setUser([...]);
$urlgenerator->setApplication([...]);
$urlgenerator->setDocuments([...]);

请参阅特定部分以获取更多详细信息

用户
应用程序
文档

凭证说明

为了生成集成 URL，您需要获取以下凭证

relativeUrl：由我们提供。
aesKey：- 用于加密数据的 AES 密钥。也由我们提供。

请立即联系 Payfully 管理员，以防泄露/受损。管理员将旋转密钥并向您提供新密钥。

生成集成 URL

说明

将库添加到 composer。

composer require payfully/integrator

实例化库对象，并在构造函数内设置 relativeUrl、aesKey 和 Env 值。

require __DIR__ . '/vendor/autoload.php';

use Payfully\Integrator\UrlGenerator;
use Payfully\Integrator\Env;

$relativeUrl = 'SuperAgency';
$aesKey = "Qkoghsks1Oe3V+/s+wtV6b1FFmM+YdQCg0mGPTiO3xofssrcsgR6yA3rvsSIyq/85DiHm/7BIbrEg1GOL1soag==";
$urlgenerator = new UrlGenerator($relativeUrl, $aesKey, Env::Stage);

注意：可能的环境值有

Env::Stage
Env::Production

如果没有设置环境，则我们假设它是 production

构建一个包含所需数据的 PHP 数组，并将数据设置到每个部分。

$urlgenerator->setUser([...]);
$urlgenerator->setApplication([...]);
$urlgenerator->setDocuments([...]);

最后调用方法 generate()

echo $urlgenerator->generate();

以下是一个完整的示例

require __DIR__ . '/vendor/autoload.php';

use Payfully\Integrator\UrlGenerator;
use Payfully\Integrator\Env;

$relativeUrl = 'SuperAgency';
$aesKey = "Qkoghsks1Oe3V+/s+wtV6b1FFmM+YdQCg0mGPTiO3xofssrcsgR6yA3rvsSIyq/85DiHm/7BIbrEg1GOL1soag==";
$urlgenerator = new UrlGenerator($relativeUrl, $aesKey, Env::Stage);
$urlgenerator->setUser([...]);
$urlgenerator->setApplication([...]);
$urlgenerator->setDocuments([...]);

echo $urlgenerator->generate();

上述代码输出


https://integration-stage.payfully.co/integrations/SuperAgency/VTJGc2RHVmtYMS9EY0FEdnJ0MFdhSkJqdGlIYXB1ZVF5cWE2VkpYSXhiTT0=

注意：已在 PHP v7.1 上测试

用户数据

所需数据

每个集成 URL 必须包含用户信息。

$user = [
  "email"=> "...", // (required) [string] Agent's email
  "fullName" => "...", // (required) [string] Agent's full name
  "phone" => "..." // (required) [string] Agent phone number; Must be a valid US phone number; Format: '+19179246228'
];

我们将根据这些数据创建一个 Payfully 账户。

注意

密码将生成并通过电子邮件发送，包括重置密码链接。
如果该电子邮件地址的用户已经存在并且在集成中创建过，我们将直接登录用户。（例如，如果经纪人两次或更多次遵循相同的集成 URL，则可能会发生这种情况）

高级应用程序数据

如果您有交易的内部 MLS ID，请将其作为 dealInformation['mlsId'] 提供。这用于避免重复高级应用程序。如果缺少 mlsId，它将由 dealInformation['closingDate'] 和 dealInformation['propertyAddress'] 组合自动生成。

未由集成 URL 提供的任何可选数据都可以稍后手动填写。

所需数据

$application = [
  'shareOfCommission' => ..., // (optional) [number] - Commission ammount expected by the Agent for the deal
  'dealInformation' => [
    'propertyAddress' => "...", // (optional) [string] - Address of the property
    'propertyType' => "...", // (optional) [string] - Type of property
    'isNewConstruction' => true/false, // (optional) [boolean] - Is it a new contruction?
    'isShortSale' => true/false, // (optional) [boolean] - Is it a short sale?
    'ratificationDate' => "...", // (optional) [string] ISO 8601 Date String - Date in which al contingencies are met
    'closingDate' => "...", // (optional) [string] ISO 8601 Date String - Closing date of the contract
    'mlsId' => "..." // (optional) [string] - MLS ID
  ],
  'agentInformation' => [
    'represents' => "...", // (optional) [string] - Who does the agent represents on this deal (see below)
    'completedTransactions' => ..., // (optional) [number] - Completed transactions by the agent in the last 6 months
    'pendingContracts' => ..., // (optional) [number] - Number of Agent's pending contracts at the moment
    'activeListings' => ..., // (optional) [number] - Number of Agent's active listings at the moment
    'licenseNumber' => "..." // (optional) [string] - Agent's license number
  ]
];

agentInformation['represents'] 只能是以下之一

'Listing'
'Buying'
'Both'

dealInformation['propertyType'] 应该是以下之一

'Condo'
'Co-op'
'Single-Family'
'Multi-Family'
'Townhouse'
'Manufactured Home'
'Half Duplex'
'Mobile Home'
'Other' - 提供字符串

将文档附加到高级应用程序

集成 URL 数据中的 documents 属性允许将文档附加到高级应用程序。如果此对象为空，经纪人将需要在我们的平台上上传所有文档。

该文档对象看起来像

$documents = [
  [
    "type" => "..." // (required) [string] Document type. Please find the list of available document types below.
    "url" => "..." // (required) [string] A URL for a direct document download. HTTP GET is used to fetch the document.
  ],
  [ ... ]
];

文档类型应该是以下之一

"idDocuments" - 您可以在此处上传最多 2 个同类型的文档
"contract" - 销售合同
"commission_report" - 经纪人的佣金报告
"agreement" - 特定列表的 MLS 协议
"money_deposit" - 认证金存款
"pre_approval_letter" - 买家的预批准信
"inspection_report" - 包含检查报告的文档
"bank_approval" - 贷款的银行批准

注意：文档将在单独的过程中下载。这是在后台进行的。当经纪人访问 Payfully 网站时，他将收到文档正在加载的通知。

此外，如果任何文档下载失败，经纪人在 Payfully 网站上可以进行手动上传。

payfully / integrator

维护者

详细信息

README

简介

工作原理

集成链接

数据结构

凭证说明

生成集成 URL

用户数据

所需数据

高级应用程序数据

所需数据

将文档附加到高级应用程序