List, retrieve, then refresh a secure token from a single-use token.

arazzo: 1.0.0
info:
  title: Refresh a saved payment method (secure token)
  summary: Find a stored secure token, then refresh its details from a Hosted
    Fields single-use token.
  description: |
    Refreshes the stored details of a reusable secure token from a Hosted Fields single-use token that already represents the new details (the account-updater flow). Use this when you hold a single-use token rather than raw details.
    Agent gotchas:
      - `accountUpdate` (POST .../update-account) body is
        `{ type: singleUseToken, token: <128-char token> }`. Requires a unique
        `Idempotency-Key` header. Returns 200 (not 201).
      - The path parameter is the `secureTokenId` (format `MREF_...`).

    To patch the saved details directly (you hold the raw details), use update-a-saved-payment-method. To remove the token, use delete-a-saved-payment-method.
  version: 1.0.0
sourceDescriptions:
  - name: payroc-api
    url: /openapi.yaml
    type: openapi
workflows:
  - workflowId: refresh-a-saved-payment-method
    x-actors:
      - id: merchant
        name: Merchant / integrator
        type: client
        description: Calls the Payroc API to find the secure token and refresh its
          stored details.
      - id: payroc-gateway
        name: Payroc gateway
        type: api
        description: The Payroc API surface these steps call.
    summary: List, retrieve, then refresh a secure token from a single-use token.
    description: |
      Optionally list secure tokens (listSecureTokens) and retrieve one (getSecureToken) to confirm its state, then refresh the stored details from a Hosted Fields single-use token (accountUpdate). The list/retrieve steps are optional when you already hold the secureTokenId.
    inputs:
      type: object
      required:
        - processingTerminalId
        - secureTokenId
        - idempotencyKey
        - singleUseToken
      properties:
        processingTerminalId:
          type: string
          description: Unique identifier for the terminal that owns the secure token.
          example: "1234001"
        secureTokenId:
          type: string
          description: Durable identifier for the saved payment method. If you do not have
            it, the discovery step can locate it.
          example: MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa
        customerName:
          type: string
          description: Customer name filter for the discovery step (URL-encoded).
          example: Sarah%20Hazel%20Hopper
        limit:
          type: integer
          description: Maximum number of secure tokens to return per page.
          example: 10
        idempotencyKey:
          type: string
          description: Unique UUID v4 sent as the `Idempotency-Key` header on the
            account-update step.
          example: f32c9ad6-c97f-4998-9356-f3b6718b1b68
        singleUseToken:
          type: string
          description: 128-character single-use token from Hosted Fields that represents
            the refreshed payment details.
          example: abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
    steps:
      - stepId: listSecureTokens
        x-actor: merchant
        x-actor-to: payroc-gateway
        x-label: token search
        description: |
          OPTIONAL — lists secure tokens on the terminal, filtered by customer name, and extracts the first result's `secureTokenId`. Skip if you already hold the `secureTokenId`.
        operationId: listSecureTokens
        parameters:
          - name: processingTerminalId
            in: path
            value: $inputs.processingTerminalId
          - name: customerName
            in: query
            value: $inputs.customerName
          - name: limit
            in: query
            value: $inputs.limit
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          firstSecureTokenId: $response.body#/data/0/secureTokenId
          hasMore: $response.body#/hasMore
      - stepId: getSecureToken
        x-actor: merchant
        x-actor-to: payroc-gateway
        x-label: token lookup
        description: |
          OPTIONAL — retrieve the secure token to confirm its current state before refreshing. Surfaces the token `status` and the replayable `token` value.
        operationId: getSecureToken
        parameters:
          - name: processingTerminalId
            in: path
            value: $inputs.processingTerminalId
          - name: secureTokenId
            in: path
            value: $inputs.secureTokenId
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          secureTokenId: $response.body#/secureTokenId
          status: $response.body#/status
          token: $response.body#/token
      - stepId: accountUpdate
        x-actor: merchant
        x-actor-to: payroc-gateway
        x-label: account update request
        description: |
          Refresh the stored payment details from a Hosted Fields single-use token. The body is `{ type: singleUseToken, token: <128-char token> }`. Requires a unique `Idempotency-Key` header. Returns 200 (not 201).
        operationId: accountUpdate
        parameters:
          - name: Idempotency-Key
            in: header
            value: $inputs.idempotencyKey
          - name: processingTerminalId
            in: path
            value: $inputs.processingTerminalId
          - name: secureTokenId
            in: path
            value: $inputs.secureTokenId
        requestBody:
          contentType: application/json
          payload:
            type: singleUseToken
            token: $inputs.singleUseToken
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          secureTokenId: $response.body#/secureTokenId
    outputs:
      secureTokenId: $steps.accountUpdate.outputs.secureTokenId