zgabievi/laravel-ipay

iPay integration for Laravel

0.2.4 2021-07-30 06:44 UTC

Requires

• php: ^7.2
• bensampo/laravel-enum: ^1.38|^3.1
• illuminate/config: ^6.0|^7.0|^8.0
• illuminate/database: ^6.0|^7.0|^8.0
• illuminate/support: ^6.0|^7.0|^8.0

MIT

• Zura Gabievi

README

📝 iPay documentation can be found here

Table of Contents

• Installation
• Usage
• ENV Variables
• License

Installation

To get started, you need to install package:

composer require zgabievi/laravel-ipay

If your Laravel version is older than 5.5, then add this to your service providers in config/app.php:

'providers' => [
    ...
    Zorb\IPay\IPayServiceProvider::class,
    ...
];

You can publish config file using this command:

php artisan vendor:publish --provider="Zorb\IPay\IPayServiceProvider"

This command will copy config file for you.

Usage

All of the responses are stdClasses. Errors are handled by laravel abort helper. Catch exceptions on your own, if you want to handle them.

Here are methods provided by this package:

• Payment Process - Initialization of payment process
  • Generate Token - (Optional) Token will be auto generated if not provided
  • Checkout - Request checkout order to iPay
  • Redirect - Redirect user to url that was provided by checkout
• Recurring - Repeat payment process using saved order id
• Refund - Reversal of transaction
• Order Details - Check details of order
• Order Status - Check status of order
• Payment Details - Check details of payment
• Complete Pre-Authentication - Complete pre-authorized order
• Helpers - Helper methods to generate checkout
  • Purchase Unit - Helper to generate object for purchase unit
  • Purchase Item - Helper to generate object for purchase item

Payment Process

Generate Token

This step is optional, and if you don't provide token to next request, it will automatically fetch token.

use Zorb\IPay\Facades\IPay;

class PaymentController
{
    public function __invoke()
    {
        $response = IPay::token();
    }
}

Example $response:

{
  "access_token": "eyJraWQiOiIxMDA2IiwiY3R5IjoiYXBwbGljYXRpb25cL2pzb24iLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJQdWJsaWMgcGF5bWVudCBBUEkgVjEiLCJhdWQiOiJpUGF5IERlbW8iLCJpc3M",
  "token_type": "Bearer",
  "app_id": "1A2019",
  "expires_in": 1605623557393
}

Checkout

Generate order in iPay system and get back order details and redirect urls.

use Zorb\IPay\Facades\IPay;
use Zorb\IPay\Enums\Intent;

class PaymentController
{
    public function __invoke()
    {
        $order_id = 1;

        $units = [
          IPay::purchaseUnit(10), // read more about purchaseUnit bellow
        ];

        $items = [
          IPay::purchaseItem(1, 10, 1, 'Item #1'), // read more about purchaseItem bellow
          IPay::purchaseItem(2, 10, 1, 'Item #2'), // read more about purchaseItem bellow
        ];

        // string $intent - 'CAPTURE', 'AUTHORIZE', 'LOAN'
        // int $order_id - Your order id
        // array $units - Purchase units
        // array $items = [] - (optional) Purchase items
        // string $token = null - (optional) JWT Token
        // string $capture_method = 'AUTOMATIC' - (optional) 'AUTOMATIC', 'MANUAL'
        // string $transaction_id = '' - (optional) Transaction id for recurring
        $response = IPay::checkout(Intent::Capture, $order_id, $units, $items);
    }
}

You can set parameters separately:

use Zorb\IPay\Facades\IPay;
use Zorb\IPay\Enums\Intent;
use Zorb\IPay\Enums\CaptureMethod;

class PaymentController
{
    public function __invoke()
    {
        $order_id = 1;

        $response = IPay::setIntent(Intent::Capture)
            ->setShopOrder($order_id)
            ->setPurchaseUnits([ IPay::purchaseUnit(10) ])
            ->setItems([
                IPay::purchaseItem(1, 10, 1, 'Item #1'),
                IPay::purchaseItem(2, 10, 1, 'Item #2'),
            ])
            ->setToken('IPAY_JWT_TOKEN')
            ->setCaptureMethod(CaptureMethod::Manual)
            ->setTransaction('IPAY_TRANSACTION_ID')
            ->checkout();
    }
}

Example $response:

{
  "status": "CREATED",
  "payment_hash": "d7936f718c2b0ec2517a28c9de76966bcbecfe29",
  "links": [
    {
      "href": "https://ipay.ge/opay/api/v1/checkout/orders/899318b1ce0d5885cb7405fe86e3930178ff90be",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://ipay.ge/?order_id=899318b1ce0d5885cb7405fe86e3930178ff90be&locale=ka",
      "rel": "approve",
      "method": "REDIRECT"
    }
  ],
  "order_id": "899318b1ce0d5885cb7405fe86e3930178ff90be"
}

Redirect

Redirect to payment page which is provided by checkout method.

use Zorb\IPay\Facades\IPay;
use Zorb\IPay\Enums\Intent;
use Zorb\IPay\Enums\CheckoutStatus;

class PaymentController
{
    public function __invoke()
    {
        $order_id = 1;

        $units = [
          IPay::purchaseUnit(10), // read more about purchaseUnit bellow
        ];

        $items = [
          IPay::purchaseItem(1, 10, 1, 'Item #1'), // read more about purchaseItem bellow
          IPay::purchaseItem(2, 10, 1, 'Item #2'), // read more about purchaseItem bellow
        ];

        $response = IPay::checkout(Intent::Capture, $order_id, $units, $items);

        if (isset($response->status) && $response->status === CheckoutStatus::Created) {
            return IPay::redirect($response);
            // IPay::redirectUrl($response); - will be used in some cases, like InertiaJS
        }
    }
}

You can set parameters separately:

use Zorb\IPay\Facades\IPay;
use Zorb\IPay\Enums\Intent;
use Zorb\IPay\Enums\CaptureMethod;
use Zorb\IPay\Enums\CheckoutStatus;

class PaymentController
{
    public function __invoke()
    {
        $order_id = 1;

        $response = IPay::setIntent(Intent::Capture)
            ->setShopOrder($order_id)
            ->setPurchaseUnits([ IPay::purchaseUnit(10) ])
            ->setItems([
                IPay::purchaseItem(1, 10, 1, 'Item #1'),
                IPay::purchaseItem(2, 10, 1, 'Item #2'),
            ])
            ->setToken('IPAY_JWT_TOKEN')
            ->setCaptureMethod(CaptureMethod::Manual)
            ->setTransaction('IPAY_TRANSACTION_ID')
            ->checkout();

        if (isset($response->status) && $response->status === CheckoutStatus::Created) {
            return IPay::setResponse($response)->redirect();
            // IPay::setResponse($response)->redirectUrl();
        }
    }
}

Redirect method will find redirect link for payment and redirect user to that page.

Recurring

Recurring process is the same as checkout process. You just have to provide transaction id you want to be used for recurring.

use Zorb\IPay\Facades\IPay;
use Zorb\IPay\Enums\Intent;
use Zorb\IPay\Enums\CheckoutStatus;

class PaymentController
{
    public function __invoke(string $trx_id)
    {
        $order_id = 1;
        $transaction_id = '899318B1CE0D5885CB7'; // Transaction id was provided in you callback url 
        
        $units = [
          IPay::purchaseUnit(10), // read more about purchaseUnit bellow
        ];

        $items = [
          IPay::purchaseItem(1, 10, 1, 'Item #1'), // read more about purchaseItem bellow
          IPay::purchaseItem(2, 10, 1, 'Item #2'), // read more about purchaseItem bellow
        ];

        $response = IPay::repeat($transaction_id, Intent::Capture, $order_id, $units, $items);

        if (isset($response->status) && $response->status === CheckoutStatus::Created) {
            return IPay::redirect($response);
        }
    }
}

You can set parameters separately:

use Zorb\IPay\Facades\IPay;
use Zorb\IPay\Enums\Intent;
use Zorb\IPay\Enums\CheckoutStatus;

class PaymentController
{
    public function __invoke()
    {
        $order_id = 1;
        $transaction_id = '899318B1CE0D5885CB7';

        $response = IPay::setIntent(Intent::Capture)
            ->setShopOrder($order_id)
            ->setPurchaseUnits([ IPay::purchaseUnit(10) ])
            ->setItems([
                IPay::purchaseItem(1, 10, 1, 'Item #1'),
                IPay::purchaseItem(2, 10, 1, 'Item #2'),
            ])
            ->setTransaction($transaction_id)
            ->repeat();

        if (isset($response->status) && $response->status === CheckoutStatus::Created) {
            return IPay::setResponse($response)->redirect();
        }
    }
}

Refund

In order to refund money you need to have order_id of payment.

use Zorb\IPay\Facades\IPay;

class PaymentController
{
    public function __invoke()
    {
        $order_id = '899318b1ce0d5885cb7405fe86e3930178ff90be';

        // string $order_id - Order id provided by checkout process
        // int $amount - Amount you want to refund (in cents)
        // string $token = null - (optional) JWT Token
        $response = IPay::refund($order_id, 10);
    }
}

You can set parameters separately:

use Zorb\IPay\Facades\IPay;

class PaymentController
{
    public function __invoke()
    {
        $order_id = '899318b1ce0d5885cb7405fe86e3930178ff90be';

        $response = IPay::setOrder($order_id)
            ->setAmount(10)
            ->refund();
    }
}

If response is OK, it means refund process was successful.

Order Details

In order to get order details you need to have order_id of payment.

use Zorb\IPay\Facades\IPay;

class PaymentController
{
    public function __invoke()
    {
        $order_id = '899318b1ce0d5885cb7405fe86e3930178ff90be';

        // string $order_id - Order id provided by checkout process
        // string $token = null - (optional) JWT Token
        $response = IPay::orderDetails($order_id);
    }
}

You can set parameters separately:

use Zorb\IPay\Facades\IPay;

class PaymentController
{
    public function __invoke()
    {
        $order_id = '899318b1ce0d5885cb7405fe86e3930178ff90be';

        $response = IPay::setOrder($order_id)
            ->orderDetails();
    }
}

Example $response:

{
  "id": "6ed105e54e703fb6d2e5b7f68a0face71fea2cc6",
  "status": "PERFORMED",
  "intent": "CAPTURE",
  "payer": {
     "name": null,
     "email_address": null,
     "payer_id": null
  },
  "purchaseUnit": {
     "amount": {
         "value": "0.10",
         "currency_code": "GEL"
     },
     "payee": {
         "addres": "Shartava str., 77",
         "contact": "0322444444",
         "email_address": "[e-mail]"
     },
     "payments": [
         {
             "captures": [
                 {
                     "id": "1",
                     "status": "PERFORMED",
                     "amount": {
                         "value": "0.10",
                         "currency_code": "GEL"
                     },
                     "final_capture": "true",
                     "create_time": "Tue Nov 17 19:04:29 GET 2020",
                     "update_time": "Tue Nov 17 19:04:29 GET 2020"
                 },
                 {
                     "id": "2",
                     "status": "PERFORMED",
                     "amount": {
                         "value": "0.10",
                         "currency_code": "GEL"
                     },
                     "final_capture": "true",
                     "create_time": "Tue Nov 17 19:04:29 GET 2020",
                     "update_time": "Tue Nov 17 19:04:29 GET 2020"
                 }
             ]
         }
     ],
     "shop_order_id": "1"
  },
  "createTime": null,
  "updateTime": null,
  "errorHistory": []
}

Order Status

In order to get order status you need to have order_id of payment.

use Zorb\IPay\Facades\IPay;

class PaymentController
{
    public function __invoke()
    {
        $order_id = '899318b1ce0d5885cb7405fe86e3930178ff90be';

        // string $order_id - Order id provided by checkout process
        // string $token = null - (optional) JWT Token
        $response = IPay::orderStatus($order_id);
    }
}

You can set parameters separately:

use Zorb\IPay\Facades\IPay;

class PaymentController
{
    public function __invoke()
    {
        $order_id = '899318b1ce0d5885cb7405fe86e3930178ff90be';

        $response = IPay::setOrder($order_id)
            ->orderStatus();
    }
}

Example $response:

{
  "status": "REJECTED"
}

Payment Details

In order to get payment details you need to have order_id of payment.

use Zorb\IPay\Facades\IPay;

class PaymentController
{
    public function __invoke()
    {
        $order_id = '899318b1ce0d5885cb7405fe86e3930178ff90be';

        // string $order_id - Order id provided by checkout process
        // string $token = null - (optional) JWT Token
        $response = IPay::paymentDetails($order_id);
    }
}

You can set parameters separately:

use Zorb\IPay\Facades\IPay;

class PaymentController
{
    public function __invoke()
    {
        $order_id = '899318b1ce0d5885cb7405fe86e3930178ff90be';

        $response = IPay::setOrder($order_id)
            ->paymentDetails();
    }
}

Example $response:

{
  "status": "error",
  "pan": null,
  "order_id": "899318b1ce0d5885cb7405fe86e3930178ff90be",
  "pre_auth_status": null,
  "payment_hash": "d7936f718c2b0ec2517a28c9de76966bcbecfe29",
  "ipay_payment_id": "18625",
  "status_description": "REJECTED",
  "shop_order_id": "1",
  "payment_method": "UNKNOWN",
  "card_type": "UNKNOWN",
  "transaction_id": null
}

Complete Pre-Authentication

In order to get complete pre-authorized order you need to have order_id of payment.

use Zorb\IPay\Facades\IPay;

class PaymentController
{
    public function __invoke()
    {
        $order_id = '899318b1ce0d5885cb7405fe86e3930178ff90be';

        // string $order_id - Order id provided by checkout process
        // string $token = null - (optional) JWT Token
        $response = IPay::completePreAuth($order_id);
    }
}

You can set parameters separately:

use Zorb\IPay\Facades\IPay;

class PaymentController
{
    public function __invoke()
    {
        $order_id = '899318b1ce0d5885cb7405fe86e3930178ff90be';

        $response = IPay::setOrder($order_id)
            ->completePreAuth();
    }
}

All helper methods to set parameters separately

Environment Variables

License

zgabievi/laravel-ipay is licensed under a MIT License.