API reference / Disputes
Send the usage of the customer for a dispute
Gives Troopy what your own records show of the customer of one dispute: the account, a summary, the events and pictures. Troopy puts them in the evidence as the records of the business. Call it from your backend when the payment provider tells you of the dispute (charge.dispute.created in Stripe, dispute.opened in Dodo Payments), with the provider's id of the dispute. When Troopy does not know the dispute yet, it reads it from the provider at once. A new call replaces the usage of the dispute. At most 20 summary lines, 500 events and 4 pictures (JPEG or PNG, 300 KB each). Send only what is true: the bank reads it.
/api/v1/disputes/{id}/usageOther ways to call it
troopy disputes usageIdempotency-Key header. A retry with the same key gets the first answer back, and the operation runs one time.Path parameters
id*stringThe id of the dispute in Troopy, or its id at its payment provider, like du_1MtJUT2eZvKYlo2C in Stripe
At least 1 characters · At most 80 characters
Body
application/jsoncustomerobjectDefault {}
4 properties
idstringThe id of the account in your product
At most 120 characters
emailstringAt most 254 characters · email
namestringAt most 120 characters
createdAtstringWhen the account was made
date-time
summaryarray<object>Totals in your own words, like { "label": "Videos made", "value": "38" }
Default [] · At most 20 items
2 properties
label*stringAt least 1 characters · At most 80 characters
value*stringAt least 1 characters · At most 300 characters
eventsarray<object>Default [] · At most 500 items
5 properties
at*stringdate-time
action*stringWhat the customer did, like Signed in or Video made
At least 1 characters · At most 80 characters
detailstringAt most 300 characters
ipstringThe address that the customer came from
devicestringThe device or browser, like Chrome on Windows
At most 120 characters
picturesarray<object>What the customer made or got, like a thumbnail
Default [] · At most 4 items
2 properties
captionstringDefault "" · At most 200 characters
content*stringA JPEG or a PNG, base64-encoded
At most 400004 characters · base64
Response
200 · application/jsondata*object3 properties
dispute*object18 properties
id*stringA 24-character id
provider*enum<string>The payment provider of the disputed payment. stripe: Troopy sends the evidence. dodopayments: a person uploads the evidence in the dashboard of Dodo Payments. paddle: Paddle answers by itself, and takes no evidence
stripedodopaymentspaddle
providerId*stringThe id of the dispute at its provider. For Paddle, the id of the disputed transaction
live*booleanfalse: a dispute of the test mode of the provider
amount*numberThe disputed amount, in the units of its currency
currency*stringreason*stringThe reason, in the words of Stripe: fraudulent, subscription_canceled or general, for example
status*stringThe status, in the words of Stripe for each provider: needs_response, under_review, won, lost, prevented, or one of the warning_ statuses of an inquiry
customer*object3 properties
id*string | nullemail*string | nullname*string | nullfiledAt*stringISO 8601 date and time
dueBy*string | nullWhen the provider stops taking an answer
stage*enum<string>Where Troopy is with it. preparing: it collects the evidence. waiting: the evidence waits for a person. submitting: it goes now. unknown: nobody knows if it went, and Troopy reads the dispute again. submitted: it went. let_go: a person decided not to answer. none: the provider takes no answer
preparingwaitingsubmittingunknownsubmittedlet_gonone
why*string | nullWhy it waits for a person, or what went wrong
usage*enum<string>The usage that the backend of the business sends. wanted: Troopy waits for it
nonewantedreceived
submittedAt*string | nullsubmittedBy*object | nullWho submitted the evidence, or said that it went. Under a grant: the person who granted it
3 properties
type*enum<string>personagentapi
id*stringname*stringauto*booleanWhether the evidence went under a grant, without a person
url*stringThe dispute, or its payment, in the dashboard of its provider
events*integerpictures*integer