README

此包允许开发人员轻松与YouCan Pay API交互。

本文档分为两个集成部分：默认集成和独立集成。您可以选择在结账页面进行一个或两个集成。

YouCan Pay SDK 配置

将 YouCan Pay SDK 添加到您的 PHP 应用程序的说明。

步骤 1. 要求

YouCan Pay 账户。
在设置 > API 密钥中可用的您의 YouCan Pay private_key 和 public_key。
Visual Studio Code 或 Sublime Text 或任何 IDE。
具有 SSL 的网站，如果您想使用支付默认模式，则必须需要。
在您的开发环境中已安装 Composer。

步骤 2. 添加 YouCan Pay SDK

打开您的 PHP 项目，添加以下内容。

运行此命令以下载并包含 YouCan Pay PHP SDK 到您的项目中。如果您无法安装 composer，您可以从 GitHub https://github.com/NextmediaMa/youcan-payment-php-sdk/archive/refs/heads/master.zip 手动下载 SDK。

composer require youcanpay/payment-sdk

步骤 2.1 YouCan Pay: 默认集成

以下是一个关于如何快速开始使用 YouCan Pay JS 集成的指南，您可以通过此链接查看完整的文档。

您可以直接在您的网站上进行支付，并可以选择 DOM 中的位置。

如果您选择使用 JS 集成，您必须在生产模式下运行 SSL 证书。

2.1.1: 在 <head>...</head> 之间复制此 JS 脚本

<script src="https://pay.youcan.shop/js/ycpay.js"></script>

2.1.2: 选择您想显示支付信息（全名、卡号、CCV...）的位置，必须放在 <body>...</body> 标签之间。

<div id="payment-card"></div>
<button id="pay">Pay</button>

2.1.3: 在 ...</body> 标签之前添加此代码。

<script type="text/javascript">
  // Create a YouCan Pay instance.
  const ycPay = new YCPay(
    // String public_key (required): Login to your account.
    // Go to Settings and open API Keys and copy your key.
    "public_key",
    // Optional options object
    {
      formContainer: "#payment-card",
      // Defines what language the form should be rendered in, supports EN, AR, FR.
      locale: "en",

      // Whether the integration should run in sandbox (test) mode or live mode.
      isSandbox: false,

      // A DOM selector representing which component errors should be injected into.
      // If you omit this option, you may alternatively handle errors by chaining a .catch()
      // On the pay method.
      errorContainer: "#error-container",
    }
  );

  // Select which gateways to render
  ycPay.renderAvailableGateways(["CashPlus", "CreditCard"]);

  // Alternatively, you may use gateway specific render methods if you only need one.
  ycPay.renderCreditCardForm();
</script>

2.1.4: 令牌化步骤：此令牌包含所有订单信息。

<?php

use YouCan\Pay\YouCanPay;

class ExamplePayment
{
    /**
     * Return a token to make payment for an order, this token is required to make payment with JS script.
     *
     * @return string
     */
    public function createToken()
    {
        // Enable sandbox mode, otherwise delete this line.
        YouCanPay::setIsSandboxMode(true);

        // Create a YouCan Pay instance, to retrieve your private and public keys login to your YouCan Pay account
        // and go to Settings and open API Keys.
        $youCanPay = YouCanPay::instance()->useKeys('my-private-key', 'my-public-key');

        // Data of the customer who wishes to make this purchase.
        // Please keep these keys.
        $customerInfo = [
            'name'         => '',
            'address'      => '',
            'zip_code'     => '',
            'city'         => '',
            'state'        => '',
            'country_code' => '',
            'phone'        => '',
            'email'        => '',
        ];

        // You can use it to send data to retrieve after the response or in the webhook.
        $metadata = [
            // Can you insert what you want here...
            //'key' => 'value'
        ];

        // Create the order you want to be paid
        $token = $youCanPay->token->create(
            // String orderId (required): Identifier of the order you want to be paid.
            "order-id",
            // Integer amount (required): The amount, Example: 25 USD is 2500.
            "2000",
            // String currency (required): Uppercase currency.
            "USD",
            // String customerIP (required): Customer Address IP.
            "123.123.123.123",
            // String successUrl (required): This URL is returned when the payment is successfully processed.
            "https://yourdomain.com/orders-status/success",
            // String errorUrl (required): This URL is returned when payment is invalid.
            "https://yourdomain.com/orders-status/error",
            // Array customerInfo (optional): Data of the customer who wishes to make this purchase.
            $customerInfo,
            // Array metadata (optional): You can use it to send data to retrieve after the response or in the webhook.
            $metadata
        );

        return $token->getId();
    }
}

2.5: 使用 SDK 的 createToken() 创建令牌，并将其插入到 JS 脚本中，此令牌包含有关此付款的所有信息。

当买家点击“支付”按钮时，下面的 JS 代码运行，您会在您在令牌化步骤中定义的 successUrl 或 errorUrl 中收到一个 GET 响应。

<script type="text/javascript">
  // Start the payment on button click
  document.getElementById("pay").addEventListener("click", function () {
    // Execute the payment, it is required to put the created token in the tokenization step.
    ycPay
      .pay("<?php createToken(); ?>")
      .then(successCallback)
      .catch(errorCallback);
  });

  function successCallback(transactionId) {
    //your code here
  }

  function errorCallback(errorMessage) {
    //your code here
  }
</script>

步骤 2.2 YouCan Pay: 独立集成

2.2.1: 令牌化步骤：此令牌包含所有订单信息。

<?php

use YouCan\Pay\YouCanPay;

class ExamplePayment
{
    /**
     * Return a URL to make payment for an order.
     *
     * @return string
     */
    public function createPaymentURL()
    {
        // Enable sandbox mode, otherwise delete this line.
        YouCanPay::setIsSandboxMode(true);

        // Create a YouCan Pay instance, to retrieve your private and public keys login to your YouCan Pay account
        // and go to Settings and open API Keys.
        $youCanPay = YouCanPay::instance()->useKeys('my-private-key', 'my-public-key');

        // Data of the customer who wishes to make this purchase.
        // Please keep these keys.
        $customerInfo = [
            'name'         => '',
            'address'      => '',
            'zip_code'     => '',
            'city'         => '',
            'state'        => '',
            'country_code' => '',
            'phone'        => '',
            'email'        => '',
        ];

        // You can use it to send data to retrieve after the response or in the webhook.
        $metadata = [
            // Can you insert what you want here...
            //'key' => 'value'
        ];

        // Create the order you want to be paid
        $token = $youCanPay->token->create(
            // String orderId (required): Identifier of the order you want to be paid.
            "order-id",
            // Integer amount (required): The amount, Example: 25 USD is 2500.
            "2000",
            // String currency (required): Uppercase currency.
            "USD",
            // String customerIP (required): Customer Address IP.
            "123.123.123.123",
            // String successUrl (required): This URL is returned when the payment is successfully processed.
            "https://yourdomain.com/orders-status/success",
            // String errorUrl (required): This URL is returned when payment is invalid.
            "https://yourdomain.com/orders-status/error",
            // Array customerInfo (optional): Data of the customer who wishes to make this purchase.
            $customerInfo,
            // Array metadata (optional): You can use it to send data to retrieve after the response or in the webhook.
            $metadata
        );

        return $token->getPaymentURL(
            // lang: Support 3 languages: AR, EN and FR.
            'ar'
        );
    }
}

2.2.2: 在令牌化之后，使用 createPaymentURL() 函数创建的链接并将其集成到您的 DOM 中，或者直接将买家重定向到此 URL。

<a href="<?php createPaymentURL(); ?>">Pay Now</a>

youcanpay / payment-sdk

维护者

详细信息