If a merchant experiences a dispute / chargeback, where does that appear in the Square Connect API? As a refund? As a negative payment? Is there another endpoint specifically for this event?
Thanks for pointing out this gap in the documentation. I've updated this answer with the definitive settlement entry type.
Events like chargebacks are reflected in the entries of Settlement objects returned by the List and Retrieve Settlement endpoints. All chargeback-related settlement entries have the type HOLD_ADJUSTMENT. These entries can indicate the placing of a hold on disputed funds, or the subsequent release of a hold if a chargeback is won by the merchant.
Chargebacks are not reflected in payment- or refund-related endpoints.
Related
I understand that the Square POS API does not currently support the ability for an external app to pass itemized line items when calling Square to process the payment. Is there a way for the external app to associate the itemized details with the completed sale transaction in Square via an API after the payment is completed and square returns control to the external app?
Are there specific plans to provide support for itemized transactions within the POS API?
There's no way to formally do this currently, and there's no current timeline or guarantee that it will be released for the POS API.
It's possible to link it via the Orders API in a workaround. Basically, prior to initializing the transaction, you would call CreateOrder with the items in the order. The response would give you an Order object, which you can retrieve the order_id from. Then, you can pass in the order_id into the notes field when creating the POS API request. This would allow you to at least look up the itemization later on (by utilizing BatchRetrieveOrders) for each of the POS API transactions.
Furthermore, if you are going further and utilizing your own database, then you wouldn't even need to pass in the order_id to the note field, as you could just link the order_id and transaction_id in your own database for easy lookup later.
References:
https://docs.connect.squareup.com/more-apis/orders/overview
https://docs.connect.squareup.com/api/connect/v2#navsection-orders
I'm trying to create a recurring payment on Square, ala Stripe subscriptions. However, I am having trouble retrieving a customer's card information (specifically customer_card_id) to pass into Charge.
Our flow is such:
A customer visits to our store and subscribes to a membership, which we process via the point of sale app.
We continuously poll Square to retrieve payment information, and create membership records appropriately.
When the user's membership period expires, charge them for the next month's membership.
When researching RetrieveCustomer, I find that there is a cards property under Customer, but iterating through all the Customers under our account, they all have cards = None despite us having taken card payments via the point of sale app.
Also, looking at ListTransactions, there doesn't seem to be anything that might be customer_card_id. The IDs I see there are tender ID, location ID, and transaction ID. The card_fingerprint also looks promising but that doesn't seem right either, since a card can have both an ID and a fingerprint.
Am I missing something? Where might I find customer_card_id?
EDIT
Looks like I was dumb and my local instance of our application was just out of date with transactions from Square. After updating my data with customers we've processed since the last time I updated, customers with a non-None card property now show up. tristansokol's answer below is still valid however.
How do you process the first charge? You need to explicitly add the card on file, it won't be added by default from processing a transaction from a customer. See: https://squareup.com/help/us/en/article/5770-use-card-on-file-with-the-square-point-of-sale-app
When we wrote or initial integration for Square v1 API, there wasn't an option to filter ListOrders by Date
Our questions for v2 api:
In v2, looks like all transactions are housed under the same endpoint.
Okay, we call GET /transactions
How do we tell what is an order vs. payment vs. refund in the response?
not all payments are generated off an order. For example, I can do one-off Square transactions on my phone for walk-up customers, which would not have an order associated with it)
Can we filter for orders only?
Does the Transaction endpoint supports date filtering now?
Thank you for your time
Take a look at the documentation for the v2 Transaction object. Refunds and orders are subsets of that object.
Also look at the documentation for the List Transactions where you can see that you can currently filter based on times only right now.
If it isn't listed in the documentation, then it probably isn't supported.
I am using GET /v1/{location_id}/payments to list all payments.
I am not able to identify Voids/Comps transaction from the list. Also how to get total number of Items Comped/Voided along with amount and reason using API?
Comped and Voided transactions are not currently identifiable via API.
If a merchant issues a refund, does it show up in both the Refunds List and Retrieve Payment endpoint? Are there situations in which it may show up in one, but not the other (such as Cash, Check, or other Tender Types)?
The use case is an external app storing / caching payments where refunds need to update the stored payments to keep accurate sales figures. If refunds show up in both places, then it seems the best way to update stored payments in this use case is to load the Refunds List periodically and update the stored payment using the Retrieve Payment endpoint.
Regardless of tender type, every refund is available both from the List Refunds endpoint and from the List/Retrieve Payment endpoints. Your solution sounds like a good one, since the List Refunds endpoint is chronological by date of refund, as opposed to date of original payment.
You can use the payment_id included in the returned Refund objects to look up your stored copy of the corresponding payment.