List, retrieve, then update (replace) a funding instruction.

arazzo: 1.0.0
info:
  title: Update a funding instruction
  summary: Find a funding instruction, retrieve it, then replace its
    funds-distribution details.
  description: |
    Post-creation update of a funding instruction. A funding instruction tells Payroc how to distribute a merchant's available funding balance to one or more funding accounts by ACH. Once an instruction exists (created via Create Funding Instruction, operationId `createInstruction`, which is out of scope here), this workflow lets you find it, confirm its status, and replace its distribution details. Read-then-act: list instructions in a date range, take a result, retrieve it to confirm the action is permitted, then update it.
    Agent gotchas captured by this workflow:
      - `instructionId` is an INTEGER, not a string (example 64643131). The path
        parameter, the list `data` entries, and the retrieved resource all use the
        integer form.
      - The list response is paginated: instructions live in the `data` array
        alongside pagination fields. To act on a result, reach into
        `data/0/instructionId` - not a top-level field. On a single retrieved
        instruction, `instructionId` IS top-level.
      - `listInstructions` REQUIRES both `dateFrom` and `dateTo` query parameters
        (YYYY-MM-DD); `before`/`after`/`limit` are the optional pagination filters.
      - You can update an instruction ONLY while its `status` is `accepted`.
        Retrieve first and check `status`; acting on a non-`accepted` instruction
        returns 409 Conflict (cannot be modified).
      - `updateInstructions` is a PUT that returns 204 No Content - there is
        nothing to capture from its response. The list and retrieve steps are
        GET (200).
      - The update body is a full replacement of the instruction's `merchants`
        (and optional `metadata`); each recipient needs `fundingAccountId`,
        `paymentMethod` (`ACH`), and `amount.value`.

    To delete a funding instruction instead, use the delete-a-funding-instruction workflow.
  version: 1.0.0
sourceDescriptions:
  - name: payroc-api
    url: /openapi.yaml
    type: openapi
workflows:
  - workflowId: update-a-funding-instruction
    summary: List, retrieve, then update (replace) a funding instruction.
    description: |
      First list funding instructions within a date range (listInstructions), take the first result's `instructionId`, and retrieve it (getInstruction) to confirm its `status` is `accepted`. Then update it (updateInstructions). The update requires the instruction to still be in `accepted` status, otherwise the gateway returns 409. The list and retrieve steps are optional when you already hold the instructionId.
    x-actors:
      - id: integrator
        name: Integrator
        type: client
        description: Finds and updates the funding instruction; the only API caller in
          this workflow.
      - id: payroc-gateway
        name: Payroc gateway
        type: api
        description: The Payroc API surface these steps call.
    inputs:
      type: object
      required:
        - dateFrom
        - dateTo
      properties:
        dateFrom:
          type: string
          format: date
          description: |
            Required. Return funding instructions sent on or after this date, in YYYY-MM-DD format. Instructions older than two years are not listable.
          example: 2024-07-01
        dateTo:
          type: string
          format: date
          description: Required. Return funding instructions sent on or before this date,
            in YYYY-MM-DD format.
          example: 2024-07-03
        before:
          type: string
          description: |
            Optional pagination cursor. Return the previous page of results before this value. Cannot be sent together with `after`.
          example: "25"
        after:
          type: string
          description: |
            Optional pagination cursor. Return the next page of results after this value. Cannot be sent together with `before`.
          example: "25"
        limit:
          type: integer
          description: Optional. Maximum number of funding instructions to return per page.
          example: 2
        instructionId:
          type: integer
          description: |
            Integer identifier of the funding instruction to update. Normally taken from the list step, but can be supplied directly (for example, to reach an instruction older than two years).
          example: 64643131
        merchantId:
          type: string
          description: Merchant ID (MID) whose funding balance the updated instruction
            distributes.
          example: "9876543219"
        fundingAccountId:
          type: integer
          description: Integer identifier of the funding account that receives the funds.
          example: 124
        amountValue:
          type: integer
          description: Amount to send to the funding account, in the currency's lowest
            denomination (cents).
          example: 69950
        currency:
          type: string
          description: Currency of the amount value.
          example: USD
        metadata:
          type: object
          description: Optional custom key/value data to store with the instruction.
          additionalProperties:
            type: string
          example:
            instructionCreatedBy: Jane Doe
    steps:
      - stepId: listInstructions
        x-actor: integrator
        x-actor-to: payroc-gateway
        x-label: list funding instructions
        description: |
          OPTIONAL — list funding instructions sent within the required `dateFrom`/`dateTo` window, optionally paginated with `before`/`after`/`limit`. The response is paginated - instructions are in the `data` array. This step extracts the first instruction's integer `instructionId` for the follow-on steps.
        operationId: listInstructions
        parameters:
          - name: dateFrom
            in: query
            value: $inputs.dateFrom
          - name: dateTo
            in: query
            value: $inputs.dateTo
          - name: before
            in: query
            value: $inputs.before
          - name: after
            in: query
            value: $inputs.after
          - name: limit
            in: query
            value: $inputs.limit
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          firstInstructionId: $response.body#/data/0/instructionId
          firstInstructionStatus: $response.body#/data/0/status
      - stepId: getInstruction
        x-actor: integrator
        x-actor-to: payroc-gateway
        x-label: get funding instruction
        description: |
          OPTIONAL — retrieve the full detail of the first funding instruction from the list. Inspect `status` (`accepted`, `pending`, or `completed`) to confirm the instruction can still be updated - only an `accepted` instruction may be modified. `instructionId` is top-level here.
        operationId: getInstruction
        parameters:
          - name: instructionId
            in: path
            value: $steps.listInstructions.outputs.firstInstructionId
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          instructionId: $response.body#/instructionId
          status: $response.body#/status
      - stepId: updateInstruction
        x-actor: integrator
        x-actor-to: payroc-gateway
        x-label: update funding instruction
        description: |
          Replace the merchant funds-distribution details of the instruction retrieved above, using its integer `instructionId`. Only works while `status` is `accepted`; otherwise the gateway returns 409 (cannot be modified). The body is a full replacement of the `merchants` array (each recipient needs `fundingAccountId`, `paymentMethod` = `ACH`, and `amount.value`) plus optional `metadata`. This is a PUT that returns 204 No Content - there is no response body to capture.
        operationId: updateInstructions
        parameters:
          - name: instructionId
            in: path
            value: $steps.getInstruction.outputs.instructionId
        requestBody:
          contentType: application/json
          payload:
            merchants:
              - merchantId: $inputs.merchantId
                recipients:
                  - fundingAccountId: $inputs.fundingAccountId
                    paymentMethod: ACH
                    amount:
                      value: $inputs.amountValue
                      currency: $inputs.currency
            metadata: $inputs.metadata
        successCriteria:
          - condition: $statusCode == 204
    outputs:
      instructionId: $steps.getInstruction.outputs.instructionId
      status: $steps.getInstruction.outputs.status