README

欢迎来到Jibimo API的PHP库，此库将使您的支付开发变得轻而易举！

🎁 快速入门

实际上，这个库是围绕Jibimo主要REST API的通用包装器。因此，它将提供几个数据模型对象和服务，以方便在PHP中使用Jibimo API。

此外，此库提供了一种简单的异常处理机制，您可以使用它轻松地找到与Jibimo REST API通信的问题。

以下是如何使用此包的快速入门指南

🎩 安装

只需使用以下composer命令安装此包

composer require puresoft/jibimo-api --prefer-stable

这将检查库的必需组件并将它们与库本身一起安装。

💵 向人们请求金钱

要使用Jibimo金钱请求API，您首先应启动交易并将用户重定向到网关，从网关返回后，您必须验证交易。如果交易有效且被接受，则一切就绪，用户已正确收到付款。

以下是指示

👍 启动交易并将用户重定向到网关

使用以下代码启动请求交易并将用户重定向到网关

$baseUrl = "https://jibimo.com/api";
$token = "..."; // You should obtain this token from your Jibimo panel

$mobile = "09366061280";
$amountInToman = 8500;
$privacyLevel = JibimoPrivacyLevel::PUBLIC;
$trackerId = "xxxx"; // Anything like a factor number or maybe a UUID, it's up to you
$description = "Thank you for using our service :)"; // Optional, this will show up in Jibimo feed
$returnUrl = "http://mywebsite.com/callback/?something=somethingelse"; // Optional, after paymnt, Jibimo will redirect user to this URL. If you omit it, Jibimo will redirect user to your company homepage

$response = Jibimo::request($baseUrl, $token, $mobile,
            $amountInToman, $privacyLevel, $trackerId, $description, $returnUrl);

// Status of transaction must be `Pending`
if(JibimoTransactionStatus::PENDING === $response->getStatus()) {

    // Save Jibimo transaction ID to database or whatever to use that to verify transaction later
    // $response->getTransactionId();

    // Now, redirect user to Jibimo gateway
    $redirect = $response->getRedirectUrl();
    header("Location: $redirect");
    exit();
}

将用户重定向到Jibimo网关后，他们将看到一个网页，通过Jibimo账户或普通银行网关向您付款。

✔️ 验证请求交易

之后，他们将返回到您提供的 $returnUrl，您可以在那里验证他们的交易。

$baseUrl = "https://jibimo.com/api";
$token = "..."; // You should obtain this token from your Jibimo panel

$transactionId = X; // You should get this transaction ID from where you saved it when you were creating the request in the previous step
$mobile = "09366061280";
$amountInToman = 8500;
$trackerId = "xxxx"; //Tracker ID of main transaction


$validationResult = Jibimo::validateRequest($baseUrl, $token, $transactionId,
            $mobile, $amountInToman, $trackerId);

// Validate and check status of transaction in Jibimo
if($validationResult->isAccepted()) {
    // Transaction was successful, user paid money correctly
}
// Otherwise, there is a problem. You can get raw response or handle exceptions to find out why there is still problem

💲 向人们支付金钱

使用Jibimo支付API非常简单。

只需支付并验证即可。没有像向用户显示网关或执行其他操作之类的额外步骤。

📫 使用Jibimo Pay API

使用以下代码向可能已注册在Jibimo中或未注册的移动号码支付。如果移动号码已在Jibimo中注册，则资金将立即转账到其Jibimo账户，否则将挂起，直到用户在Jibimo中注册。他们将通过Jibimo收到短信通知付款。

$baseUrl = "https://jibimo.com/api";
$token = "..."; // You should obtain this token from your Jibimo panel

$mobile = "09366061280";
$amountInToman = 8500;
$privacyLevel = JibimoPrivacyLevel::PUBLIC;
$trackerId = "xxxx"; // Anything like a factor number or maybe a UUID, it's up to you
$description = "Thank you for using our service :)"; // Optional, this will show up in Jibimo feed


$response = Jibimo::pay($baseUrl, $token, $mobile,
            $amountInToman, $privacyLevel, $trackerId, $description);

// Here you should save transaction ID to verify it later
// $response->getTransactionId();

if(JibimoTransactionStatus::ACCEPTED === $response->getStatus()) {
    // Money was paid immediately
} else if(JibimoTransactionStatus::PENDING === $response->getStatus()) {
    // The user was not registered in Jibimo, so it will be pending until user being registered in Jibimo
}

// For other problems and errors, you can see the raw response or catch exceptions

✔️ 验证支付交易

验证支付交易很简单。您可以使用以下代码

$baseUrl = "https://jibimo.com/api";
$token = "..."; // You should obtain this token from your Jibimo panel

$transactionId = X; // You should get this transaction ID from where you saved it when you were creating the request in the previous step
$mobile = "09366061280";
$amountInToman = 8500;
$trackerId = "xxxx"; // Tracker ID of main transaction


$validationResult = Jibimo::validatePay($baseUrl, $token, $transactionId,
            $mobile, $amountInToman, $trackerId);

// Validate and check status of transaction in Jibimo
if($validationResult->isAccepted()) {
    // Transaction was successful, user received money
}
// Otherwise, there is a problem. You can get raw response or handle exceptions to find out why there is still problem

🚄 扩展支付即直接支付API

使用Jibimo 扩展支付 API，您可以使用人们的移动号码和IBAN（Sheba）号码的组合直接向他们的银行账户支付。

此方法与正常付款的区别在于IBAN（Sheba）号码以及扩展付款，资金将直接转入用户的原始银行账户，而在正常付款中，则会转入用户的Jibimo账户。因此，如果用户未在Jibimo注册，即使不与Jibimo的任何服务联系，也可以收到资金。

🌈 使用Jibimo扩展支付API

使用以下代码向一个手机号码和IBAN（Sheba）号码组合进行付款，这些号码可能已在Jibimo注册，也可能没有。在此方法中，资金将通过Paya直接转入用户的原始银行账户。

$baseUrl = "https://jibimo.com/api";
$token = "..."; // You should obtain this token from your Jibimo panel

$mobile = "09366061280";
$amountInToman = 8500;
$iban = "IR140570028870010133089001"; // This is my real IBAN(Sheba), so keep your head up to not pay to it mistakenly, I will not return back your money to you ! :D
$privacyLevel = JibimoPrivacyLevel::PUBLIC;
$trackerId = "xxxx"; // Anything like a factor number or maybe a UUID, it's up to you
$description = "Thank you for using our service :)"; // Optional, this will show up in Jibimo feed
$name = "حسام"; // Optional, The first name of IBAN(Sheba) owner
$family = "غلامی"; // Optional, The last name of IBAN(Sheba) owner

$response = Jibimo::extendedPay($baseUrl, $token, $mobile,
            $amountInToman, $privacyLevel, $iban, $trackerId,
            $description, $name, $family);

// Here you should save transaction ID to verify it later
// $response->getTransactionId();

if(JibimoTransactionStatus::ACCEPTED === $response->getStatus()) {
    // Money was paid successfully
}

// For other problems and errors, you can see the raw response or catch exceptions

✔️ 验证扩展支付交易

验证扩展支付交易非常简单。您可以使用以下代码

$baseUrl = "https://jibimo.com/api";
$token = "..."; // You should obtain this token from your Jibimo panel

$transactionId = X; // You should get this transaction ID from where you saved it when you were creating the request in the previous step
$mobile = "09366061280";
$amountInToman = 8500;
$trackerId = "xxxx"; // Tracker ID of main transaction


$validationResult = Jibimo::validateExtendedPay($baseUrl, $token, $transactionId,
            $mobile, $amountInToman, $trackerId);

// Validate and check status of transaction in Jibimo
if($validationResult->isAccepted()) {
    // Transaction was successful, user received money
}
// Otherwise, there is a problem. You can get raw response or handle exceptions to find out why there is still problem

就这些了！希望这个快速入门能帮助您快速上手。

如果您在此软件包中发现任何问题，请随时提交问题。

📃 Jibimo API规范

为了更好地理解Jibimo API规范，您可以查看其API文档，文档可在https://jibimo.com/api/documentaion找到。但在这里，您可以找到一份简单的速查表来使用。

🎭 隐私级别

Jibimo有3个隐私级别来向用户展示交易。

😃 个人

这意味着交易只对参与其中的双方可见，即付款人和收款人。所以只有这两个人能看到这笔交易。

👪 朋友

这意味着交易不仅对参与其中的双方可见，还包括他们的朋友，即付款人和收款人以及付款人的Jibimo朋友和收款人的Jibimo朋友。

注意	在此隐私级别中，交易金额对付款人和收款人以外的人不可见。

🏦 公开

这意味着任何在Jibimo注册的人都可以看到这笔交易。所以它可以是推广您产品在社交媒体上的一个很好的点。

注意	在此隐私级别中，交易金额对付款人和收款人以外的人不可见。

🚦 交易状态

在Jibimo API中，交易有三种不同的状态。

⛔️ 已拒绝

这意味着一方拒绝接受交易或交易存在问题。

例如，在请求金钱API中，如果用户点击取消按钮，交易状态将被设置为“已拒绝”。或者如果您向无效的IBAN(Sheba)号码付款，交易状态将在银行对Jibimo的失败响应后设置为“已拒绝”。

🕞 待处理

此状态意味着交易正在等待其他事件的发生。

例如，如果您使用正常支付API向未在Jibimo注册的用户付款，交易将待处理，直到用户加入Jibimo。

✅ 已接受

此状态意味着交易成功，一切顺利。

📱 手机号码格式

本包将尝试将您的手机号码标准化，以满足 Jibimo API 的要求。

在 Jibimo API 中，手机号码必须符合以下格式

+989366061280

但在这个包中，您也可以使用以下格式

9366061280 09366061280 989366061280 +989366061280

所有上述格式都受支持。

📊 IBAN (Sheba) 格式

和手机号码一样，这个包也会尝试标准化您的 IBAN(Sheba) 号码。

在 Jibimo API 中，IBAN(Sheba) 号码必须符合以下格式

140570028870010133089001

但在这个包中，您可以使用两种格式，无论是否以 IR 开头

140570028870010133089001 IR140570028870010133089001