openapi: 3.0.0
info:
  version: 1.0.0
  title: ISO Wire Payments API
  description: >
    The ISO Wire Payments API allows the consumer to initiate an Electronic Wire Customer Credit Transfer using The FedWire Funds Service ISO 20022 standard underneath and check the status of them using a payment identification.

servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/apipeople/iso-wire-payments-api/1.0.0
  - description: Workato API People
    url: https://apim.workato.com/apipeople/wires/iso/api/v1
  - description: Workato API People
    url: https://apim.workato.com/api-peoplepb-dev/wires/iso/api/v1
security:
  - oAuth2_ClientCredentials: []
  
tags:
  - name: APIs
    description: A set of APIs to initiate and inquiry on a Wire Credit Transfer.
  - name: Webhooks
    description: Webhook Service enables your backend applications to receive near real-time notifications when events occur in our systems. This allows you to take automated actions and eliminates unnecessary API polling calls.
  
paths:
  /payments/credits:
    post:
      operationId: createPayment
      description: This API initiates a single Wire Customer Credit Transfer for a given Account that is associated to a Wire Company.
      summary: 'Create an ISO Wire Customer Credit Transfer'
      parameters:
        - $ref: '#/components/parameters/xCorrelationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/paymentDetails'
      responses:
        '201':
          description: Wire Operation Created Successfully Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wireResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '409':
          $ref: '#/components/responses/409'  
        '500':
          $ref: '#/components/responses/500'
      security:
        - oAuth2_ClientCredentials: []
      tags:
        - APIs

  /payments/{paymentId}:
    get:
      operationId: getPaymentInfo
      description: This API retrieves the all the information (including status) of a submitted ISO Wire Transfer using its `paymentId`.
      summary: 'Retrieve an ISO Wire Customer Credit Transfer information'
      parameters:
        - name: paymentId
          in: path
          required: true
          description: Payment key generated when creating the Wire
          example: 1998237737364728
          schema:
            type: string
        - $ref: '#/components/parameters/xCorrelationId'
      responses:
        '200':
          description: Successful Wire Retrieval Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentInquiryDetails'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
      security:
        - oAuth2_ClientCredentials: []
      tags:
        - APIs
#
# Webhooks
#
  /your-webhook-url:
    post:
      operationId: WebhookEvent
      description: This is a representation of the HTTP webhook call that the consumer will receive for each Wire payment related event that occur. Please be aware (/your-webhook-url) will be the full FDNS consumer custom http endpoint that should be provided during API consumer onboarding.
      summary: Receive ISO Wire Event Webhooks 
      parameters: 
        - $ref: '#/components/parameters/xTimestamp'
        - $ref: '#/components/parameters/xSignature'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhookEvent'
      responses:
        '200':
          description: Notification is delivered. No additional retries are executed. 
      tags:
        - Webhooks
#
  /payments/webhookEvents:
    get:
      summary: 'Retrieve All ISO Wire Events for a Given Period'
      description: This API allows the API consumer to retrieve past webhooks events on demand given a date period.
      operationId: GetWebhookEvents
      parameters:
        - name: startDate
          in: query
          required: true
          description: Start date to retrieve events
          example: '2025-04-03'
          schema:
            format: date
            pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
            type: string
        - name: endDate
          in: query
          required: true
          description: End date to retrieve events.
          example: '2025-04-03'
          schema:
            format: date
            pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
            type: string
        - name: x-correlation-id
          in: header
          required: true
          description: Required unique GUID to allow idempotency validation.
          schema:
            type: string
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/limit"    
      responses:
        '200':
          description: Successful Webhook Events Retrieval.
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      allOf:
                        - type: object
                          properties:
                            eventStatus:
                              type: string
                              description: "The Wire Event Status"
                              example: "DELIVERED"
                        - $ref: "#/components/schemas/webhookEvent"
                  pagination:
                    $ref: '#/components/schemas/paginationResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
      security:
        - oAuth2_ClientCredentials: []
      tags:
        - Webhooks
############################################
# API Standard Error Responses Data Models #
############################################

components:
  securitySchemes:
    oAuth2_ClientCredentials:
      type: oauth2
      description: OAuth 2 [Client Credentials Flow](https://docs.workato.com/api-mgmt/oauth2.html#how-to-setup-oauth-2-0)
      flows: 
        clientCredentials: 
          tokenUrl: https://apim.workato.com//oauth2/token
          scopes: {} # Scopes not used in v1
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  errorDetails: 
                    allOf:
                      - $ref: '#/components/schemas/ErrorDetails'
                      - type: object
                        properties:                    
                          code:  
                            example: 400
                          reason:  
                            example: BAD_REQUEST
                          details:  
                            example: Please verify input parameters.
    '401':
      description: |
        Unauthorized.

          :::info 401 errors
          There are two different error schemas for 401 errors, one when the API credentials sent are wrong or invalid and another one when the API credentials are valid but the operation is prohibited for the consumer.
          :::
          
      content:
        application/json:
          schema:
            oneOf:
              - allOf:
                - $ref: '#/components/schemas/Error'
                - type: object
                  properties:
                    errorDetails: 
                      allOf:
                        - $ref: '#/components/schemas/ErrorDetails'
                        - type: object
                          properties:                    
                            code:  
                              example: 401
                            reason:  
                              example: UNAUTHORIZED
                            details:  
                              example: Permission denied.
              - type: object
                properties:
                  error: 
                    type: string
                    example: Access to this API has been disallowed
    '409':
      description: | 
            Conflict.
              The API was unable to process the request due to business validation rules.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  errorDetails: 
                    allOf:
                      - $ref: '#/components/schemas/ErrorDetails'
                      - type: object
                        properties:                    
                          code:  
                            example: 409
                          reason:  
                            example: "CONFLICT"
                          details:  
                            example: "Wire 60 days Limit Reached"
                            enum:
                              - "Wire Daily Limit Reached"
                              - "Wire 60 days Limit Reached"
                              - "Credit Operation Not Allowed"
                              - "Insufficient Funds to perform credit"                    
    '500':
      description: API Internal Error.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  errorDetails: 
                    allOf:
                      - $ref: '#/components/schemas/ErrorDetails'
                      - type: object
                        properties:                    
                          code:  
                            example: 500
                          reason:  
                            example: "INTERNAL_SERVER_ERROR"
                          details:  
                            example: "Recipe function call failed (id: 61178786, job_id: j-AT6HQhcH-YGmr8a): Bank Routing Number is not valid at line: 19092"
  
  parameters:
    xCorrelationId:
      name: x-correlation-id
      in: header
      required: true
      description: A UUID value compliant with RFC 4122 used to identify an API Request. The value is echoed back in the response header. See [Authentication](/api/authentication/#correlation-id) for more details.
      schema:
        type: string
        minLength: 36
        maxLength: 36
    xTimestamp:
      name: x-timestamp
      in: header
      required: true
      description: |
        The timestamp used to support the message signature. Should contain only numbers.
        
          :::warning  Rejected Timestamps
          Requests with timestamp > 5min will be rejected
          :::
        
      schema:
        type: string
        example: "1746197323"
    xSignature:
      name: x-signature
      in: header
      required: true
      description: |
        Payload signature used by the API Client to validate message authenticity. Signature is calculated via **HMAC SHA256** algorithm and is composed by: 
        
            -`HTTP_VERB + HTTP_URL + PAYLOAD + TIMESTAMP`.
            
        The key will be provided to API Consumer
      schema:
        type: string
        minLength: 64
        maxLength: 64
  #############################
  # API Pagination Parameters #
  #############################
    limit:
      name: limit
      in: query
      required: false            
      description: The maximum number of records to return in each response.  
      example: 10
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 100
    offset:
      name: offset
      in: query
      required: false            
      description: Allows the call to understand where the previous call left off when returning multiple records and allowing a subsequent call to retrieve more records.
      example: ZkiT8ovgDb5NbZ7XvkwTYwwm1vgUDn1vEswIQT4ThOBY4qv5Xnp1oKS1e05Gas4AAfP8bH_w-Tl8VMAggvqkLlTjnnJ3PRl-79BDsg 
      schema:
        type: string
        example: ZkiT8ovgDb5NbZ7XvkwTYwwm1vgUDn1vEswIQT4ThOBY4qv5Xnp1oKS1e05Gas4AAfP8bH_w-Tl8VMAggvqkLlTjnnJ3PRl-79BDsg          
        
########################
## Schemas of Objects
########################
  schemas:
    webhookEvent:
      type: object
      properties:
        notificationId:
          type: string
          minLength: 36
          maxLength: 36
          description: UUID of the generated event.
          example: "8cefee42-cb39-4479-b7fd-b8a358aeb002"
        eventType:
          type: string
          description: "The ISO Wire Event Type"
          example: "wire.status"
        eventDateTime:
          type: string
          format: date-time
          description: The date the event occurred.
          example: "2017-07-21T17:32:28Z"
        data:
          type: object
          properties:
            wireEventInfo:
              $ref: '#/components/schemas/paymentInquiryDetails'
          
  #
  # Inquiry Response Details
  #
    paymentInquiryDetails: 
      type: object
      properties:
        paymentId:
          type: string
          example: 1998237737364728
          description: Payment key generated when creating the Wire.
        status:
          description: Wire transfer status.
          type: string
          example: "Processed"        
          enum:
            - "Review"
            - "Send Ready"
            - "Reject"
            - "Error"
            - "Exception"
            - "Complete"
        exceptionInfo:
          type: array
          items:
            type: object
            properties:
              exceptionCode:
                description: The Wire exception code.
                type: string 
                example: "Suspect"
              exceptionDescription:
                description: The Wire exception description.
                type: string
                example: "OFAC Match Suspect"

        IMAD:
          type: string
          example: 20250416456FMPBO000137
          description:  Input Message Accountability Data.
        OMAD:
          type: string
          example: 20250416456FMPBO000135
          description: Output Message Accountability Data.
        
        originalWire:
          $ref: '#/components/schemas/paymentDetails'  


        
  #
  # Wire Payment Details
  #
    paymentDetails:
      description: Wire Transfer Payment Detail.
      type: object
      required:      
        - wireInfo
        - originatorInfo
        - beneficiaryInfo
      properties:
        wireInfo:
          properties:
            paymentAmount:
              maxLength: 12
              minLength: 1
              type: string
              pattern: ^[\d]*\.[\d]{2}$
              example: "1.00"
              description: |
                Transaction amount in `N.NN` format. For amounts less than 1 Dollar, the 0 is required (0.50).
            referenceId:
              maxLength: 35
              minLength: 35
              type: string
              example: "124323453243545"
              description: >-
                Identification provided to a transaction. Please send `Not Provided` if you dont have one.
            endToEndId: 
              maxLength: 36
              minLength: 36
              type: string
              example: "eeaa89d8-a0c8-4e9b-8b9c-ca8103b345cb"
              description: >-
                Unique identification to unambiguously identify the transaction that is passed on, unchanged, throughout the entire interbank chain.            
          required:
            - paymentAmount
            - referenceId
             
        originatorInfo:
          properties:
            accountNumber:
              example: 2030567898
              maxLength: 16
              minLength: 1
              type: string
              description: The API People Account number associated with the Wire Company.
            accountType:
              description: The API People Account type associated with the Wire Company. [D - Deposit or S - Savings]
              type: string
              example: D
              enum:
                - D
                - S
            name:
              example: John Doe
              maxLength: 35
              minLength: 1
              type: string
              description: Name of of the account holder.
            wireCompanyId:
              example: 1234
              maxLength: 12
              minLength: 1
              type: string
              description: The Wire Company Id tied to the financial account where the funds will be sent from. 
            wireCompanyName:
              example: ABC Comp
              maxLength: 40
              minLength: 1
              type: string
              description: The Wire Company Name tied to the financial account where the funds will be sent from.
          required:
            - accountNumber
            - accountType
            - name

        beneficiaryInfo:
          properties:
            accountNumber:
              example: 2030567898
              maxLength: 34
              minLength: 1
              type: string
              description: The receiving party account number.
            accountType:
              description: |
                The single letter identifier for the financial account type.
                   - `D` = Deposit
                   - `S` = Savings
                  If not informed, the default value is `D`
              type: string
              example: D
              enum:
                - D
                - S
            name:
              example: Bob Smith
              maxLength: 35
              minLength: 1
              type: string
              description: Name of beneficiary account holder.
            address:
              $ref: '#/components/schemas/addressDefault'
            institutionInfo:
              properties:
                name:
                  example: The Big Bank
                  maxLength: 35
                  minLength: 1
                  type: string
                  description: Name of beneficiary Bank.
                routingNumber:
                  example: 039506009
                  maxLength: 9
                  minLength: 1
                  type: string
                  description: Beneficiary bank ABA number.                  
                address:
                  $ref: '#/components/schemas/addressDefault'              
              required:
                - name
                - routingNumber
                - address

          required:
            - accountNumber
            - accountType
            - name
            - address
            - institutionInfo

        remittanceInformation:
          type: string
          maxLength: 140
          description: Remittance information (140 chars limit).
          example: "Sender to Receiver Comments"  

    addressDefault:
      description: Address.
      type: object
      properties:
        addressLine:
          description: Street address line.
          type: string
          minLength: 1
          maxLength: 70
        city:
          description: City or locality.
          type: string
          minLength: 1
          maxLength: 21
        state:
          description: State
          type: string
          minLength: 1
          maxLength: 2
        postalCode:
          description: Postal code. 
          type: string
          minLength: 1
          maxLength: 10
      required:
        - addressLine
        - city
        - state
        - postalCode
 
    wireResponse:
      type: object
      properties:
        paymentId:
          type: string
          example: JXUUG0CTIN
          description: Resulting Wire Operation ID that can be used to inquiry status.
  ##############################################
  # API Standard Pagination Response DataModel #
  ##############################################
    paginationResponse:
      type: object
      properties:
        moreResults:
          description: Indicates if there is more content that could be returned from a subsequent call.
          type: boolean
        offset:
          description: Allows the next call to understand where it left off when returning multiple records and allowing a subsequent call to retrieve more records.
          type: string
          example: ZkiT8ovgDb5NbZ7XvkwTYwwm1vgUDn1vEswIQT4ThOBY4qv5Xnp1oKS1e05Gas4AAfP8bH_w-Tl8VMAggvqkLlTjnnJ3PRl-79BDsg          
  ################################
  # API Standard Error DataModel #
  ################################
    Error:
      required:
      - apiName
      - version
      - correlationId
      - timestamp
      - errorDetails
      properties:
        apiName:
          type: string
          example: ISO Wire Payments API
        version:
          type: string
          example: v1
        correlationId:
          type: string
          example: 679751e0-36ba-49a1-b992-599c75beec66
        timestamp:
          type: string
          example: "2025-06-05T10:12:43.642286-07:00"
        errorDetails:
          type: object
          properties:
            code:
              type: string
              description: HTTP standard error code.
            reason:
              type: string
              description: Integration error identification code.
            details:
              type: string
              description: Error description.
    ErrorDetails:
      type: object
      properties:
        code:
          type: string
          description: HTTP standard error code.
        reason:
          type: string
          description: Integration error identification code.
        details:
          type: string
          description: Error description.