Skip to main content

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

  1. Calculate the local file byte length and SHA-256.
  2. Call attachment.prepare with a stable top-level operation_id.
  3. Submit every field returned in result.upload.fields plus the file to result.upload.url.
  4. Call attachment.finalize with another stable operation_id.
  5. Wait for status ready; only then include the attachment h_id in a ticket/comment mutation.

Prepare and upload

attachment.prepare returns:
Treat every upload URL and field as opaque. The required 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:
Finalization is idempotent. A malware scanner or storage outage fails closed with HTTP 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 only ready IDs:
An attachment cannot be reused for another ticket/comment, used across merchants, or attached under the wrong purpose. Unlinked ready files are cleaned up after 24 hours; expired and rejected objects are cleaned separately.

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:
The API never signs a legacy/internal source key. The URL contains only an opaque alias and file bytes still move directly from object storage, not through the public API endpoint. Signed URLs must nevertheless be treated as secrets until they expire.

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 ready before creating the ticket/comment.
  • Download through a freshly authorized attachment.get call rather than caching signed URLs.