Merge pull request #62 from veritrans/v2.31

v2.31

MAINTAINING.md

@@ -28,6 +28,11 @@ Other:
 - External WC PG dev guide: https://www.skyverge.com/blog/how-to-create-a-simple-woocommerce-payment-gateway/
 - WP get_options() functions: https://developer.wordpress.org/reference/functions/get_option/
 
+### Attention
+- Due to the feature of "custom order_id suffix to prevent duplicated order_id", order_id input and output may need to be handled non-traditionally, look for `@TAG: order-suffix-separator` in the code comments. e.g:
+  - when sending order_id to Midtrans, it may need to go thru func `WC_Midtrans_Utils::generate_non_duplicate_order_id`
+  - when receiving order_id, it may need to go thru func `WC_Midtrans_Utils::check_and_restore_original_order_id`
+
 ### Separted Payment Buttons
 To implement separated payment buttons (separate WC payment gateway) for each of Midtrans' supported payment methods, the following implementations are made:
 - within `/class/sub-specific-buttons` those are the class files

README.md

@@ -8,21 +8,23 @@ Also [Available on Wordpress plugin store](https://wordpress.org/plugins/midtran
 
 ### Description
 
-This plugin will allow secure online payment on your WooCommerce store, without your customer ever need to leave your WooCommerce store! With beautiful responsive payment interface built-in.
-Midtrans  is an online payment gateway. They strive to make payments simple for both the merchant and customers.
-Support various online payment channel.
-Support WooCommerce v3 & v2.
+This plugin will allow secure online payment on your WooCommerce store, without your customer ever need to leave your WooCommerce store! 
+
+Midtrans-WooCommerce is official plugin from [Midtrans](https://midtrans.com). Midtrans is an online payment gateway. We strive to make payments simple & secure for both the merchant and customers. Support various online payment channel. Support WooCommerce v3 & v2.
+
+Please follow [this step by step guide](https://docs.midtrans.com/en/snap/with-plugins?id=wordpress-woocommerce) for complete configuration. If you have any feedback or request, please [do let us know here](https://docs.midtrans.com/en/snap/with-plugins?id=feedback-and-request).
 
 Payment Method Feature:
 
 * Credit card fullpayment and other payment methods.
-* Bank transfer, internet banking for various banks
+* E-wallet, Bank transfer, internet banking for various banks
 * Credit card Online & offline installment payment.
 * Credit card BIN, bank transfer, and other channel promo payment.
 * Credit card MIGS acquiring channel.
 * Custom expiry.
 * Two-click & One-click feature.
-* Midtrans Snap all payment method fullpayment.
+* Midtrans Snap all supported payment method.
+* Optional: Separated specific payment buttons with its own icons.
 
 
 ### Installation
@@ -89,7 +91,7 @@ You can customize icon that will be shown on payment buttons, from the plugin co
 
 All available values for the field:
 ```
-credit_card.png, gopay.png, shopeepay.png, qris.png, other_va.png, bni_va.png, bri_va.png, bca_va.png, permata_va.png, echannel.png, alfamart.png, indomaret.png, akulaku.png, bca_klikpay.png, cimb_clicks.png, danamon_online.png, midtrans.png
+midtrans.png, credit_card.png, gopay.png, shopeepay.png, qris.png, other_va.png, bni_va.png, bri_va.png, bca_va.png, permata_va.png, echannel.png, alfamart.png, indomaret.png, akulaku.png, bca_klikpay.png, cimb_clicks.png, danamon_online.png
 ```
 
 Or refer to [payment-methods folder](/public/images/payment-methods) to see the list of all available file names. The image file will be loaded from that folder.
@@ -136,11 +138,13 @@ If you are a developer or know how to customize Wordpress, this section may be u
 
 This plugin have few available [WP hooks](https://developer.wordpress.org/plugins/hooks/):
 - filter: `midtrans_snap_params_main_before_charge` (1 params)
-	- For if you want to modify Snap API JSON param on the main gateway, before transaction is created on Midtrans side.
+	- For if you want to modify Snap API JSON param on the main gateway, before transaction is created on Midtrans side. The $params is PHP Array representation of [Snap API JSON param](https://snap-docs.midtrans.com/#request-body-json-parameter)
 - action: `midtrans_after_notification_payment_complete` (2 params)
 	- For if you want to perform action/update WC Order object when the payment is declared as complete upon Midtrans notification received.
 - action: `midtrans_on_notification_received` (2 params)
 	- For if you want to perform action/update WC Order object upon Midtrans notification received.
+- action: `midtrans-handle-valid-notification` (1 params)
+	- For if you want to perform something upon valid Midtrans notification received. Note: this is legacy hook, better use the hook above.
 
 Example implementation:
 ```php
@@ -174,6 +178,8 @@ function my_midtrans_on_notif_hook( $order, $midtrans_notification ) {
 
 For reference on where/which file to apply that code example, [refer here](https://blog.nexcess.net/the-right-way-to-add-custom-functions-to-your-wordpress-site/).
 
+Note: for `midtrans_after_notification_payment_complete` & `midtrans_on_notification_received` hooks, if you are using [custom "WC Order Status on Payment Paid"](https://docs.midtrans.com/en/snap/with-plugins?id=advanced-customize-woocommerce-order-status-upon-payment-paid) config, the final WC Order status value can get overridden by that config. As that config is executed last.
+
 </details>
 
 #### Customizing Snap API parameters

abstract/abstract.midtrans-gateway.php

@@ -131,16 +131,26 @@ public function process_refund($order_id, $amount = null, $reason = '') {
    */
   public function refund( $order, $order_id, $amount, $reason ) {
     $refund_params = array(
+      // @TODO: careful with this order_id here, which does not get deduplicated treatment
       'refund_key' => 'RefundID' . $order_id . '-' . current_time('timestamp'),
       'amount' => $amount,
       'reason' => $reason
     );
 
     try {
-      $response = WC_Midtrans_API::createRefund($order_id, $refund_params, $this->id);
+      if(strpos($this->id, 'midtrans_sub') !== false){
+        // for sub separated gateway buttons, use main gateway plugin id instead
+        $this->id = 'midtrans';
+      }
+      // @TODO: call refund API with transaction_id instead of order_id to avoid id not found for suffixed order_id. $order->get_transaction_id();
+      $transaction_id = $order->get_transaction_id() 
+        ? $order->get_transaction_id() 
+        : $order_id;
+      $response = WC_Midtrans_API::createRefund($transaction_id, $refund_params, $this->id);
     } catch (Exception $e) {
       $this->setLogError( $e->getMessage() );
-      $error_message = strpos($e->getMessage(), '412') ? $e->getMessage() . ' Note: Refund via Midtrans only for specific payment method, please consult to your midtrans PIC for more information' : $e->getMessage();
+      // error_log(var_export($e,1));
+      $error_message = strpos($e->getMessage(), '412') ? $e->getMessage() . ' Note: Refund via Midtrans API only available on some payment methods, and if the payment status is eligible. Please consult to your midtrans PIC for more information' : $e->getMessage();
       return $error_message;
     }
 
@@ -334,6 +344,7 @@ public function getResponseTemplate( $order ) {
    * @return WC_Order_Refund|WP_Error
    */
   public function midtrans_refund( $order_id, $refund_amount, $refund_reason, $isFullRefund = false ) {
+    $order_id = WC_Midtrans_Utils::check_and_restore_original_order_id();
     $order  = wc_get_order( $order_id );
     if( ! is_a( $order, 'WC_Order') ) {
       return;
@@ -386,6 +397,20 @@ public function midtrans_refund( $order_id, $refund_amount, $refund_reason, $isF
       return $refund;
   }
 
+  /**
+   * Custom helper function to set customer web session cookies of WC order's finish_url
+   * That will be used by finish url handler to redirect customer to upon finish url is reached
+   * Cookies is used to strictly allow only the transacting-customer 
+   * to access the order's finish url
+   * @TAG: finish_url_user_cookies
+   * @param WC_Order $order WC Order instance of the current transaction
+   */
+  public function set_finish_url_user_cookies( $order ) {
+    $cookie_name = 'wc_midtrans_last_order_finish_url';
+    $order_finish_url = $order->get_checkout_order_received_url();
+    setcookie($cookie_name, $order_finish_url);
+  }
+
   /**
    * Custom helper function to write messages to WP/WC error log. 
    * @TODO: refactor name to make it more descriptive?

class/class.midtrans-gateway-api.php

@@ -87,12 +87,47 @@ public static function get_environment() {
      * @return void
      */
     public static function fetchAndSetMidtransApiConfig( $plugin_id="midtrans" ) {
+        if(strpos($plugin_id, 'midtrans_sub') !== false){
+          // for sub separated gateway buttons, use main gateway plugin id instead
+          $plugin_id = 'midtrans';
+        }
 		self::fetchAndSetCurrentPluginOptions( $plugin_id );
         Midtrans\Config::$isProduction = (self::get_environment() == 'production') ? true : false;
         Midtrans\Config::$serverKey = self::get_server_key();     
         Midtrans\Config::$isSanitized = true;
     }
 
+    /**
+     * Same as createSnapTransaction, but it will auto handle exception
+     * 406 duplicated order_id exception from Snap API, by calling WC_Midtrans_Utils::generate_non_duplicate_order_id
+     * @param  object $order the WC Order instance.
+     * @param  array $params Payment options.
+     * @param  string $plugin_id ID of the plugin class calling this function
+     * @return object Snap response (token and redirect_url).
+     * @throws Exception curl error or midtrans error.
+     */
+    public static function createSnapTransactionHandleDuplicate( $order, $params, $plugin_id="midtrans") {
+        try {
+            $response = self::createSnapTransaction($params, $plugin_id);
+        } catch (Exception $e) {
+            // Handle: Snap order_id duplicated, retry with suffixed order_id
+            if( strpos($e->getMessage(), 'transaction_details.order_id sudah digunakan') !== false) {
+                self::setLogRequest( $e->getMessage().' - Attempt to auto retry with suffixed order_id', $plugin_id );
+                // @TAG: order-id-suffix-handling
+                $params['transaction_details']['order_id'] = 
+                    WC_Midtrans_Utils::generate_non_duplicate_order_id($params['transaction_details']['order_id']);
+                $response =  self::createSnapTransaction($params, $plugin_id);
+
+                // store the suffixed order id to order metadata
+                // @TAG: order-id-suffix-handling-meta
+                $order->update_meta_data('_mt_suffixed_midtrans_order_id', $params['transaction_details']['order_id']);
+            } else {
+                throw $e;
+            }
+        }
+        return $response;
+    }
+
     /**
      * Create Snap Token.
      * @param  array $params Payment options.

class/class.midtrans-gateway-installment.php

@@ -88,7 +88,7 @@ function process_payment( $order_id ) {
         // Empty the cart because payment is initiated.
         $woocommerce->cart->empty_cart();
         try {
-          $snapResponse = WC_Midtrans_API::createSnapTransaction( $params, $this->id );
+          $snapResponse = WC_Midtrans_API::createSnapTransactionHandleDuplicate( $order, $params, $this->id );
         } catch (Exception $e) {
           $this->setLogError( $e->getMessage() );
           WC_Midtrans_Utils::json_print_exception( $e, $this );
@@ -105,7 +105,8 @@ function process_payment( $order_id ) {
         $order->update_meta_data('_mt_payment_snap_token',$snapResponse->token);
         $order->update_meta_data('_mt_payment_url',$snapResponse->redirect_url);
         $order->save();
-
+        // set wc order's finish_url on user's session cookie
+        $this->set_finish_url_user_cookies($order);
         if(property_exists($this,'enable_immediate_reduce_stock') && $this->enable_immediate_reduce_stock == 'yes'){
           wc_reduce_stock_levels($order);
         }

class/class.midtrans-gateway-installmentoff.php

@@ -117,7 +117,7 @@ public function process_payment( $order_id ) {
         // Empty the cart because payment is initiated.
         $woocommerce->cart->empty_cart();
         try {
-          $snapResponse = WC_Midtrans_API::createSnapTransaction( $params, $this->id );
+          $snapResponse = WC_Midtrans_API::createSnapTransactionHandleDuplicate( $order, $params, $this->id );
         } catch (Exception $e) {
           $this->setLogError( $e->getMessage() );
           WC_Midtrans_Utils::json_print_exception( $e, $this );
@@ -135,6 +135,8 @@ public function process_payment( $order_id ) {
         $order->update_meta_data('_mt_payment_snap_token',$snapResponse->token);
         $order->update_meta_data('_mt_payment_url',$snapResponse->redirect_url);
         $order->save();
+        // set wc order's finish_url on user's session cookie
+        $this->set_finish_url_user_cookies($order);
         if(property_exists($this,'enable_immediate_reduce_stock') && $this->enable_immediate_reduce_stock == 'yes'){
           // Reduce item stock on WC, item also auto reduced on order `pending` status changes
           wc_reduce_stock_levels($order);