Submit evidence for a Justt chargeback

arazzo: 1.0.1
info:
  title: Submit evidence for a Justt chargeback
  version: 1.0.0
  description: >-
    Read an open chargeback, upload an evidence file, submit it to the PSP, and
    poll the asynchronous submission to a terminal state.
  x-realizes-capability-ids:
  - BC-1340.70
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-1340.70
      capability_name: Card Transaction Processing Management
      spec: justt-evidence-api-openapi.yml
      confidence: 0.78
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: chargebacksApi
  url: ../openapi/justt-chargebacks-api-openapi.yml
  type: openapi
- name: evidenceApi
  url: ../openapi/justt-evidence-api-openapi.yml
  type: openapi
- name: filesApi
  url: ../openapi/justt-files-api-openapi.yml
  type: openapi
workflows:
- workflowId: submitEvidenceForChargeback
  summary: Upload and submit an evidence file against an open chargeback
  description: >-
    Evidence submission is irreversible and asynchronous — it can take up to 24
    hours to complete at the PSP. There is no idempotency key on any step, so a
    timed-out call must be reconciled with a read before it is retried.
  inputs:
    type: object
    required: [chargebackId, evidenceFile]
    properties:
      chargebackId:
        type: string
        description: Justt's UUID for the chargeback
      referenceAccountId:
        type: string
        description: Merchant account reference, when one key serves several merchants
      evidenceFile:
        type: string
        format: binary
      purpose:
        type: string
        enum: [evidence_file, evidence_image]
        default: evidence_file
  steps:
  - stepId: getChargeback
    description: Confirm the chargeback exists and is still actionable
    operationId: ChargebackItemController_getChargeback
    parameters:
    - name: id
      in: path
      value: $inputs.chargebackId
    - name: reference-account-id
      in: header
      value: $inputs.referenceAccountId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      pspStatus: $response.body#/data/pspStatus
  - stepId: uploadFile
    description: >-
      Upload the evidence file. The multipart field name must be exactly "file".
    operationId: FilesController_create
    parameters:
    - name: reference-account-id
      in: header
      value: $inputs.referenceAccountId
    requestBody:
      contentType: multipart/form-data
      payload:
        file: $inputs.evidenceFile
        purpose: $inputs.purpose
    successCriteria:
    - condition: $statusCode == 201
    outputs:
      fileId: $response.body#/fileId
  - stepId: submitEvidence
    description: Submit the uploaded file against the chargeback. Irreversible.
    operationId: EvidenceController_submitEvidence
    parameters:
    - name: id
      in: path
      value: $inputs.chargebackId
    - name: reference-account-id
      in: header
      value: $inputs.referenceAccountId
    requestBody:
      contentType: application/json
      payload:
        fileId: $steps.uploadFile.outputs.fileId
    successCriteria:
    - condition: $statusCode == 201
    outputs:
      submitEvidenceId: $response.body#/id
  - stepId: pollSubmissionStatus
    description: >-
      Poll until status is succeeded or failed. Prefer the
      chargeback.evidence.submitted webhook over tight polling.
    operationId: EvidenceController_getEvidenceSubmissionStatus
    parameters:
    - name: id
      in: path
      value: $inputs.chargebackId
    - name: submitEvidenceId
      in: path
      value: $steps.submitEvidence.outputs.submitEvidenceId
    - name: reference-account-id
      in: header
      value: $inputs.referenceAccountId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      status: $response.body#/status
      error: $response.body#/error
  outputs:
    submitEvidenceId: $steps.submitEvidence.outputs.submitEvidenceId
    status: $steps.pollSubmissionStatus.outputs.status