Support attachments
Public support files are uploaded directly to a quarantine object through a short-lived presigned POST. The platform validates size, checksum, extension, MIME type, magic bytes, and malware status before the file can be attached.Prerequisites: use
tickets.create for purpose ticket or
tickets.comment for purpose ticket_comment. Reading ticket files requires
tickets.read; reading chargeback evidence requires chargebacks.read.Constraints
The declared name, MIME type, exact byte size, and checksum are immutable for the session. Use purpose
ticket only for ticket creation and ticket_comment only for comment creation.
Flow
- Calculate the local file byte length and SHA-256.
- Call
attachment.preparewith a stable top-leveloperation_id. - Submit every field returned in
result.upload.fieldsplus the file toresult.upload.url. - Call
attachment.finalizewith another stableoperation_id. - Wait for status
ready; only then include the attachmenth_idin a ticket/comment mutation.
Prepare and upload
attachment.prepare returns:
fields.key value is a short-lived transport token, not an attachment identifier; it contains no merchant, ticket, chargeback, filename, or checksum data. Do not log, persist, parse, or replace it.
Finalize and check status
Finalize after the object upload succeeds:503; retry the same operation and attachment ID after backoff. Do not attach the file while scanning is incomplete.
Use attachment.status to observe pending, scanning, ready, or consumed:
ready means the ID can be attached exactly once to the matching purpose. consumed means it has already been claimed by its parent. Rejected and expired sessions return a stable attachment error rather than reusable upload data.
Attach to a ticket or comment
Include onlyready IDs:
Download
After rechecking the merchant, parent resource, scope, and internal visibility,attachment.get materializes an opaque storage alias and returns a five-minute URL for that alias:
Error handling
Best practices
- Calculate checksum and size from the exact bytes uploaded, not from a decoded/converted copy.
- Keep presigned form data out of logs and never send it to your frontend analytics.
- Verify a file reaches
readybefore creating the ticket/comment. - Download through a freshly authorized
attachment.getcall rather than caching signed URLs.
