Refunded payment data before/after v2.46
Answered
Hello,
I've read through much of the API documentation and changelog, specifically on the new Orders API refund changes in v2.46, but I still have more questions on how payment data differs before/after these changes. I'm a consumer of the API data for integrations but not a Toast POS user. Could someone please give me some feedback on a few of these questions?
- I understand that credit payment refunds could occur before and after v2.46. I also understand that it's possible for the "refundTransaction" section to be populated only after the v2.46 update. Can you outline whether there are any other differences to the "payments" object(either new/changed fields or altered field values) when a credit payment is refunded, before v2.46 vs. after?
- I understand that cash and gift card payment refunds could not occur until v2.46, and I have read that formally users would void these payments instead. Can you explain whether the user is performing a new action in the POS which is now producing a refunded payment in v2.46 rather than a voided payment, or is it the same action by the user? If it's a new action, is it still possible that users will continue to void payments just as was done prior to this version, or will they be forced to now refund the payments instead of void?
Thanks!
-
Hi Sean,
Sure thing! Here's some info about the new refund functionality.
-
I understand that credit payment refunds could occur before and after v2.46. I also understand that it's possible for the "refundTransaction" section to be populated only after the v2.46 update. Can you outline whether there are any other differences to the "payments" object(either new/changed fields or altered field values) when a credit payment is refunded, before v2.46 vs. after?
Values on the Payment object did not change with the 2.46 refunds change, beyond the changes to the nested Refund object. That said, the "amount" value on the Check object changed with the new refund functionality. For example, say a guest paid $20 and received a $5 refund. Before 2.46, the "amount" value on the check would have been $15 after the refund. With mobile version 2.46 and later, the "amount" on the check is $20 before and after the refund. You can deduce that the total value paid is $15 by seeing that "refundAmount" value on the Refund object (nested under the Payment object) is $5.
-
I understand that cash and gift card payment refunds could not occur until v2.46, and I have read that formally users would void these payments instead. Can you explain whether the user is performing a new action in the POS which is now producing a refunded payment in v2.46 rather than a voided payment, or is it the same action by the user? If it's a new action, is it still possible that users will continue to void payments just as was done prior to this version, or will they be forced to now refund the payments instead of void?
Our documentation about issuing refunds as well as our FAQ for our new refund functionality will probably get you the info you're seeking. I'm also following up to see if there's a basic "before and after" guide you can reference.
I've sent these docs to you separately, but in case others are following this post and would like additional information about the new refund functionality in mobile release 2.46, additional documentation can be found here:
- Refund information in Order objects
- rel20210113 section in API Change Log
0 -
I understand that credit payment refunds could occur before and after v2.46. I also understand that it's possible for the "refundTransaction" section to be populated only after the v2.46 update. Can you outline whether there are any other differences to the "payments" object(either new/changed fields or altered field values) when a credit payment is refunded, before v2.46 vs. after?
-
In our original email exchange, you'd asked for some JSON examples. Here are some JSONs in case it's helpful. (In case anyone is curious, I've modified all GUIDs and identifiers.)
Voided non-credit payment before 2.46 (cash payment in this example):
"payments": [
{
"guid": "cd1e5419-8c74-46d9-9892-b4db7a9191a7",
"entityType": "OrderPayment",
"externalId": null,
"originalProcessingFee": null,
"cashDrawer": null,
"lastModifiedDevice": {
"id": "f3e58d5fe6610ee5"
},
"refundStatus": "NONE",
"type": "CASH",
"voidInfo": {
"voidUser": {
"guid": "f87d63be-971c-47dc-8cbf-68974cdb2b47",
"entityType": "RestaurantUser",
"externalId": null
},
"voidApprover": {
"guid": "f87d63bf-971c-47dc-8cbf-68974ddb2b47",
"entityType": "RestaurantUser",
"externalId": null
},
"voidDate": "2021-02-26T13:59:29.961+0000",
"voidBusinessDate": 20210226,
"voidReason": null
},
"checkGuid": "fe94f3f6-d918-4354-a499-6b64b1b1ec3e",
"otherPayment": null,
"paidDate": "2021-02-26T13:59:21.076+0000",
"orderGuid": "ef40d4db-50e8-47f2-a921-7b19ea6f191d",
"cardEntryMode": null,
"paymentStatus": "VOIDED",
"amount": 50.0,
"tipAmount": 0.0,
"amountTendered": 50.0,
"cardType": null,
"houseAccount": null,
"mcaRepaymentAmount": null,
"createdDevice": {
"id": "f3e58d5fe6610ee5"
},
"paidBusinessDate": 20210226,
"last4Digits": null,
"refund": null
}
]Refunded non-credit payment after 2.46 (voidInfo is null and paymentStatus is 'CAPTURED'):
"payments": [
{
"guid": "a6bd4a5e-c51a-49f5-ae36-f0cbd05aab8f",
"entityType": "OrderPayment",
"externalId": null,
"originalProcessingFee": null,
"cashDrawer": {
"guid": "0e5704e2-d0f5-40bd-9a84-950359e35c23",
"entityType": "CashDrawer",
"externalId": null
},
"lastModifiedDevice": {
"id": "f9edf38e91fc1b8"
},
"refundStatus": "FULL",
"type": "CASH",
"voidInfo": null,
"checkGuid": "1881cd3b-b82c-4a7d-ba22-f603c91fb11b",
"otherPayment": null,
"paidDate": "2021-03-10T18:29:40.594+0000",
"orderGuid": "aa0efc41-5d31-40e3-8424-3ccd8273d86a",
"cardEntryMode": null,
"paymentStatus": "CAPTURED",
"amount": 182.31,
"tipAmount": 0.0,
"amountTendered": 200.0,
"cardType": null,
"houseAccount": null,
"mcaRepaymentAmount": null,
"createdDevice": {
"id": "f9edf38e91fc1b8"
},
"paidBusinessDate": 20210310,
"last4Digits": null,
"refund": {
"refundAmount": 182.31,
"tipRefundAmount": 0.0,
"refundDate": "2021-03-11T17:46:41.180+0000",
"refundBusinessDate": 20210311,
"refundTransaction": {
"guid": "59cfd0cb-ce12-4000-a948-a7138648a38a",
"entityType": "RefundTransaction"
}
}
}
]Voided non-credit payment after 2.46 (voidInfo is populated, refund is null, paymentStatus is 'VOIDED'):
"payments": [
{
"guid": "9706c954-7ef3-4a30-adc9-32acca6b8264",
"entityType": "OrderPayment",
"externalId": null,
"originalProcessingFee": null,
"cashDrawer": {
"guid": "44d60ec5-f480-4ed3-8daa-23426dda42cf",
"entityType": "CashDrawer",
"externalId": null
},
"lastModifiedDevice": {
"id": "6352c9576ca8e1de"
},
"refundStatus": "FULL",
"type": "CASH",
"voidInfo": {
"voidUser": {
"guid": "37b25306-9b31-4c0d-bf62-1a9a7272c499",
"entityType": "RestaurantUser",
"externalId": null
},
"voidApprover": {
"guid": "37b25306-9b31-4c0d-bf62-1a9a7272c499",
"entityType": "RestaurantUser",
"externalId": null
},
"voidDate": "2021-04-30T01:51:37.475+0000",
"voidBusinessDate": 20210429,
"voidReason": null
},
"checkGuid": "f15ad160-8d46-4f58-a4e0-1df6a67ecdf1",
"otherPayment": null,
"paidDate": "2021-04-30T01:50:46.951+0000",
"orderGuid": "f58f6fc4-c246-418b-b5ca-cbb8d7ed679b",
"cardEntryMode": null,
"paymentStatus": "VOIDED",
"amount": 8.96,
"tipAmount": 0.0,
"amountTendered": 50,
"cardType": null,
"houseAccount": null,
"mcaRepaymentAmount": null,
"createdDevice": {
"id": "6352c9576ca8e1de"
},
"paidBusinessDate": 20210429,
"last4Digits": null,
"refund": null
}
]0 -
Hi Liz,
Thank you for sending this info. My questions from my first bullet are answered, stating that no fields/values on the Payments object changed in 2.46 for credit payment refunds aside from the data changes within the Refund object.
Regarding the second bullet and more specifically your third JSON example of a Voided non-credit payment after 2.46, it appears that the payment record has a Payment Status of "VOIDED", yet there is still a Refund object present which has a "refundAmount" value as well as an associated "refundTransaction".
From the documentation link, I see the below message outlined:
Refunds are still only supported on checks from previous days -- reversals of credit card, cash, or Toast gift card payments on the same day are considered voids. Items and checks should no longer be voided before or after a refund is issued.
This message seems to indicate that voiding and refunding payments are separate transactions, yet the JSON response seems to indicate that the payment is both a void and a refund at the same time. Can you outline how this can be? After 2.46, is there the possibility of a voided payment which does not also have this same refund data present, or can I expect that all voided payments will come through with this refund data?
Thanks,
Sean0 -
Hi Sean,
Good catch about the refund object being populated on the voided cash payment. I followed up with our refunds expert to ask for additional information about this, and it turns out the voided cash payment example I grabbed had erroneously-populated data, which we're looking into. I've updated the third JSON example to reflect how voided payment data will be populated, which includes a populated "voidInfo" value and a null "refund" value.
Let me know if this helps clarify. To summarize the different scenarios for non-credit card payments:
- Voided, pre-2.46: Payment status = "VOIDED", "voidInfo" is populated, "refund" is null
- Voided, 2.46 and later: Payment status = "VOIDED", "voidInfo" is populated, "refund" is null (same as pre-2.46)
- Refunded, pre-2.46: Not possible, just adding this item for the sake of completeness
- Refunded, 2.46 and later: Payment status = "CAPTURED", "voidInfo" is null, "refund" is populated
Let me know if you have additional questions!
0 -
Hi Liz,
Thank you for the feedback, this is helpful. I have a few more questions/requests about refunded payments to tack on:
- We utilize paid-out data, which are from payment objects which have specific payment types. For example, the list of payment types shown below may be a list we will use. Can payments of these types be refunded? If so, would the examples be the same as other “non-Credit” payments? If there is any difference in the JSON between these payment types and the "non-Credit" payments, can you offer example JSON?
○ PAY_OUT
○ CASH_IN
○ CLOSE_OUT_SHORTAGE
○ CLOSE_OUT_OVERAGE- For credit payment refunds, the only examples we’ve seen have a “refundAmount” value, but have a value of ‘0.0’ in the “tipRefundAmount” field. It’s understood from the user documentation that a user could choose to refund a tip along with the credit payment, or even refund just a tip on it’s own. Can you offer JSON examples that show a payment with tip included, and another with just a tip refund?
Thanks!
0 -
Hi Sean,
The types in the bulleted list correspond to cash entries rather than payments, and these transactions therefore can't be refunded in the same sense as a payment. Cash entries can be undone, meaning that they can be reversed, but there will not be payment-level refund information on orders associated with the undoing of the cash entries. More information about undoing cash entries can be found in the "Undone Cash Entries" section at the bottom of this page.
In terms of a refunded payment with a refunded tip, here's a sample JSON. Let me know if you have additional questions, and we'll be more timely with our next response!
"payments": [
{
"guid": "a345b0b1-6d7c-478b-8730-5ba947973888",
"entityType": "OrderPayment",
"externalId": null,
"originalProcessingFee": 0.0,
"server": {
"guid": "f440215d-49f1-46ce-b9cd-d5e11443e28d",
"entityType": "RestaurantUser",
"externalId": null
},
"cashDrawer": null,
"lastModifiedDevice": {
"id": "dc81718053acda1c"
},
"refundStatus": "FULL",
"type": "CREDIT",
"voidInfo": null,
"checkGuid": "33debad1-7cbb-4886-805b-68893681116a",
"otherPayment": null,
"paidDate": "2021-05-16T02:30:51.745+0000",
"orderGuid": "3a4f0e9f-5694-4b04-a8a0-3412647d1a24",
"cardEntryMode": "ONLINE",
"paymentStatus": "CAPTURED",
"amount": 117.18,
"tipAmount": 28.82,
"amountTendered": 0.0,
"cardType": "VISA",
"houseAccount": null,
"mcaRepaymentAmount": 0.0,
"createdDevice": {
"id": "dc81718053acda1c"
},
"paidBusinessDate": 20210515,
"last4Digits": "1111",
"refund": {
"refundAmount": 117.18,
"tipRefundAmount": 28.82,
"refundDate": "2021-05-16T17:18:58.402+0000",
"refundBusinessDate": 20210516,
"refundTransaction": {
"guid": "8b458963-dee3-4e58-882a-a0b11d7d2c3c",
"entityType": "RefundTransaction"
}
}
}
]0
Please sign in to leave a comment.
Comments
6 comments