Sometimes Paypal decided to place a payment on "on hold / pending" status. This Usually caused by safety measures Paypal take for new sellers or because there's a higher than average risk associated with this payment, or any other reason Paypal decided to do it.
This is a common process and they hold the money for something like 21 days.
You can see the documented here:https://www.paypal.com/il/smarthelp/article/why-is-my-payment-on-hold-faq3297
The problem is that until paypal release the money to the seller - the invoice is marked as unpaid without any indication that the customer actually paid the invoice and the money he paid is hold by paypal. The customer paid for the invoice - the amount was removed from his bank account / credit card - so in the customer view he paid for the product so he should see the invoice as paid and get the product he bought.
There should be no reason for the customer to pay and get the product only after ~21 days - this is something paypal is doing to the seller not the buyer.
Presently, in the event a payment is held by PayPal, there is no way for the seller to know that the invoice is actually paid and to deliver the product to the customer, nor for the customer to know he already paid the invoice - and therefore he will try to pay for it again and again and be charged more then one time for the same invoice.
I understand that marking the invoice as paid is not the way you are working - but this is the right way according to paypal since the customer actually paid the necessary payment and paypal is the one holding the money and this is not the customer fault.
I can totally work also with the other option of waiting for paypal to release the payment - but this have to be clear for both the customer and the seller that this invoice is pending for paypal (as long as we are sure that paypal do send a new webhook notification and that WHMCS know to take it and change the invoice status accordingly.)
So either work as paypal instructed and mark the invoice as paid (and the seller will get the money when paypal will release it) or create a new invoice status so it will be cleared to all that this invoice was paid by the customer but paypal is holding the money transfer.
Please note that waiting for paypal to release the payment defeats the purpose of paypal - they want to postpone the money transfer to the seller in order to make sure the buyer delivered the product to the buyer - and if the seller will waite and not do it it can harm his position in paypal.
But as mentioned before either solution is good enough for me.
To sum it all up there are 2 options:
1. The option recommended by paypal - to accept the invoice as paid and to deliver the product to the customer. if everything will went o.k. and the customer will get the product and there will be no complaints by customer regarding the seller - Paypal will release the money to the seller account. and in the long run will allow more and more payment to go through without first being put in the pending status.
2. The safe option from the seller point of view (this is not recommended by paypal) - is to add a new status for the invoice, one that will be clear for the buyer and for the seller that we are waiting for an approval from paypal for the payments (and that this can take up to a full month).
The new status is crucial because without it there is no way to know that this invoice will be paid eventually and without it there can be a double payment since when the customer will see the invoice as unpaid he will try to pay for it again - and maybe with other payment gateways and thus paying more than one time.