### Install YouCan Pay SDK via Composer

Source: https://github.com/youcan-shop/youcan-payment-php-sdk/blob/master/README.md

Run this command in your terminal to download and include the SDK in your project.

```bash
composer require youcanpay/payment-sdk
```

--------------------------------

### Initialize YouCan Pay Instance

Source: https://github.com/youcan-shop/youcan-payment-php-sdk/blob/master/README.md

Configure the YCPay instance and render payment gateways before the closing body tag.

```javascript
<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>
```

--------------------------------

### Create Payment URL with YouCan Pay SDK

Source: https://github.com/youcan-shop/youcan-payment-php-sdk/blob/master/README.md

Initializes the SDK with API keys and generates a payment URL for a specific order. Requires setting sandbox mode if testing.

```php
<?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'
        );
    }
}
```

--------------------------------

### Create Payment Token in PHP

Source: https://github.com/youcan-shop/youcan-payment-php-sdk/blob/master/README.md

Initializes the YouCan Pay instance and generates a payment token required for the client-side JS script.

```php
<?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();
    }
}
```

--------------------------------

### Execute Payment with JavaScript

Source: https://github.com/youcan-shop/youcan-payment-php-sdk/blob/master/README.md

Triggers the payment modal using the generated token when the user clicks the pay button.

```html
<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>
```

--------------------------------

### Define Payment UI Elements

Source: https://github.com/youcan-shop/youcan-payment-php-sdk/blob/master/README.md

Place these elements within the <body> tags to define where the payment form and pay button will appear.

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

--------------------------------

### YouCanPay::token->create()

Source: https://github.com/youcan-shop/youcan-payment-php-sdk/blob/master/README.md

Creates a payment token for an order, which is required to generate a payment URL.

```APIDOC
## YouCanPay::token->create()

### Description
Creates a new payment token containing order information, customer details, and metadata. This token is used to generate the final payment URL.

### Parameters
- **orderId** (string) - Required - Identifier of the order.
- **amount** (integer) - Required - The amount to be paid (e.g., 2500 for 25 USD).
- **currency** (string) - Required - Uppercase currency code.
- **customerIP** (string) - Required - Customer's IP address.
- **successUrl** (string) - Required - URL to redirect upon successful payment.
- **errorUrl** (string) - Required - URL to redirect upon payment failure.
- **customerInfo** (array) - Optional - Customer details including name, address, zip_code, city, state, country_code, phone, and email.
- **metadata** (array) - Optional - Custom data to retrieve after response or in webhook.
```

--------------------------------

### YouCanPay::token->create()

Source: https://github.com/youcan-shop/youcan-payment-php-sdk/blob/master/README.md

Creates a payment token required to initiate a transaction via the YouCan Pay JS script.

```APIDOC
## YouCanPay::token->create()

### Description
Generates a payment token that encapsulates order details, customer information, and metadata. This token is required to execute the payment on the client side.

### Method
PHP SDK Method

### Parameters
- **orderId** (string) - Required - Identifier of the order.
- **amount** (integer) - Required - The amount to be paid (e.g., 2500 for 25.00).
- **currency** (string) - Required - Uppercase currency code (e.g., USD).
- **customerIP** (string) - Required - Customer's IP address.
- **successUrl** (string) - Required - URL to redirect upon successful payment.
- **errorUrl** (string) - Required - URL to redirect upon payment failure.
- **customerInfo** (array) - Optional - Customer details including name, address, zip_code, city, state, country_code, phone, and email.
- **metadata** (array) - Optional - Custom data to be retrieved after the response or in webhooks.
```

--------------------------------

### token->getPaymentURL()

Source: https://github.com/youcan-shop/youcan-payment-php-sdk/blob/master/README.md

Retrieves the payment URL from a created token to redirect the buyer.

```APIDOC
## token->getPaymentURL()

### Description
Generates the final payment URL for the customer to complete the transaction.

### Parameters
- **lang** (string) - Required - Language for the payment page (supports 'AR', 'EN', 'FR').
```

--------------------------------

### Integrate Payment Link in HTML

Source: https://github.com/youcan-shop/youcan-payment-php-sdk/blob/master/README.md

Embeds the generated payment URL into an anchor tag for user interaction.

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

--------------------------------

### Include YouCan Pay JS Script

Source: https://github.com/youcan-shop/youcan-payment-php-sdk/blob/master/README.md

Add this script tag within the <head> section of your HTML document.

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.