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.0.0-beta.3'
  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: Consent Notification
    description: Notificações de mudanças de estados de consentimentos da API de Iniciação de Pagamentos.
  - name: Pix Payment Notification
    description: 'Notificações de mudanças de estados do pagamento: Arranjo Pix da API de Iniciação de Pagamentos.'
    
paths:
  '/payments/{versionApi}/consents/{consentId}':
    post:
      tags:
        - Consent Notification
      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:
        - Pix Payment Notification
      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'
components:
  schemas:
    RequestBodyWebhook:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          description: Informações referentes à chamada realizada.
          required:
            - timestamp
          properties:
            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'
    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.
  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: '^urn:[a-zA-Z0-9][a-zA-Z0-9\-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$'
        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
    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
  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'