Afterpay Disputes API

{"openapi":"3.1.0","info":{"title":"Disputes","version":"1.0.0"},"paths":{"/v2/disputes":{"get":{"operationId":"retrieve-dispute","summary":"Retrieve Dispute","description":"List disputes within a date range based on certain criteria. This endpoint can be used for debugging or synchronizing the disputes from Afterpay if/when you are unable to use the webhook method.\n","tags":[""],"parameters":[{"name":"order","in":"query","description":"Payment or Order token using which you can filter the list.","required":false,"schema":{"type":"integer"}},{"name":"merchant","in":"query","description":"Merchant token using which you can filter the list.","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Dispute status using which you can filter the list.","required":false,"schema":{"type":"string"}},{"name":"openedAfter","in":"query","description":"Filter disputes that were created on or after this timestamp (inclusive).","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"openedBefore","in":"query","description":"Filter disputes that were created on or before this timestamp (inclusive).","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"offset","in":"query","description":"Offset for the search results.","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","description":"The maximum number of records that you want returned from this request.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/retrieve-dispute_Response_200"}}}}}}},"/v2/disputes/{dispute_id}":{"get":{"operationId":"receive-dispute","summary":"Receive Dispute","description":"Get detailed information about a dispute.","tags":[""],"parameters":[{"name":"dispute_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"application/json","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dispute"}}}}}},"post":{"operationId":"respond-to-dispute","summary":"Respond to Dispute","description":"The Respond to the Dispute endpoint allows a merchant to submit evidence for the dispute. This is only allowed if the dispute is the state `needs_response`.\n\nMerchants only have one opportunity to submit evidence. Once a 200 response is received, this information cannot be updated or changed.","tags":[""],"parameters":[{"name":"dispute_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"application/json","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"When successful, returns the updated dispute object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dispute"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID given to a dispute."},"evidence":{"$ref":"#/components/schemas/evidence","description":"Evidence for the dispute. Note that there should be at least one valid field."}}}}}}}},"/v2/disputes/{dispute_id}/accept":{"get":{"operationId":"accept-dispute","summary":"Accept Dispute","description":"Merchants can call this endpoint to accept a dispute case. The endpoint only works if the dispute is in a non-terminal state (the status is not `won` or `lost`).\n\n> **Note:** Calling the API changes the dispute status to lost.","tags":[""],"parameters":[{"name":"dispute_id","in":"path","required":true,"schema":{"type":"string"}},{"in":"query","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"application/json","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"If successful, returns the updated dispute object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dispute"}}}}}}},"/v2/disputes/files":{"post":{"operationId":"upload-file","summary":"Upload File","description":"Use this endpoint to upload files for disputes.","tags":[""],"parameters":[{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"application/json","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Indicates a successful file upload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/upload-file_Response_200"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"description":"The file you want to upload."},"fileType":{"type":"string","description":"The type of file. Only `dispute_evidence` is supported."}},"required":["file","fileType"]}}}}}},"/v2/disputes/files/{id}":{"get":{"operationId":"retrieve-file","summary":"Retrieve file","description":"Use this endpoint to retrieve files for disputes.","tags":[""],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"query","description":"ID of the file to be retrieved.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Basic authentication","required":true,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"application/json","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Indicates that the file has been retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/retrieve-file_Response_200"}}}},"401":{"description":"Unauthorized. Invalid merchant credentials.","content":{"application/json":{"schema":{"description":"Any type"}}}},"404":{"description":"Not Found. The corresponding entity can't be found for the merchant.","content":{"application/json":{"schema":{"description":"Any type"}}}},"412":{"description":"Precondition Failed. Invalid action for the dispute case, or the refund amount is larger than the refundable amount.","content":{"application/json":{"schema":{"description":"Any type"}}}},"413":{"description":"Request Entity Too Large. The uploaded file is too large. It must be less than 10 MB.","content":{"application/json":{"schema":{"description":"Any type"}}}},"415":{"description":"Unsupported Media Type. Afterpay does not support the filetype of the uploaded file. It must be: GIF, PDF, JPEG, or PNG.","content":{"application/json":{"schema":{"description":"Any type"}}}},"422":{"description":"Unprocessable Entity. Invalid parameter in the Dispute API request.","content":{"application/json":{"schema":{"description":"Any type"}}}},"429":{"description":"Too Many Requests. Too many requests in a short period of time, retry later.","content":{"application/json":{"schema":{"description":"Any type"}}}}}}}},"servers":[{"url":"https://global-api-sandbox.afterpay.com","description":"Sandbox"},{"url":"https://global-api.afterpay.com","description":"Production"}],"components":{"schemas":{"DisputeReason":{"type":"string","enum":["product_not_received","product_unacceptable","credit_not_processed","order_canceled","duplicate","incorrect_amount","paid_by_other_means","fraudulent","fraudulent_merchant"],"description":"The reason for the dispute.","title":"DisputeReason"},"DisputeStatus":{"type":"string","enum":["needs_response","under_review","won","lost","merchant_refunded","merchant_voided"],"description":"The current state of the dispute. Values depend on how the dispute state machine is modeled.","title":"DisputeStatus"},"DisputeClosingReason":{"type":"string","enum":["merchant_accepted","evidence_accepted","evidence_rejected","deadline_expired","customer_cancelled"],"description":"A reason indicating how the final decision on the dispute was reached. Recommended possible values listed in Closing Reasons.","title":"DisputeClosingReason"},"meta":{"type":"object","properties":{"transactionAmount":{"type":"string","description":"The transaction amount for the order."},"network":{"type":"string","description":"The payment network used by the customer. (For example, `Visa` or `MasterCard`)"},"networkReferenceId":{"type":"string","description":"The identifier for the payment."},"orderType":{"type":"string","description":"The type of order. `ONLINE` or `INSTORE`"}},"required":["transactionAmount","orderType"],"title":"meta"},"dispute":{"type":"object","properties":{"id":{"type":"string","description":"Dispute identifier"},"order":{"type":"string","description":"The token of the order that the dispute is for."},"amount":{"type":"string","description":"The amount of the dispute"},"reason":{"$ref":"#/components/schemas/DisputeReason","description":"The reason for the dispute."},"status":{"$ref":"#/components/schemas/DisputeStatus","description":"The current state of the dispute. Values depend on how the dispute state machine is modeled."},"open":{"type":"boolean","default":true,"description":"`True` if a final decision on the dispute hasn't been made yet."},"responseDueBy":{"type":"string","description":"Deadline by which the merchant must respond to the dispute. (Epoch timestamp in seconds, timezone UTC +0.00)"},"createdAt":{"type":"string","description":"A timestamp indicating when the dispute was created. (Epoch timestamp in seconds, timezone UTC +0.00)"},"openingNote":{"type":"string","description":"Text from the customer describing why the dispute was opened or the reason for the complaint. While dispute category codes are helpful at informing what a merchant should present, it doesn’t provide reasoning behind the customer’s complaint. In some cases, this can help merchants troubleshoot the dispute directly with their customers."},"openingNoteAttachments":{"type":"string","description":"Attachments to supplement the `openingNote` if the customer provided photos or screenshots as part of their dispute description."},"updatedAt":{"type":"string","description":"Timestamp when the dispute was updated. (Epoch timestamp in seconds, timezone UTC +0.00)"},"closingReason":{"$ref":"#/components/schemas/DisputeClosingReason","description":"A reason indicating how the final decision on the dispute was reached. Recommended possible values listed in Closing Reasons."},"closingNote":{"type":"string","description":"Text describing in detail how the final decision on the dispute was reached. This supplements the `closingReason`."},"merchantOrderId":{"type":"string","description":"The identifier for the transaction on the merchant side."},"transactionDate":{"type":"string","description":"The timestamp of the order created by the customer. (Epoch timestamp in seconds, timezone UTC +0.00)"},"settlementAmount":{"type":"string","description":"The settlementAmount for audit usage."},"meta":{"$ref":"#/components/schemas/meta","description":"The extra information for merchants to match payment."}},"required":["id","order","amount","reason","status","open","responseDueBy","createdAt","openingNote","closingReason","merchantOrderId","transactionDate","settlementAmount"],"description":"Dispute object","title":"dispute"},"retrieve-dispute_Response_200":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/dispute"},"description":"An array of dispute objects that match the filter criteria in the request."},"offset":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"}},"title":"retrieve-dispute_Response_200"},"evidence":{"type":"object","properties":{"productDescription":{"type":"string","description":"A description of the product or service and any relevant details on how this was presented to the customer at the time of purchase."},"refundPolicy":{"type":"string","format":"binary","description":"Token of the file upload. The merchant’s refund policy, as shown or provided to the customer."},"refundPolicyDisclosure":{"type":"string","description":"An explanation of how and when the customer was shown or provided with the merchant’s refund policy prior to purchase."},"refundRefusalExplanation":{"type":"string","description":"The merchant’s explanation for why the customer is not entitled to a refund."},"shippingDocumentation":{"type":"string","format":"binary","description":"Token of the file upload. A shipping label or receipt for the disputed payment."},"shippingAddress":{"type":"string","description":"The address to which a physical product was shipped."},"shippingDate":{"type":"string","description":"In cases of physical products, the date that a physical product began its route to the shipping address in a clear human-readable format. This date should be prior to the date of the dispute."},"shippingCarrier":{"type":"string","description":"In cases of physical products, the delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, separate them with commas."},"shippingTrackingNumber":{"type":"string","description":"The tracking number for a physical product, obtained from the delivery service."},"uncategorizedFile":{"type":"string","format":"binary","description":"Token of the file upload. Additional file that’s not in any of the categories above."},"uncategorizedText":{"type":"string","description":"Any additional text deemed relevant by the merchant."}},"title":"evidence"},"upload-file_Response_200":{"type":"object","properties":{"id":{"type":"string","description":"The ID token of the file."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp indicating when the file was uploaded."},"expiresAt":{"type":"string","format":"date-time","description":"The timestamp indicating when the uploaded file expires. "}},"title":"upload-file_Response_200"},"retrieve-file_Response_200":{"type":"object","properties":{"url":{"type":"string","description":"The link of the file to be retrieved."},"expiresAt":{"type":"string","format":"date-time","description":"The timestamp indicating the expiration of the link."}},"title":"retrieve-file_Response_200"}},"securitySchemes":{"sec0":{"type":"http","scheme":"basic"}}}}