PayPal RESTful API Payment Module

mprough:

Yes, I did. Even uninstalled & reinstalled in admin
Yep, there's something "funny" going on with v1.2.0. Please continue to use v1.1.0 while I figure out what the heck's going on.

lat9:

Yep, there's something "funny" going on with v1.2.0. Please continue to use v1.1.0 while I figure out what the heck's going on.
v1.2.1 is now available to download from the Plugins section, correcting the upgrade issues from versions prior to v1.2.0.

Anyone who has installed the 1.2.0 release can correct those issues by copying the following into the admin's Tools :: Install SQL Patches

UPDATE configuration SET configuration_value = '1.1.0' WHERE configuration_key = 'MODULE_PAYMENT_PAYPALR_VERSION' LIMIT 1;

Once that's been run, navigate back to the Modules :: Payment page and the PayPal/RESTful module will update (properly) to v1.2.1.

lat9:

v1.2.1 is now available to download from the Plugins section, correcting the upgrade issues from versions prior to v1.2.0.

Anyone who has installed the 1.2.0 release can correct those issues by copying the following into the admin's Tools :: Install SQL Patches

UPDATE configuration SET configuration_value = '1.1.0' WHERE configuration_key = 'MODULE_PAYMENT_PAYPALR_VERSION' LIMIT 1;

> 
> Once that's been run, navigate back to the **Modules :: Payment** page and the PayPal/RESTful module will update (properly) to v1.2.1.

I can confirm that works for sure upon testing. Many thanks!

HeathenMagic:

I can confirm that works for sure upon testing. Many thanks!
Thanks for the feedback!

I am getting the follow error when testing version 1.2.1 on Zen cart 2.0.1 php 8.3.

 There was a problem capturing the transaction. {"errNum":422,"errMsg":"An interface error (422) was returned from PayPal.","curlErrno":0,"name":"UNPROCESSABLE_ENTITY","message":"The requested action could not be performed, semantically incorrect, or failed business validation.","details":[{"issue":"MAX_CAPTURE_AMOUNT_EXCEEDED","description":"Capture amount exceeds allowable limit. Please contact customer service or your account manager to request the change to your overage limit. The default overage limit is 115%, which allows the sum of all captures to be up to 115% of the order amount."}],"debug_id":"f951957561990"}

I created a transaction with item costing £15 and postage £3.90. Authorise only.
I then capture the £15 as a partial capture.
I then try to capture the postage £3.90 with capture remaining funds ticked, and final capture ticked. The process fails with error message above.

If I try again and don't tick capture remaining funds the process works no error.
I have the PayPal logs and can pm if you require.

brittainmark:

I am getting the follow error when testing version 1.2.1 on Zen cart 2.0.1 php 8.3.

There was a problem capturing the transaction. {"errNum":422,"errMsg":"An interface error (422) was returned from PayPal.","curlErrno":0,"name":"UNPROCESSABLE_ENTITY","message":"The requested action could not be performed, semantically incorrect, or failed business validation.","details":[{"issue":"MAX_CAPTURE_AMOUNT_EXCEEDED","description":"Capture amount exceeds allowable limit. Please contact customer service or your account manager to request the change to your overage limit. The default overage limit is 115%, which allows the sum of all captures to be up to 115% of the order amount."}],"debug_id":"f951957561990"}

> I created a transaction with item costing £15 and postage £3.90. Authorise only.
> I then capture the £15 as a partial capture.
> I then try to capture the postage £3.90 with capture remaining funds ticked, and final capture ticked. The process fails with error message above. 
> 
> If I try again and don't tick capture remaining funds the process works no error.
> I have the PayPal logs and can pm if you require.
You can send those logs to my direct email address.

lat9:

You can send those logs to my direct email address.
Crud, from the PayPal documentation on the "Capture" (https://developer.paypal.com/docs/api/payments/v2/#authorizations_capture%29:

The amount to capture. To capture a portion of the full authorized amount, specify an amount.** If amount is not specified, the full authorized amount is captured.** The amount must be a positive number and in the same currency as the authorization against which the payment is being captured.

So are you saying that if I click capture remaining funds, I should set the amount to zero?

Currently the amount is set correctly to the ramaining amount when I click commit.

brittainmark:

So are you saying that if I click capture remaining funds, I should set the amount to zero?

Currently the amount is set correctly to the ramaining amount when I click commit.
Nope, I'm saying either I misread the API originally (I thought that capturing with no arguments meant capture the remaining value) or the documentation changed.

I might just remove the "Capture remaining funds" checkbox.

ZC 2.1
PHP 8.3

customer_tax_exempt_2.0.2
edit_orders-5.0.2
paypalr-1.2.1
sales_report-4.0.2
sitemapxml-4.0.4
usps-USPS_2024_08_25_K11l
zen_Image-Handler-5.3.5
zen_TyPackageTracker-5.0.1

I installed the newest version of paypalr. I have had a couple of successful sales but I am getting the two following error logs for some reason:

[10-Sep-2025 17:49:50 America/Boise] PHP Fatal error:  Declaration of PayPalRestful\Admin\Formatters\Messages::output(?string $class = null) must be compatible with messageStack::output($class) in /public_html/includes/modules/payment/paypal/PayPalRestful/Admin/Formatters/Messages.php on line 21

[09-Sep-2025 18:19:47 America/Boise] Request URI: /ipn_main_handler.php?type=ec, IP address: ***.***.***.***, Language id 1
#0 /public_html/includes/functions/functions_taxes.php(390): zen_debug_error_handler()
#1 /public_html/includes/modules/order_total/ot_tax.php(66): zen_get_tax_locations()
#2 /public_html/includes/classes/order_total.php(229): ot_tax->process()
#3 /public_html/includes/modules/payment/paypalwpp.php(1635): order_total->pre_confirmation_check()
#4 /public_html/ipn_main_handler.php(81): paypalwpp->ec_step1()
--> PHP Warning: Undefined array key "billto" in /public_html/includes/functions/functions_taxes.php on line 390.

[09-Sep-2025 18:19:47 America/Boise] Request URI: /ipn_main_handler.php?type=ec, IP address: ***.***.***.***, Language id 1
#0 /public_html/includes/functions/functions_taxes.php(390): zen_debug_error_handler()
#1 /public_html/includes/modules/order_total/ot_tax.php(66): zen_get_tax_locations()
#2 /public_html/includes/classes/order_total.php(96): ot_tax->process()
#3 /public_html/includes/modules/payment/paypalwpp.php(1636): order_total->process()
#4 /public_html/ipn_main_handler.php(81): paypalwpp->ec_step1()
--> PHP Warning: Undefined array key "billto" in /public_html/includes/functions/functions_taxes.php on line 390.

Okay, the second error log above is BS because it occurred before I got upgraded to the new paypal so ignore that.
In regards to the first error log above ChatGPT, I know hiss, hiss, boo, boo but it helps me a lot sometimes, indicates that this is a PHP method signature mismatch between the PayPal RESTful module and Zen Cart’s messageStack class:

paypalr is declaring:

public function output(?string $class = null)

Zen Cart’s messageStack::output() is declared as:

public function output($class)

In PHP 8+, method signatures in subclasses must match exactly (including nullable types and default values).

Proposed fix:
Open:

/includes/modules/payment/paypal/PayPalRestful/Admin/Formatters/Messages.php

Find:

public function output(?string $class = null)

Replace with:

public function output($class = null)

That makes the signature compatible with messageStack::output($class).

If the above is correct then I will just make the change.
If not then I apologize and please advise.
Thank You for any assistance with this issue.

wsworx:

Okay, the second error log above is BS because it occurred before I got upgraded to the new paypal so ignore that.
In regards to the first error log above ChatGPT, I know hiss, hiss, boo, boo but it helps me a lot sometimes, indicates that this is a PHP method signature mismatch between the PayPal RESTful module and Zen Cart’s messageStack class:

paypalr is declaring:

public function output(?string $class = null)

> 
> 
> Zen Cart’s messageStack::output() is declared as:
> 
> ```
public function output($class)

In PHP 8+, method signatures in subclasses must match exactly (including nullable types and default values).

Proposed fix:
Open:

/includes/modules/payment/paypal/PayPalRestful/Admin/Formatters/Messages.php

Find:

public function output(?string $class = null)

> 
> 
> Replace with:
> 
> ```
public function output($class = null)

That makes the signature compatible with messageStack::output($class).

If the above is correct then I will just make the change.
If not then I apologize and please advise.
Thank You for any assistance with this issue.
Thanks for the report; the issue was previously reported in this (https://github.com/lat9/paypalr/issues/81) GitHub issue. The solution you posted was also suggested there, so I'll say you can "go with it".

PHP 8.4 / ZC 2.1.0 / PayPal RESTFUL 1.2

Testing the module out and everything works as far as recognizing paying events (CREATE, CAPTURED, COMPLETED). However, triggering an refund from the PayPal side of things has the order not recognize that it was refunded.

That is to say: if I charge an order, then try to refund that order, the PayPal refund doesn't reach the ZC Database. I can see a log is generated (attached below, it's from the sandbox) but then at the end of it, the module notes that it cannot find the order and just drops out.

Is this something to be concerned with?

2025-09-14 09:54:36: (ppr_webhook) ppr_webhook (PAYMENT.CAPTURE.REFUNDED, PayPal/AUHD-1.0-1, POST) starts.{
    "id": "WH-74T39592TU773570G-4UR976727P454984C",
    "event_version": "1.0",
    "create_time": "2025-09-14T13:54:28.338Z",
    "resource_type": "refund",
    "resource_version": "2.0",
    "event_type": "PAYMENT.CAPTURE.REFUNDED",
    "summary": "A $ 0.01 USD capture payment was refunded",
    "resource": {
        "seller_payable_breakdown": {
            "total_refunded_amount": {
                "value": "0.01",
                "currency_code": "USD"
            },
            "paypal_fee": {
                "value": "0.00",
                "currency_code": "USD"
            },
            "gross_amount": {
                "value": "0.01",
                "currency_code": "USD"
            },
            "net_amount": {
                "value": "0.01",
                "currency_code": "USD"
            }
        },
        "amount": {
            "value": "0.01",
            "currency_code": "USD"
        },
        "update_time": "2025-09-14T06:54:24-07:00",
        "create_time": "2025-09-14T06:54:24-07:00",
        "invoice_id": "PPR-20250914095258-1-PauWil-c05c82fc",
        "links": [
            {
                "method": "GET",
                "rel": "self",
                "href": "https:\/\/api.sandbox.paypal.com\/v2\/payments\/refunds\/27L28035LL8140251"
            },
            {
                "method": "GET",
                "rel": "up",
                "href": "https:\/\/api.sandbox.paypal.com\/v2\/payments\/captures\/50A226912H175722S"
            }
        ],
        "id": "27L28035LL8140251",
        "payer": {
            "email_address": "[email protected]",
            "merchant_id": "K5V8XYA7Z66VL"
        },
        "status": "COMPLETED"
    }
}
************************************************


webhook verification passed
************************************************


webhook event supported by PayPalRestful\Webhooks\Events\PaymentCaptureRefunded
PAYMENT.CAPTURE.REFUNDED - action() triggered
************************************************


2025-09-14 09:54:37: (ppr_webhook) validateCredentials: Checking (1).
TokenCache::clear, clearing cached token.
The curlPost (v1/oauth2/token) request was successful (200).
{
    "token_type": "Bearer",
    "expires_in": 31492
}
TokenCache::save, saving access-token; valid for 31492 seconds.


************************************************




---
NOTICE: Order ID lookup returned no results.

The second question: originally I had an address of mydomain.com/ppr_webhook.php but I noticed in the last update that it was removed. Should I remove this configured address from the PayPal developers section for the webhook address?

~~I'm having 'difficulties' moving this post to the payment module's support-thread: https://www.zen-cart.com/showthread.php/229886-PayPal-RESTful-API-Payment-Module

If you could re-post there,~~ I'll be happy to investigate issue #1.

For the 2nd question, it's still /ppr_webhook.php. That script is copied to the root when the payment module is installed. And is registered to PayPal webhooks automatically.

retched:

PHP 8.4 / ZC 2.1.0 / PayPal RESTFUL 1.2

Testing the module out and everything works as far as recognizing paying events (CREATE, CAPTURED, COMPLETED). However, triggering an refund from the PayPal side of things has the order not recognize that it was refunded.

That is to say: if I charge an order, then try to refund that order, the PayPal refund doesn't reach the ZC Database. I can see a log is generated (attached below, it's from the sandbox) but then at the end of it, the module notes that it cannot find the order and just drops out.

Is this something to be concerned with?

2025-09-14 09:54:36: (ppr_webhook) ppr_webhook (PAYMENT.CAPTURE.REFUNDED, PayPal/AUHD-1.0-1, POST) starts.{
"id": "WH-74T39592TU773570G-4UR976727P454984C",
"event_version": "1.0",
"create_time": "2025-09-14T13:54:28.338Z",
"resource_type": "refund",
"resource_version": "2.0",
"event_type": "PAYMENT.CAPTURE.REFUNDED",
"summary": "A $ 0.01 USD capture payment was refunded",
"resource": {
"seller_payable_breakdown": {
"total_refunded_amount": {
"value": "0.01",
"currency_code": "USD"
},
"paypal_fee": {
"value": "0.00",
"currency_code": "USD"
},
"gross_amount": {
"value": "0.01",
"currency_code": "USD"
},
"net_amount": {
"value": "0.01",
"currency_code": "USD"
}
},
"amount": {
"value": "0.01",
"currency_code": "USD"
},
"update_time": "2025-09-14T06:54:24-07:00",
"create_time": "2025-09-14T06:54:24-07:00",
"invoice_id": "PPR-20250914095258-1-PauWil-c05c82fc",
"links": [
{
"method": "GET",
"rel": "self",
"href": "https://api.sandbox.paypal.com/v2/payments/refunds/27L28035LL8140251"
},
{
"method": "GET",
"rel": "up",
"href": "https://api.sandbox.paypal.com/v2/payments/captures/50A226912H175722S"
}
],
"id": "27L28035LL8140251",
"payer": {
"email_address": "[email protected]",
"merchant_id": "K5V8XYA7Z66VL"
},
"status": "COMPLETED"
}
}

webhook verification passed

webhook event supported by PayPalRestful\Webhooks\Events\PaymentCaptureRefunded
PAYMENT.CAPTURE.REFUNDED - action() triggered

2025-09-14 09:54:37: (ppr_webhook) validateCredentials: Checking (1).
TokenCache::clear, clearing cached token.
The curlPost (v1/oauth2/token) request was successful (200).
{
"token_type": "Bearer",
"expires_in": 31492
}
TokenCache::save, saving access-token; valid for 31492 seconds.

NOTICE: Order ID lookup returned no results.

> 
> The second question: originally I had an address of mydomain.com/ppr_webhook.php but I noticed in the last update that it was removed. Should I remove this configured address from the PayPal developers section for the webhook address?

I wonder if this is simply a mismatch between orders in your database vs sandbox.
The Order ID lookup for webhook handling would use the webhook payload of  "id": "27L28035LL8140251" to search your store's paypal history table for an order with that transaction id.

The log you posted is only related to the webhook.

Did I correctly understand from your post that there doesn't seem to be a refund reflected in the order history itself? Or is it only missing when looking at paypal-specific details?


Also, while the module automatically registers the ppr_webhook.php as the webhook handler, it will do it separately for sandbox and for production, and doesn't de-register when you change modes. It's currently only de-registering when you uninstall the module. (It shouldn't matter that a sandbox webhook is registered, since once in production you'll almost never use the sandbox webhook anyway. So it's moot.)

lat9:

~~I'm having 'difficulties' moving this post to the payment module's support-thread: https://www.zen-cart.com/showthread.php/229886-PayPal-RESTful-API-Payment-Module

If you could re-post there,~~ I'll be happy to investigate issue #1.

For the 2nd question, it's still /ppr_webhook.php. That script is copied to the root when the payment module is installed. And is registered to PayPal webhooks automatically.

Wait, so the file is copied to the root automatically on install? Should I reinstall the module if my root is missing this file?

retched:

Wait, so the file is copied to the root automatically on install? Should I reinstall the module if my root is missing this file?
If you're running v1.2.0, there was an issue with the auto-update. Update to v1.2.1 to correct the issue.

ZC 1.5.8a / php 7.4.33

Running fine with v1.1.0, but error in 1.2.1:

[20-Sep-2025 02:00:06 Canada/Pacific] PHP Parse error:  syntax error, unexpected ')', expecting variable (T_VARIABLE) in /zc/includes/modules/payment/paypal/PayPalRestful/Api/PayPalRestfulApi.php on line 367

[20-Sep-2025 02:00:06 Canada/Pacific] Request URI: /index.php?main_page=checkout_shipping, IP address: x.x.x.x
--> PHP Parse error: syntax error, unexpected ')', expecting variable (T_VARIABLE) in /zc/includes/modules/payment/paypal/PayPalRestful/Api/PayPalRestfulApi.php on line 367.

siliconbug:

ZC 1.5.8a / php 7.4.33

Running fine with v1.1.0, but error in 1.2.1:

[20-Sep-2025 02:00:06 Canada/Pacific] PHP Parse error: syntax error, unexpected ')', expecting variable (T_VARIABLE) in /zc/includes/modules/payment/paypal/PayPalRestful/Api/PayPalRestfulApi.php on line 367

[20-Sep-2025 02:00:06 Canada/Pacific] Request URI: /index.php?main_page=checkout_shipping, IP address: x.x.x.x
--> PHP Parse error: syntax error, unexpected ')', expecting variable (T_VARIABLE) in /zc/includes/modules/payment/paypal/PayPalRestful/Api/PayPalRestfulApi.php on line 367.

Hmm, I'm not seeing that with PHP 7.4.30 (don't currently have access to 7.4.33).  Here are lines 361 to 367 of the PayPalRestfulApi.php module:
```php
    public function updatePackageTracking(
        string $paypal_txnid,
        string $tracking_number,
        string $carrier_code,
        string $action = 'ADD',
        bool $email_buyer = false,
    ): false|array {

If you remove the comma (,) after bool $email_buyer = false, does that correct the issue?

New error log after removing the comma (,) :

[20-Sep-2025 08:55:25 Canada/Pacific] PHP Parse error: syntax error, unexpected '|', expecting ';' or '{' in /includes/modules/payment/paypal/PayPalRestful/Api/PayPalRestfulApi.php on line 367

[20-Sep-2025 08:55:25 Canada/Pacific] Request URI: /index.php?main_page=checkout_shipping, IP address: x.x.x.x
--> PHP Parse error: syntax error, unexpected '|', expecting ';' or '{' in /includes/modules/payment/paypal/PayPalRestful/Api/PayPalRestfulApi.php on line 367.