Filtering Payments (using status) possible?

[holtkamp]

The PHPDoc of the Payments resource suggests that one can use a filter. I would expect that such a filter would allow to fetch only specific Payments, something like:

$filter = array('status' => 'paidout');

But this seems not to work. Using an incorrect filter DOES trigger an error:

$filter = array('state' => 'paidout'); //Note that 'state' is not a valid Payment property

Results in

 [Mollie_API_Exception]                                     
  Error executing API call (request): Unknown field: state.

Looking at the API documentation, it seems this kind of filtering is not supported for Payments? https://www.mollie.com/nl/docs/reference/payments/list

So why does the PHPDoc suggest this?

[willemstuursma]

I am sorry, we don't offer any filtering in the Payments resource.

The parameter is confusingly named. It is used for adding things to the query string, e.g. for offsets, counts, includes and excludes.

I'll see if we can clear this up.

[holtkamp]

I'll see if we can clear this up.

thanks for the response. Might be easier to "just" add support for filtering? 😇

[willemstuursma]

What kind of use cases do you have?

[holtkamp]

Uhm, like iterate over all paidout payments and process them appropriately in our administration.

The callback mechanism that Mollie offers does not 'consider' the 'paidout' state, so we need to periodically 'check' whether payments were paidout...

[willemstuursma]

Thanks, this use case is clear. I'll take it up here and see how we can (best) support this.

[zchermit]

+1 for filtering. I want to filter payments by "pending" status for sending them an email notifications.

[holtkamp]

Thanks, this use case is clear. I'll take it up here and see how we can (best) support this.

@willemstuursma any (rough) ETA for this? Or... "someday" 😄

[willemstuursma]

Sorry @holtkamp, it's going to be someday.

[holtkamp]

@willemstuursma do you guys have a suggested workaround? Fetch all Payments (current maximum is 250 per batch) iterate them ourselves and determine the status like that?

For some operations (like sending Payments ourselves) we need to make sure we received the Payment from Mollie / paidout Payments.

[willemstuursma]

For this situation, it would be best to use the Settlements API and then use the paymentIds property to get the settled payments.

If you need an OAuth token but don't want to create an app, we can create a token for you with the right scopes. You can contact our support department for that (please mention this Github issue).

[holtkamp]

For this situation, it would be best to use the Settlements API and then use the paymentIds property to get the settled payments.

Ok, thanks, will dive into that approach.

If you need an OAuth token

no, not needed, but thanks for the pointer 😄

[Smitsel]

Hi @holtkamp,

Our new v2 client might help you with your use case.

You could iterate the settlements and use the $settlement->payments() when the settlement has Mollie\Api\Types\SettlementStatus:: STATUS_PAIDOUT

[holtkamp]

Thanks, will have a look! Compliments for the documentation at https://docs.mollie.com/migrating-v1-to-v2

I Noticed you guys did not use this opportunity to upgrade to PHP 7.1?

[willemstuursma]

We'll move to PHP ^7.0 once PHP 5.6 loses its security support, so Jan 2019.

[toonvandeputte]

Good to know! Is there a roadmap for these planned updates somewhere?

[holtkamp]

@Smitsel about https://github.com/mollie/mollie-api-php/issues/84#issuecomment-387736422

am I correct that this is not really different from using the v1 Settlement API and loading the paymentIDs as was suggested in https://github.com/mollie/mollie-api-php/issues/84#issuecomment-342125767

I encountered the need to "filtering" / searching Payments again: to see whether a Mollie Payment was used to pay a Moneybird Invoice, the Payment.description can be used which would be in the format: $moneybirdInvoiceReference ($moneybirdInvoiceId).

In case no filtering is possible, all Payments need to be iterated... Seems not really efficient. Suggestions are welcome of course!

[willemstuursma]

@holtkamp filter all you want, we are ready for it. You wouldn't believe what API traffic some consumers are causing, so it won't affect us.

Feel free to report API calls that are taking too long in your opinion.

[sandervanhooft]

A thought for the weekend... 😄

The filtering feature mentioned by @holtkamp is in fact an opinionated API design paradigm if applied consistently. It's also advocated in "Build APIs You Won't Hate" by Phil Sturgeon. (Conceptually still applicable, although technically a bit outdated).

Right now I see a lot of sub(sub?)resources being added to Mollie's services to tackle problems that could be alternatively solved by using filters.

For example, instead of using /subscriptions/<id>/payments

you could use /payments?filters=subscriptionId:sub_k23hu4e.

It's fine either way.

The former is easier on the eyes and easier to test, the latter is easier to maintain/extend. Probably also more versatile, because you would be able to combine multiple filters. I would love this, also as a search function.

And yes, the $filters variable also got my hopes up. Would be appropriate to rename it, but I don't know of a better word atm.

[willemstuursma]

In practice it is very hard to offer a public API where arbitrary combinations of filters are allowed. The size and cardinality can be wildly different between API consumers, leading to unpredictable query plans on the storage layers. Unpredictable query plans lead to outages affecting multiple merchants, which is a no-no.

These problems can be solved with custom solutions but this is expensive and only few consumers benefit from this.

I'm closing this issue as filtering payments on status is not high on our priority list right now.

Requests for changes in priorities can best be made through our sales department.