Shopify Payments Payout and Transaction API Clarification

amdev
Tourist
6 0 3

Hi,

I would like to get some clarification on some properties provided in both Payout (https://shopify.dev/docs/admin-api/rest/reference/shopify_payments/payout?api[version]=2020-07) and Transactions (https://shopify.dev/docs/admin-api/rest/reference/shopify_payments/transaction) API

First of all, in the payout API. I can't seem to find the explanation of each of the properties provided there in the summary. Under each of the payout summary, the following properties are given.

"adjustments_fee_amount": "0.00",
"adjustments_gross_amount": "0.17",
"charges_fee_amount": "0.98",
"charges_gross_amount": "3.95",
"refunds_fee_amount": "0.00",
"refunds_gross_amount": "-1.00",
"reserved_funds_fee_amount": "0.00",
"reserved_funds_gross_amount": "0.00",
"retried_payouts_fee_amount": "0.00",
"retried_payouts_gross_amount": "0.00"

However, I failed to understand the relationship and the use case scenario for each of them. Would you be able to give me an explanation for each of the properties there, please? And is there any sample payload of how it would look like when there is a dispute or refund happening?

In particular, I am quite confused about the properties of "refunds_fee_amount", "adjustments_fee_amount", "adjustments_gross_amount". I originally thought that when there is a refund, a refunds_fee_amount would be presented. However, I quickly realise that it would show up in the adjustments_gross_amount instead. Does that mean I can treat all 3 of these properties the same way, as the refunds fee amount? What's the difference between them?

Secondly, in the Transactions API, I realised that there are many different types of transactions. However, it does not exactly explain to me when I would expect to see each of these transactions (use cases like disputes/refunds) and what does it actually mean? Could you provide me with an explanation for each type of the transaction, please?

And in addition to that, what would be the common transactions flow for a dispute happening? Will it have a reserve transaction first, before having a dispute transaction?

And finally, what's a credit and a debit transaction? And if there is any difference between a credit and a payout transaction?

Sorry for the long question. I would appreciate any assistance anyone of you could provide to me.

Thank you.