README

这是一个简单的库，用于将 Laravel 与您的 PHP 代码集成。请注意，此库正处于非常早期的开发阶段，只有最基本的功能可用，并且尚未进行彻底测试以确保可靠的功能。

安装

通过 Composer

$ composer require ratapay/ratapayphp

然后在您的项目中要求自动加载

require_once "vendor/autoload.php";

当使用如 Laravel 这样的框架时，通常不需要上面的 require。因为框架已经设置了它们的包加载器。

用法

1. 密钥和秘密

在您可以使用此库之前，您需要一个 Ratapay 账户，至少是个人级别账户。

密钥和秘密可以从账户页面 -> 个人资料 -> 查看凭据菜单中获取

2. 发票

发票是 Ratapay 中创建交易的必要条件。交易将仅通过定义的发票来创建。

使用以下方式实例化：

$invoice = new \ratapay\ratapayphp\Invoice($data);

其中 $data 是一个数组，包含以下属性中定义的数据的键值格式

属性

first_period、second_period 和 refund_threshold 使用以下格式的周期格式：

[1-9][D/M/Y]

其中第一部分是分子，第二部分是单位，可以是天（D）、月（M）或年（Y）

例如，7 天的周期将是 7D

要查看可用的支付系统 ID（paysystem）列表，请向以下链接发送 GET 请求：[https://api.ratapay.co.id/v2/gateway/list](https://api.ratapay.co.id/v2/gateway/list)（生产环境）或 [https://dev.ratapay.co.id/v2/gateway/list](https://dev.ratapay.co.id/v2/gateway/list)（沙盒环境）

方法

3. 商品

商品定义了发票内容的详细信息。

使用以下方式实例化：

$item = new \ratapay\ratapayphp\Item($data);

其中 $data 是一个数组，包含以下属性中定义的数据的键值格式

属性

4. 受益人

受益人定义了谁将从发票交易中获得份额。

使用以下方式实例化：

$beneficiary = new \ratapay\ratapayphp\Beneficiary($data);

其中 $data 是一个数组，包含以下属性中定义的数据的键值格式

属性

5. 客户

客户将处理发送到 Ratapay 的请求

使用以下方式实例化：

$client = new \ratapay\ratapayphp\Client($merchant_id, $merchant_secret, $api_key, $api_secret, $sandbox);

除了 $sandbox 以外的每个参数的数据都可以从第 1 点“密钥和秘密”中获取。

而 $sandbox 是一个标志，用于定义是否使用沙盒模式，默认为 true。

A. 创建交易

$result = $client->createTransaction($invoice);

其中 $invoice 是之前已定义的发票对象

$result 将是一个包含以下数据的对象：

1. status：成功或失败，表示交易创建结果状态
2. message：交易创建失败的原因的错误消息，仅在状态为失败时可用
3. payment_url：付款过程的 URL，只有当状态为成功时才可用
4. data：表示交易基于哪个发票的字符串数组，包含：invoice_id、note 和 ref 作为 Ratapay 的参考号，仅在状态为成功时才可用

B. 列出交易

$result = $client->listTransaction($reference = '', $invoice_id = '', $creation_time = [], $paid_time = [], $offset = 0, $limit = 5);

$result 将是一个包含以下数据的对象：

1. status：成功或失败，表示交易列出结果状态
2. list：检索到的交易数据列表
3. count：具有指定条件的交易记录总数
4. totalAmount：检索到的交易记录的总金额

C. 执行拆分

通常，如果已超过退款阈值，可退款的发票资金将自动拆分。但是，如果需要提前拆分，可以使用此功能。

$result = $client->confirmSplit($reference, $item_ids = []);

如果指定了 item_ids，则仅拆分匹配的商品。

D. 延长退款

可以用来扩展退款阈值。

$result = $client->extendRefund($reference, $period, $item_ids = []);

如果指定了item_ids，则只有匹配的项的退款阈值将被扩展。

E. 执行退款

可以用来在退款阈值之前执行退款。

$result = $client->confirmRefund($reference, $params);

$result 将是一个包含以下数据的对象：

1. status：成功或失败，表示退款请求状态

如果执行全额退款，则不需要使用params参数。但如果执行部分退款，则应使用以下结构填充params参数

• 用于对整个发票部分退款的params结构，使用项目ID 0

$params = [
        0 => [
            'type' => {% or $}
            'value' => {value}
        ]
]

• 用于对每个特定项目部分退款的params结构

$params = [
        {item_id_1} => [
            'type' => {% or $} // optional, default $, will be ignored if specified but using qty
            'value' => {value}, // required if no qty specified
            'qty' => {qty} // required if no value specified
        ],
        {item_id_n} => [
            'type' => {% or $}, // optional, default $, will be ignored if specified but using qty
            'value' => {value}, // required if no qty specified
            'qty' => {qty} // required if no value specified
        ]
]

%表示百分比，最大100%

$表示金额，最多为项目小计金额

F. 获取自身账户信息

$result = $client->getAccount();

$result 将是一个包含以下数据的对象：

1. status：成功或失败，表示获取账户信息状态
2. account：账户信息详情

G. 注册新账户

$result = $client->registerAccount(['email'=>$email,'name'=>$name,'password'=>$password]);

$result 将是一个包含以下数据的对象：

1. status：成功或失败，失败表示已存在具有该电子邮件的账户
2. account：如果账户创建状态为成功，则账户信息详情
3. error：关于错误的简要信息
4. message：详细的错误信息

H. 获取其他账户信息

$result = $client->getAccount(['email' => $email]);

$result 将是一个包含以下数据的对象：

1. status：成功或失败，表示获取账户信息状态
2. account：如果请求状态成功，则账户信息详情
3. error：关于错误的简要信息
4. message：详细的错误信息

如果error是'none'或'waiting'，则需要通过执行以下方法让用户同意将他们的账户链接到您的商户数据

$result = $client->linkAccount($email, $username);

$username是可选的，如果您的系统通过用户名识别用户并且用户更改了电子邮件，则可以使用它来跟踪用户。$result将是一个包含以下数据的对象

1. status：成功或失败，表示获取账户信息状态
2. link：到ratapay同意页面的链接以批准链接
3. error：关于错误的简要信息
4. message：详细的错误信息

I. 添加新受益人

新受益人只能添加到现有的发票项目。因此，请确保准备有剩余份额金额的项目或专门为新受益人准备的项目。

$result = $client->addBeneficiaries($ref, $beneficiaries);

$ref是交易参考代码

$beneficiaries是要添加的新受益人数据的列表

$result 将是一个包含以下数据的对象：

1. status：成功或失败

沙箱

在沙箱模式下，可以通过访问沙箱支付模拟页面来模拟支付。

输入支付参考编号，然后点击支付以模拟交易支付。

默认支付方法将使用Ratapay余额，因此如果测试账户在其账户中没有余额，则支付将失败。因此，首先通过访问交易创建结果中定义的payment_url打开支付说明，然后在尝试模拟支付之前选择首选的支付方式。

回调

Ratapay在特定事件上发送POST回调，其中包含以下数据

要验证数据与散列值，请使用具有sha256算法和商户密钥作为散列键的hash_hmac函数。

示例

$valid = hash_equals($_POST['hash'], hash_hmac('sha256', $_POST['data'], $merchant_key));

数据包含以下信息

**动作列表**

测试

$ phpunit

贡献

有关详细信息，请参阅贡献。

信用

• Ratapay
• 所有贡献者

许可

MIT许可（MIT）。请参阅许可文件以获取更多信息。