Settlements in the sandbox

Dear all,

I pray you are well.

I just tried to fade the V1Settlements API and it seems it was deprecated in only the last couple of days. The corresponding Java API method is deprecated too. What is its replacement?

Also, how do I create test settlements in the sandbox to test my code?


The V1 Settlements API has technically been deprecated, but it does not currently have a replacement so you still can use it if needed. There’s no way to create settlements in the sandbox environment unfortunately.

Thank you @sjosey for that response, very helpful. Of course, it would have been nicer if the Settlements could be mocked in the sandbox, but knowing it’s not possible saved me wasting time figuring out how to do it!

It’s a little unusual to deprecate an API before it has a replacement, so I need to ask: is a replacement planned? I don’t want to depend on a deprecated API and then later find out it has been retired and my code stops working…

Apologies for the issues you are experiencing with v1 Settlements.
If you don’t mind sharing your use case it will help us create a better experience and APIs in the future. Mainly what data do you need, what is the use case for the settlement API, and how does it work in your application?


Dear @jarred,

Thank you for your response and taking an interest in my use case. I will describe my use case more fully - maybe once you understand it you might be able to tell me if a superior alternative exists.

I am trying to integrate Square payments with our Open Source accounting software. I’ve looked at the Device API and Terminal API, played with them in the sandbox, and I’m pretty sure I can integrate the POS side of things with a minimum of manual input required, without out too much difficulty. But I’m trying to integrate and automate the back end as well: to import the payments and automatically reconcile them against our bank statement.

As I understand it, Square will collect payments, and then transfer the amount (nett of any fees collected by Square and other application providers) according to a defined schedule (which could even be manual rather than automatic).

The V2 Payments API gives me everything I need to import the payments via the ListPayments call (I’ve already mocked this up and tested it). But only the Settlements API gives me what I need to be able to reliably reconcile the individual payments against the corresponding line in our bank statement - it tells me the amount transferred, and the payments that the settlement is comprised of.

Without the Settlements API, I have to guess which payments comprise the amount transferred. I can try and infer this based on what I calculate the transfer schedule should be and assuming that the full balance is transferred each time, but I can forsee that this approach could be unreliable. For example, the standard transfer schedule is quite complicated and depends on things like bank holidays which might make my calculated transfer schedule diverge from the real one. Also, if I am relying on the calculated transfer schedule and someone changes the actual schedule (eg, changes the close-of-day time or sets it to manual in the dashboard), then that would mess it up. With the Settlements Api, changes like these would be automatically taken into account. The settlements also provides me with a double-check as I know what value to expect in my bank statement line, and if there is a discrepancy it can be flagged for investigation.

I also considered an alternative approach: I could model the real bank account and the Square account both as “bank accounts” in our accounting package (call them B1 & B2 respectively), and then model each settlement as an internal bank account transfer from B2 to B1. This would also work into the future if Square ever shifted to a model where you might transfer part of the Square balance rather than all of the balance. But for this model to work reliably, I need to be able to double-check to make sure that B2’s closing balance is the same as that actual closing balance reported by the Square itself (and alert if there is a discrepancy). This could be done manually (the bookkeeper logs in to check that the account amounts match up) but it would be nicer if it could be done automatically. My understanding is that Square does not provide this functionality at the moment either.

Is this clear? Do you have any thoughts? If there’s any way to do the equivalent of the above using the V2 Api that is reliable and automatic, I’m all ears!

@jarred @sjosey , I pray you are well. Sorry to bug you, just wondering if you had an update on this? Is a replacement for the settlement API planned? I know I can use the V1 settlements API for now, but I don’t want to commit to that if it won’t be replaced. Blessings!

Definitely plans to replace it now that it’s deprecated, but I do not have an ETA on the replacement at this time unfortunately.

Thank you @sjosey. My biggest concern is that it wouldn’t be replace and some time soon it would also be removed, which would leave me in a hole. Knowing that it will be replaced is sufficient for me to have confidence using it. Thanks!

:wave: Hi all! We’re excited to unveil the v2/payouts API in beta! This API will replace the v1/settlements API, which will be retired in 2023.You can use the Payouts API to automatically reconcile sellers’ bank deposits or debits with their payments taken with Square in production and sandbox. You can retrieve a list of payouts or individual payouts and compare their amounts with the deposit or debit amounts on the bank statement. You can also list all of the payout entries associated with a payout so you can reconcile at a transaction level in your accounting system.

To get started visit the Payouts API documentation page. Feel free to ask questions or provide feedback here! :slightly_smiling_face:

1 Like