Allow registering payment via API

[CherryDT]

Is your feature request related to a problem? Please describe.
Currently it seems there is no way to register a payment through the API. But we may receive payments through external services that we intergated with, so we'd like to reflect the payment that we received in the invoice in SolidInvoice automatically.

Describe the solution you'd like
Add POST, PUT, DELETE endpoints to the Payment resources as well.

Additional context
I wonder why this isn't already supported. What is the gotcha? If I were to fork this project and try to implement it myself, I'd assume I could just update the ApiResource of the Payment entity so it's no longer restricted to read-only, but I assume there is a reason it's currently like that - what is the reason?

[pierredup]

The payments goes through a payment gateway, which has a lot of additional logic (verifying the payment with the gateway, sending payment notifications to the admin etc). This will be difficult to replicate through the API, which is why it hasn't been implemented yet.

An alternative would be to just insert a payment record through the API and skip the payment gateway workflow, but just adding the ApiResource to the Payment entity won't be enough since there are still additional logic that needs to be replicated, E.G marking the invoice as paid (if the payment amount = invoice amount), capturing a partial payment, emitting the payment events (Payment Completed event etc).

[CherryDT]

I don't need a payment gateway, people can pay by bank wire or something else, that's not part of what the software needs to care about in this use case. That's in fact the whole point of what I need here - someone can pay in some external manner which another service may register and then it needs to let your software know that the amount was paid. I am therefore interested in simply automating the part of manually registering a payment that was made which you can currently do in the UI but not in the API.

[pierredup]

I am therefore interested in simply automating the part of manually registering a payment that was made

That is the flow that I mentioned in my first comment:

An alternative would be to just insert a payment record through the API and skip the payment gateway workflow, but just adding the ApiResource to the Payment entity won't be enough since there are still additional logic that needs to be replicated, E.G marking the invoice as paid (if the payment amount = invoice amount), capturing a partial payment, emitting the payment events (Payment Completed event etc).

This will skip the payment gateway flow, but it would still require some additional work to ensure the invoice is marked as paid and that the payment events are triggered.

[CherryDT]

OK, so I guess I'd have to figure out how it's done when you do it through the API and replicate this as API endpoint. I assume I can add the payment record as writable API resource and then add some sort of hook to execute the additional logic needed? Probably we should only allow POST then since with the things you described, PUT/DELETE would become even harder to build.

[pierredup]

I assume I can add the payment record as writable API resource

That is correct

add some sort of hook to execute the additional logic needed

One of the most important parts is emitting the payment complete event. Most of the additional logic is done when this event is emitted:

SolidInvoice/src/PaymentBundle/Action/Done.php

Lines 57 to 58 in b24e9aa

	$event = new PaymentCompleteEvent($payment);
	$this->eventDispatcher->dispatch($event, PaymentEvents::PAYMENT_COMPLETE);

There are listeners that mark the invoice as paid in

SolidInvoice/src/PaymentBundle/Listener/PaymentCompleteListener.php

Line 52 in b24e9aa

public function onPaymentComplete(PaymentCompleteEvent $event): void

, but this listener currently assumes the payment is done from the UI, so it sets a response to redirect the user back to view the invoice which should not happen when a payment is captured through the API. So this listener needs to be adjusted to take into account that the payment is done through the API.

Probably we should only allow POST then since with the things you described, PUT/DELETE would become even harder to build.

Yes I think PUT and DELETE will become very tricky, since the payment needs to be unallocated from the invoice. Just allowing POST for now will be the easiest

[CherryDT]

Hm, I saw POST/PUT/DELETE is now listed in the API docs, did you add this already? I am a bit confused about the arguments though, I don't understand why the payment would require information about the company and users and their passwords and stuff like that, also I have no idea what to fill into those fields.

Does that mean the feature is in progress and not done yet? In that case I won't try to mess with it and just wait. (I was going to try and implement it.)

[pierredup]

I recently merged #977 which updates the API configuration from annotation to attributes and tries to use some of the newer API Platform features. In the process, some of the configuration got messed up, which is why the payments are listed in the API, but I don't think it's really functional. It should also not have any of the fields you mentioned. So it's an issue that I am aware of that crept in with those changes. You are welcome to try and implement the changes