diff --git a/README.md b/README.md index a83c264..a5d05c5 100755 --- a/README.md +++ b/README.md @@ -7,41 +7,222 @@ License

-This package allows the developer to interact easily with the [YouCan Pay API](https://pay.youcan.shop/docs). +This package allows the developer to interact easily with the [YouCan Pay API](https://pay.youcan.shop/docs). -## Basic Usage +This documentation is separated in two integrations: **Default Integration** and the **Standalone Integration**. +you have the choice to do one integration or both integrations in your checkout page. +## YouCan Pay SDK Setup +Instructions for adding the YouCan Pay SDK to your PHP Applications. + +### Step 1. Requirements +* YouCan Pay Account. +* Your YouCan Pay `private_key` and `public_key` available in Settings > API Keys. +* Visual Studio Code or Sublime Text or any IDE. +* Website with SSL, required only if you want to use the **default mode** for your payments. +* Composer installed in your development environment. + +### Step 2. Add YouCan Pay SDK +Open your PHP project, add the following. +* Run this command to download and include YouCan Pay PHP SDK in your project. + If you can't install composer, you can manually download the SDK from GitHub `https://github.com/NextmediaMa/youcan-payment-php-sdk/archive/refs/heads/master.zip`. ```bash -composer install youcanpay/payment-sdk +composer require youcanpay/payment-sdk +``` + +### Step 2.1 YouCan Pay: Default Integration +You can make payments directly on your site, with the possibility of choosing the position in the DOM. + +If you choose to use JS integration, you must have an SSL certificate to run in production mode. + +2.1.1: Copy this JS script between `...` +```html + ``` +2.1.2: Choose where you want to display payment information (Full Name, Card Numbers, CCV...), must be placed between the `...` tags. +```html +
+ +``` + +2.1.3: Add this code just before the end of the `...` tag. +```html + +``` + +2.1.4: Tokenization step: this token contains all the order information. ```php +useKeys('my-private-key', 'my-public-key'); +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'); -// check keys are valid -YouCanPay::instance()->checkKeys('private-key', 'public-key'); -// or using current instance -$youCanPay->keys->check('private-key', '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' => '', + ]; -// generate a token for a new payment -$token = $youCanPay->token->create("order-id", "2000", "USD", "123.123.123.123"); -var_dump($token->getToken(), $token->getRedirectURL()); + // 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' + ]; -// get details of a transaction -$transaction = $youCanPay->transaction->get('transaction-id'); -var_dump($transaction->getAmount(), $transaction->getCurrency()); + // 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(); + } +} ``` -## Using Test, Production environment -You can specify which environment when initializing `YouCanPay` instance +2.5: Retrieve the token you created with the SDK `createToken()` and insert it into the JS script, this token which contains all the information concerning this payment. + +When the buyer clicks on the Pay button. the JS code below runs, and you receive a **GET** response in `successUrl` or `errorUrl` you defined in the tokenization step. +```html + +``` + +### Step 2.2 YouCan Pay: Standalone Integration +2.2.1: Tokenization step: this token contains all the order information. ```php +useKeys('my-private-key', 'my-public-key'); +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: After the tokenization retrieve the link created with `createPaymentURL()` function and integrate it in your DOM or redirect the buyer directly to this URL. +```html +Pay Now ```