Confirm a signature instruction is still pending, then cancel it.

arazzo: 1.0.0
info:
  title: Cancel a device signature instruction
  summary: Abort a still-pending Payroc Cloud device signature instruction before
    the customer signs.
  description: |
    Cancels a signature instruction that was submitted to a Payroc Cloud payment device (via the capture-signature-on-a-device workflow) while it is still `inProgress` — when the customer will not sign — so no signature is captured.
    Agent gotchas captured here:
    - `deleteSignatureInstruction` (HTTP 204) cancels a still-pending instruction.
      An instruction that is already `completed` or `failed` cannot be canceled
      (409), so confirm the status with `getSignatureInstruction` first and run
      this only while the instruction is `inProgress`.

    - Canceling is mutually exclusive with retrieving the signature (see the
      capture-signature-on-a-device workflow, whose terminal outcome is a captured
      signature image).
  version: 1.0.0
sourceDescriptions:
  - name: payroc-api
    url: /openapi.yaml
    type: openapi
workflows:
  - workflowId: cancel-a-device-signature-instruction
    summary: Confirm a signature instruction is still pending, then cancel it.
    description: |
      Optionally confirm the instruction is still `inProgress` (getSignatureInstruction), then cancel it (deleteSignatureInstruction) using the `signatureInstructionId` returned when the instruction was submitted.
    x-actors:
      - id: merchant
        name: Merchant / integrator
        type: client
        description: Calls the Payroc API to abort the pending signature capture.
      - id: payroc-gateway
        name: Payroc gateway
        type: api
        description: The Payroc API surface these steps call.
      - id: payment-device
        name: Payroc Cloud payment device
        type: external-system
        description: In-person Payroc Cloud device that holds the pending instruction;
          not directly callable as an API step.
    inputs:
      type: object
      required:
        - signatureInstructionId
      properties:
        signatureInstructionId:
          type: string
          description: Identifier of the signature instruction to cancel, as returned by
            sendSignatureInstruction in the capture-signature-on-a-device
            workflow.
          example: a37439165d134678a9100ebba3b29597
    steps:
      - stepId: getSignatureInstruction
        x-actor: merchant
        x-actor-to: payroc-gateway
        x-label: instruction status check
        description: |
          OPTIONAL — confirm the instruction is still `inProgress` before canceling, via GET /signature-instructions/{signatureInstructionId}. Cancel is only allowed while the status is `inProgress`.
        operationId: getSignatureInstruction
        parameters:
          - name: signatureInstructionId
            in: path
            value: $inputs.signatureInstructionId
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          status: $response.body#/status
      - stepId: cancelSignatureInstruction
        x-actor: merchant
        x-actor-to: payroc-gateway
        x-label: instruction cancellation
        description: |
          Cancel the signature instruction via DELETE /signature-instructions/{signatureInstructionId}. Valid only while the instruction's status is `inProgress`. Returns HTTP 204 with no body.
        operationId: deleteSignatureInstruction
        parameters:
          - name: signatureInstructionId
            in: path
            value: $inputs.signatureInstructionId
        successCriteria:
          - condition: $statusCode == 204
    outputs:
      signatureInstructionId: $inputs.signatureInstructionId