openapi: 3.0.0
info:
  title: API Webhook - Open Finance Brasil
  description: |
    API de Webhook é responsável por notificar eventos definidos em cada uma das APIs que possuem a funcionalidade no Open Finance Brasil.   

    Informações sobre endpoints suportados e funcionamento podem ser encontrados na página <a href="https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/105021661/Conven+o+de+Webhook">Convenção de Webhook</a>, disponível no portal do desenvolvedor do Open Finance Brasil.
    
  version: 1.3.0-rc.1
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0'
  contact:
    name: Governança do Open Finance Brasil – Especificações
    email: gt-interfaces@openbankingbr.org
    url: 'https://openbanking-brasil.github.io/areadesenvolvedor/'
servers:
  - url: 'https://api.banco.com.br/open-banking/webhook/v1'
    description: Servidor de Produção
  - url:  'https://apih.banco.com.br/open-banking/webhook/v1'
    description: Servidor de Homologação
tags:
  - name: Payments - Consents and Pix Payments
    description: Notificações de mudanças de estados de consentimentos e do pagamento.
  - name: No redirect - Enrollment Id Notification
    description: Notificações de mudanças de estados do vínculo de conta com a instituição.
  - name: Automatic Payments - Consents and Pix Payments
    description: Notificações de mudanças nas entidades de consentimentos de longa duração e do pagamento.
    
paths:
  '/payments/{versionApi}/consents/{consentId}':
    post:
      tags:
        - Payments - Consents and Pix Payments
      summary: Notificações de mudanças de estados de consentimentos da API de Iniciação de Pagamentos.
      operationId: consentNotification
      description: Notificações de mudanças de estados de consentimentos da API de Iniciação de Pagamentos.
      parameters:
        - $ref: '#/components/parameters/consentId'
        - $ref: '#/components/parameters/versionApi'
        - $ref: '#/components/parameters/xWebhookInteractionId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBodyWebhook'
        description: Payload enviado para notificar a alteração no estado do consentimento.
        required: true
      responses:
        '202':
          $ref: '#/components/responses/202Webhook'
  '/payments/{versionApi}/pix/payments/{paymentId}':
    post:
      tags:
        - Payments - Consents and Pix Payments
      summary: 'Notificações de mudanças de estados do pagamento: Arranjo Pix da API de Iniciação de Pagamentos.'
      operationId: pixPaymentNotification
      description: 'Notificações de mudanças de estados do pagamento: Arranjo Pix da API de Iniciação de Pagamentos.'
      parameters:
        - $ref: '#/components/parameters/paymentId'
        - $ref: '#/components/parameters/versionApi'
        - $ref: '#/components/parameters/xWebhookInteractionId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBodyWebhook'
        description: Payload enviado para notificar a alteração no estado do pagamento.
        required: true
      responses:
        '202':
          $ref: '#/components/responses/202Webhook'
  '/enrollments/{versionApi}/enrollments/{enrollmentId}':
    post:
      tags:
        - No redirect - Enrollment Id Notification
      summary: Mudanças de estado ou dados no vínculo de conta da API - Pagamentos sem Redirecionamento.
      operationId: enrollmentIdNotification
      description: Notificações de mudanças de estados ou limites no vínculo de conta da API - Pagamentos sem Redirecionamento.
      parameters:
        - $ref: '#/components/parameters/enrollmentId'
        - $ref: '#/components/parameters/versionApi'
        - $ref: '#/components/parameters/EnrollmentxWebhookInteractionId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBodyWebhookEnrollments'
        description: Payload enviado para notificar a alteração no estado do vínculo.
        required: true
      responses:
        '202':
          $ref: '#/components/responses/202Webhook'
  '/automatic-payments/{versionApi}/recurring-consents/{recurringConsentId}':
    post:
      tags:
       - Automatic Payments - Consents and Pix Payments
      summary: Notificações de mudanças da entidade de consentimentos da API de Pagamentos automáticos. 
      operationId: recurringConsentIdNotification
      description: Notificações de mudanças da entidade de consentimentos da API de Pagamentos automáticos. 
      parameters:
        - $ref: '#/components/parameters/recurringConsentId'
        - $ref: '#/components/parameters/versionApi'
        - $ref: '#/components/parameters/xWebhookInteractionId'
      requestBody: 
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBodyWebhook'
        description: Payload enviado para notificar a alteração na entidade do consentimento de longa duração.
        required: true
      responses:
        '202': 
          $ref: '#/components/responses/202WebhookPayments'
  '/automatic-payments/{versionApi}/pix/recurring-payments/{recurringPaymentId}':
    post:
      tags:
       - Automatic Payments - Consents and Pix Payments
      summary: Notificações de mudanças da entidade de pagamentos da API de Pagamentos automáticos. 
      operationId: recurringPaymentIdNotification
      description: Notificações de mudanças da entidade de pagamentos da API de Pagamentos automáticos. 
      parameters:
        - $ref: '#/components/parameters/recurringPaymentId'
        - $ref: '#/components/parameters/versionApi'
        - $ref: '#/components/parameters/xWebhookInteractionId'
      requestBody: 
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBodyWebhook'
        description: Payload enviado para notificar a alteração na entidade do pagamento automático.
        required: true
      responses:
        '202': 
          $ref: '#/components/responses/202WebhookPayments'
components:
  schemas:
    RequestBodyWebhookEnrollments:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          description: Informações referentes à chamada realizada.
          required:
            - timestamp
            - eventType
          properties:
            timestamp:
              $ref: '#/components/schemas/Timestamp'
            eventType:
              $ref: '#/components/schemas/EventType'
    RequestBodyWebhook:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          description: Informações referentes à chamada realizada.
          required:
            - timestamp
          properties:
            timestamp:
              $ref: '#/components/schemas/Timestamp'
    xWebhookInteractionId:
      type: string
      pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$'
      maxLength: 100
      description: Identificador único recebido da detentora de conta na notificação enviada pelo Webhook.
    xWebhookInteractionIdPayments:
      type: string
      pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$'
      maxLength: 100
      description: Identificador único para cada tentativa de notificação realizada. O identificador deverá seguir o padrão UID [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122).
    Timestamp:
      type: string
      format: date-time
      description: Data e hora em que ocorreu o evento responsável pelo disparo da notificação via webhook, conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).
      maxLength: 20
      pattern: '^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$'
      example: '2021-05-21T08:30:00Z'
    EventType:
      type: string
      enum:
        - STATE_CHANGED
        - DATA_CHANGED
      description:  |
        Tipo de evento que disparou a notificação via webhook.  
        - STATE_CHANGED: Indica que o estado do consentimento, do pagamento ou do vínculo de dispositivo foi alterado.  
        - DATA_CHANGED: Indica que dados do consentimento ou do vínculo de dispositivo foram alterados.
  parameters:
    consentId:
      name: consentId
      in: path
      description: |
        O consentId é o identificador único do consentimento e deverá ser um URN - Uniform Resource Name.  
        Um URN, conforme definido na [RFC8141](https://tools.ietf.org/html/rfc8141) é um Uniform Resource 
        Identifier - URI - que é atribuído sob o URI scheme "urn" e um namespace URN específico, com a intenção de que o URN 
        seja um identificador de recurso persistente e independente da localização.  
        Considerando a string urn:bancoex:C1DD33123 como exemplo para consentId temos:
        - o namespace(urn)
        - o identificador associado ao namespace da instituição transnmissora (bancoex) 
        - o identificador específico dentro do namespace (C1DD33123).  
        Informações mais detalhadas sobre a construção de namespaces devem ser consultadas na [RFC8141](https://tools.ietf.org/html/rfc8141).
      required: true
      schema:
        type: string
        pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9\-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$'
        maxLength: 256
    versionApi:
      name: versionApi
      in: path
      description: Identifica a versão da API que deverá ser utilizada para recebimento da notificação via webhook
      required: true
      schema:
        type: string
        pattern: '^v([1-9][0-9]?|10)$'
        maxLength: 256
    paymentId:
      name: paymentId
      in: path
      description: Identificador da operação de pagamento.
      required: true
      schema:
        type: string
        pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$'
        maxLength: 100
    enrollmentId:
      name: enrollmentId
      in: path
      description: Identificador único do vínculo de conta criado para a iniciação de pagamento solicitada. Deverá ser um URN - Uniform Resource Name. Um URN, conforme definido na [RFC8141](https://datatracker.ietf.org/doc/html/rfc8141) é um Uniform Resource Identifier - URI - que é atribuído sob o URI scheme "urn" e um namespace URN específico, com a intenção de que o URN seja um identificador de recurso persistente e independente da localização.
      required: true
      schema:
        type: string
        pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$'
        maxLength: 100
    recurringConsentId:
      name: recurringConsentId
      in: path
      description: | 
        O recurringConsentId é o identificador único do consentimento e deverá ser um URN - Uniform Resource Name.
        Um URN, conforme definido na [RFC8141](https://datatracker.ietf.org/doc/html/rfc8141) é um Uniform Resource Identifier - URI - que é atribuído sob o URI scheme "urn" e um namespace URN específico, com a intenção de que o URN seja um identificador de recurso persistente e independente da localização.
        Considerando a string urn:bancoex:C1DD33123 como exemplo para recurringConsentId temos:

        - o namespace(urn). 
        - o identificador associado ao namespace da instituição transnmissora (bancoex). 
        - o identificador específico dentro do namespace (C1DD33123). Informações mais detalhadas sobre a construção de namespaces devem ser consultadas na [RFC8141](https://datatracker.ietf.org/doc/html/rfc8141).
      required: true
      schema:
        type: string
        pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9\-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$'
        maxLength: 256
    recurringPaymentId:
      name: recurringPaymentId
      in: path
      description: Identificador da operação de pagamento.
      required: true
      schema:
        type: string
        pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$'
        maxLength: 100
    xWebhookInteractionId:
      name: x-webhook-interaction-id
      in: header
      description: Identificador único para cada tentativa de notificação realizada. O identificador deverá seguir o padrão UID [RFC4122](https://tools.ietf.org/html/rfc4122).
      required: true
      schema:
        type: string
        pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$'
        minLength: 1
        maxLength: 100
    EnrollmentxWebhookInteractionId:
      name: x-webhook-interaction-id
      in: header
      description: Identificador único para cada tentativa de notificação realizada. Caso haja retentativas de notificação para o mesmo evento, este identificador não poderá ser reaproveitado da notificação anterior. O identificador deverá seguir o padrão UUID [RFC4122](https://tools.ietf.org/html/rfc4122).
      required: true
      schema:
        type: string
        pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$'
        minLength: 1
        maxLength: 100
  responses:
    202Webhook:
      description: Requisição aceita para processamento posterior.
      headers:
        x-webhook-interaction-id:      
          description: Identificador único recebido da detentora de conta na notificação enviada pelo Webhook.
          schema:
            $ref: '#/components/schemas/xWebhookInteractionId'
    202WebhookPayments:
      description: Requisição aceita para processamento posterior.
      headers:
        x-webhook-interaction-id:      
          description: Identificador único para cada tentativa de notificação realizada. O identificador deverá seguir o padrão UID [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122).
          schema:
            $ref: '#/components/schemas/xWebhookInteractionIdPayments'