BMO Payment Status Update API

openapi: 3.2.0
info:
  title: Push Notifications Payment Status Update API
  description: "This document summarize the Payment Service - Push Notification API interface specification. The intent of this API is to receive the payment status updates.  The payment status will be sent in JSON format adhering to the ISO pain002 format. Customers must subscribe to the Push Notification as part of the Payment API onboarding process. Customer can subscribe to the pre-defined list of payment status for which the notifications need to be enabled during onboarding process. During payment processing, the payment status changes will be updated by calling this API and the notification wil be send only for the subscribed payment status changes. <br>\nSystem will retry the payment delivery based on the http response code of this API. System will do retry delivering the payments for 24 hours with one hour interval. Refer the \"Response\" section of this swagger for more details. \n## Non-Functional Requirements:\n     Performance:\n      - 95% of request should respond with in 3 seconds\n      - Maximum acceptable Latency: 5 seconds\n     Throughput: \n      - 50 requests/second\n     Availability\n      - 99.95 % uptime SLA\n     Security:\n      - All endpoints must support https and TLS 1.2+\n      - In addition to TLS , payload encryption as per defined in the x-crypto-key header element\n      - Authorization is enabled by OAuth 2.0        "
  contact:
    email: paymentAPIPNSupport@bmo.com
  version: 1.0.0
  x-ibm-name: payment-service-push-notification-api
  x-api-id: BMO-ENT-f03de36a-fb59-4757-af38-b4afb449a904
  x-bmoservicedomain-name: Payment Initiation
  x-bmo-api-type: general-api
  x-bmo-api-provider-id: 87679
  x-audience: company-internal
  x-template-version: 1.0.0
  x-api-specification-compliant: true
  x-ibm-summary: ''
servers:
- url: https://sandbox-open-api.bmo.com/open-banking/commercial-sb
security:
- api-key: []
tags:
- name: PaymentStatusUpdate
paths:
  /paymentStatusUpdate/v1:
    post:
      x-dataclassification-code: Confidential
      summary: 'Payment Status Update '
      parameters:
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-client-id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-request-timestamp'
      - $ref: '#/components/parameters/x-crypto-key'
      - $ref: '#/components/parameters/x-payment-type'
      - $ref: '#/components/parameters/x-retry-flag'
      requestBody:
        description: Request body contains encrypted payload.Payload will be encrypted as Base64(AES-256-GCM-Encrypted-Message)|Base64(AuthTag)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentStatusUpdateRequest'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
        '504':
          $ref: '#/components/responses/504'
        default:
          $ref: '#/components/responses/default'
      tags:
      - PaymentStatusUpdate
components:
  responses:
    '200':
      description: Success responses
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Success'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002
    '503':
      description: Service Unavailable. Service is not available due to maintenance. System will do default (3-times) retry first followed by 24 hrs retry with one hour interval.
    '400':
      description: Bad Request.Unable to process the payment status update message. The payload is malformed,corrupted or failed to decrypt the message. No Automatic retry for this error code. Support team will investigate the issue and resend the notification.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002
    '429':
      description: Too many requests. System will retry for this request. The request will be retried 3 times on failure and then subsequent retry will happen for 24 hours at one hour interval.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002
    default:
      description: If the http error code is not part of the listed http error codes of the swagger, it will be considered as default error handling. If the http error code falls under 4XX series, system will not do the retry and for other error codes , system will do a default (3 times) retry and also 24 hrs scheduled retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002
    '504':
      description: System processing timeout. System will do default (3-times) retry first followed by 24 hrs retry with one hour interval.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002
    '500':
      description: Internal Server Error or Unexpected Error. System will do default (3-times) retry first followed by 24 hrs retry with one hour interval.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002
    '401':
      description: Unauthorized.Request is not having valid authorization credentials. For example, OAuth token may be expired. System will retry this request with a default 3 time retry. If the default re-try limit exceeds, then support team will be updated for further investigation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002
    '422':
      description: Unprocessable Entity.Request syntax is valid for not able process the request ,i.e invalid transaction id. No automatic retry for this error code. Support team will investigate and resend this request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002
    '403':
      description: Forbidden. Not authorized to call this API. No Retry for this request. Support team will investigate this issue and may resend the notification.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        x-correlation-id:
          schema:
            type: string
          description: Correlates HTTP requests between a client and server. Populate the request id as part of this field.
        x-response-id:
          schema:
            type: string
          description: Unique id to identify the response.
        x-response-timestamp:
          schema:
            type: string
          description: Response Timestamp in UTC format. For example 2025-01-22T12:00:00.002
  parameters:
    x-request-timestamp:
      in: header
      name: x-request-timestamp
      description: Request Timestamp in UTC format. For example 2025-01-22T12:00:00.002
      schema:
        type: string
      required: true
    authorization:
      in: header
      name: authorization
      description: Authorization Token
      schema:
        type: string
      required: true
    x-api-key:
      in: header
      name: x-api-key
      description: Unique identifier to identify API and to manage the API usage.
      schema:
        type: string
      required: true
    x-request-id:
      in: header
      name: x-request-id
      description: Unique id used to identify the request.
      schema:
        type: string
      required: true
    x-crypto-key:
      in: header
      name: x-crypto-key
      description: x-crypto-key will be send in the format Base64(keyid).Base64 +(encrypted CEK).base64(hashed CEK).base64(IV).GCM<br> It has 5 parts.<br> <b>Base64(keyid)</b> - First part of the header is the base64 encoded keyid of | the  public key <br> <b>Base64(encrypted CEK)</b>-Second part of the header is the base64 encoded encrypted CEK|Encrypt CEK using the public key, ensure padding is set to  RSA_PKCS1_OAEP_PADDING and base64 encoded. <br> <b>Base64(hashed CEK)</b> -Hash CEK using SHA-256 algorithm.Apply base64 encoding on the hashed CEK to generate the third parts. <br> <b>Base64(IV)</b>-Apply base64 encoding on the IV to generate the fourth part (AES-256-GCM)<br> <b>GCM-256</b>-AES-256-GCM algorithm used in encryption of the payload.
      schema:
        type: string
      required: true
    x-payment-type:
      in: header
      name: x-payment-type
      description: Used to identify the payment type.
      schema:
        type: string
      required: false
    x-retry-flag:
      in: header
      name: x-retry-flag
      description: Payment Status update is send during retry. Contains 'Y' if the status update is send during retry.
      schema:
        type: string
      required: false
    x-client-id:
      in: header
      name: x-client-id
      description: Used to identify the entity making the API call.
      schema:
        type: string
      required: true
  schemas:
    Problem:
      type: object
      properties:
        status:
          type: integer
          format: int32
          description: "The HTTP status code generated by the origin server for this occurrence\nof the problem.                 \n"
        title:
          type: string
          description: 'A short, summary of the problem type. Written in english and readable

            for engineers (usually not suited for non technical stakeholders and

            not localized); example: Service Unavailable

            '
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem. example: Connection to database timed out

            '
    PaymentStatusUpdateRequest:
      properties:
        SECURE:
          $ref: '#/components/schemas/SECURE'
    Success:
      type: object
      properties:
        status:
          type: integer
          format: int32
          description: "Populated with value 200 for successful processing of the message                \n"
        title:
          type: string
          description: 'Contains value ''success''.

            '
        detail:
          type: string
          description: 'Additional information related to status message processing.

            '
    SECURE:
      type: object
      required:
      - encrypted
      - data
      properties:
        encrypted:
          type: boolean
          default: true
          description: Send true when dealing with data encryption else false
        data:
          type: string
          default: Payment Status information as encrypted PAIN002 message
          description: 'base64url<cipher-text>. #/definitions/SecuredDataObject should be sent as encrypted string in this field'
  securitySchemes:
    api-key:
      type: apiKey
      x-key-type: client_id
      name: x-api-key
      in: header
externalDocs:
  description: Documentation about the Payment API Push Notification.
  url: /payment-systems/<payment-type>
x-ibm-configuration:
  type: rest
  phase: realized
  enforced: true
  testable: true
  categories:
  - bian--bd--operationalservices
  cors:
    enabled: true
x-ibm-endpoints:
- url: https://sandbox-open-api.bmo.com/open-banking/commercial-sb
  type:
  - production
  - development