openapi: 3.2.0
info:
  title: Modulr Notification API
  description: Modulr API
  license:
    name: © Modulr Finance
    url: https://www.modulrfinance.com
  version: '1.0'
servers:
- url: https://api-sandbox.modulrfinance.com/api-sandbox-token
security:
- modulo_security: []
tags:
- name: Notification
  description: Operations on Notifications
paths:
  /partners/{partnerId}/notifications/{notificationId}:
    get:
      tags:
      - Notification
      summary: Retrieve a specific notification by unique reference for a specific partner
      description: This allows you to see the settings for a particular notification that has been set up, for example if you want to check if it is active or the emails the notification is being sent to. It would be best practice to call this before updating a notification.
      operationId: getPartnerNotification
      parameters:
      - name: partnerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: notificationId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification.NotificationResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.MessageResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification.NotificationResponse'
      security:
      - HMAC: []
      - TOKEN: []
    put:
      tags:
      - Notification
      summary: Update a specific notification by unique reference for a specific partner
      description: If you need to change anything about a particular notification, for example add an email address or make it inactive, then this is the endpoint to use. You need to put all of the information into this request for the notification even if it isn't changing, so either you will need to record this somewhere when you create the notification, or call the 'GET' request first.
      operationId: editPartnerNotification
      parameters:
      - name: partnerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: notificationId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/notification.UpdateNotificationRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification.NotificationResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.MessageResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification.NotificationResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /customers/{customerId}/notifications/{notificationId}:
    get:
      tags:
      - Notification
      summary: Retrieve a specific notification by unique reference for a specific customer
      description: This allows you to see the settings for a particular notification that has been set up, for example if you want to check if it is active or the emails the notification is being sent to. It would be best practice to call this before updating a notification.
      operationId: getCustomerNotification
      parameters:
      - name: customerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: notificationId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification.NotificationResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.MessageResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification.NotificationResponse'
      security:
      - HMAC: []
      - TOKEN: []
    put:
      tags:
      - Notification
      summary: Update a specific notification by unique reference for a specific customer
      description: If you need to change anything about a particular notification, for example add an email address or make it inactive, then this is the endpoint to use. You need to put all of the information into this request for the notification even if it isn't changing, so either you will need to record this somewhere when you create the notification, or call the 'GET' request first.
      operationId: editCustomerNotification
      parameters:
      - name: customerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: notificationId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/notification.UpdateNotificationRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification.NotificationResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.MessageResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification.NotificationResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /partners/{partnerId}/notifications:
    get:
      tags:
      - Notification
      summary: Get all Notifications linked directly to a Partner
      description: Retrieve details of all notifications set up for a partner using the partner's ID as a reference
      operationId: getAllPartnerNotifications
      parameters:
      - name: partnerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.NotificationResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.MessageResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.NotificationResponse'
      security:
      - HMAC: []
      - TOKEN: []
    post:
      tags:
      - Notification
      summary: Set up a Notification for a Partner
      description: Sets up a new notification for a partner using the partner's ID as a reference. Returns a notification ID that should be saved if the notification needs to be amended in the future
      operationId: addPartnerNotification
      parameters:
      - name: partnerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/notification.NotificationRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification.NotificationResponse'
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /customers/{customerId}/notifications:
    get:
      tags:
      - Notification
      summary: Get all Notifications for a Customer
      description: Retrieve details of all notifications set up for a customer using the customer's ID as a reference
      operationId: getAllCustomerNotifications
      parameters:
      - name: customerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.NotificationResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.MessageResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.NotificationResponse'
      security:
      - HMAC: []
      - TOKEN: []
    post:
      tags:
      - Notification
      summary: Set up a Notification for a Customer
      description: Sets up a new notification for a customer using the customer's ID as a reference. Returns a notification ID that should be saved if the notification needs to be amended in the future
      operationId: addCustomerNotification
      parameters:
      - name: customerId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/notification.NotificationRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification.NotificationResponse'
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /webhooks/{webhookId}/failures:
    get:
      tags:
      - Notification
      summary: Check if a particular webhook has failed
      description: Only supports webhook notifications and as such uses the webhook endpoint. Request a specific notification ID and specify you want to see failures. (Max 50)
      operationId: getFailedWebHooks
      parameters:
      - name: webhookId
        in: path
        description: 'Id of Webhook '
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: from
        in: query
        description: Failed since Date. Needs to be urlEncoded value
        required: true
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.WebHookFailureResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/notification.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
components:
  schemas:
    notification.MessageResponse:
      type: object
      properties:
        field:
          type: string
        code:
          type: string
          enum:
          - GENERAL
          - BUSINESSRULE
          - MFASTATUS
          - MFAERROR
          - MFATIMEOUT
          - MFADEVICEMM
          - MFAMESSAGEINVALID
          - NOTFOUND
          - DUPLICATE
          - INVALID
          - CONNECTION
          - RETRY
          - RATELIMIT
          - PERMISSION
          - NOTACCEPTABLE
          - MFAVERIFICATION
          - TOKENEXPIRED
        errorCode:
          type: string
        message:
          type: string
        sourceService:
          type: string
    notification.NotificationRequest:
      type: object
      properties:
        type:
          type: string
          description: Type of the notification.
          enum:
          - PAYIN
          - PAYOUT
          - BALANCE_LOW
          - BALANCE_HIGH
          - BALANCE
          - DDMANDATE
          - CUSTVSTAT
          - ACCOUNT_STATEMENT
          - PENDING_PAYMENTS
          - DD_INCOMING_DEBIT
          - DD_FAILED_CLAIM
          - DD_FUNDS_RETURNED
          - CARD_AUTH
          - CARD_AUTH_OFFLINE
          - CARD_CREATION
          - UPCOMING_CREDIT
          - UPCOMING_COLLECTION_CREDIT
          - UPCOMING_COLLECTION_DEBIT
          - CARD_STATUS_UPDATE
          - CARD_TOKEN_PROVISIONING
          - PAYMENT_COMPLIANCE_STATUS
          - DD_COLLECTION_STATUS
          - ACCOUNT_SWITCH_UPDATE
          - PAYMENT_FILE_UPLOAD
          - ACCOUNT_STATUS_CHANGE
          - PAYMENT_APPROVAL_STATUS_CHANGE
          - CUSTOMER_BATCH_PAYMENT_APPROVAL_STATUS_CHANGE
          - CARD_BULK_OPS_COMPLETED
          - CUSTOMER_STATUS
          - CREDIT_AUTH
          - DD_INDEMNITY_CLAIM_STATUS
          - APPLICATION_STATUS_CHANGE
          - CUSTOMER_CREATED
        channel:
          type: string
          description: Channel used for sending the notification
          enum:
          - EMAIL
          - WEBHOOK
        destinations:
          type: array
          description: The list of emails or url(webhook) used for sending the notification. For 'EMAIL' channel this can be a list of comma separated email addresses. For 'WEBHOOK' channel this should be a single URL.
          items:
            type: string
          minItems: 1
        config:
          $ref: '#/components/schemas/notification.NotificationConfig'
          description: Configuration information for this Notification entity.
      required:
      - channel
      - config
      - destinations
      - type
    notification.NotificationConfig:
      type: object
      properties:
        threshold:
          type: number
          description: Amount threshold which triggers the notification. This attribute only applies to 'EMAIL' notifications channel, of type 'PAYIN', 'PAYOUT'.
          minimum: 0
        timesToRun:
          type: array
          description: Times of the day when to trigger the notification. This attribute applies only to 'EMAIL' notifications channel, of type 'BALANCE'.
          items:
            type: string
            enum:
            - AM
            - PM
        daysToRun:
          type: array
          description: Days of the week when to trigger the notification. This attribute applies only to 'EMAIL' notifications channel, of type 'BALANCE'.
          items:
            type: string
            enum:
            - MONDAY
            - TUESDAY
            - WEDNESDAY
            - THURSDAY
            - FRIDAY
            - SATURDAY
            - SUNDAY
        retry:
          type: boolean
          description: Flag indicating whether failed webhooks should be retried. This attribute applies only to 'WEBHOOK' notifications channel.
        secret:
          type: string
          description: Mandatory for webhook. Secret that is used in HMAC calculation, for webhooks. This attribute applies only to 'WEBHOOK' notifications channel.
          maxLength: 32
          minLength: 32
        hmacAlgorithm:
          type: string
          description: Signing algorithm that is used in Webhook HMAC calculation. This attribute only applies to 'WEBHOOK' notifications channel.
          enum:
          - hmac-sha1
          - hmac-sha256
          - hmac-sha384
          - hmac-sha512
    notification.UpdateNotificationRequest:
      type: object
      properties:
        status:
          type: string
          description: Status of the notification.
          enum:
          - ACTIVE
          - INACTIVE
        destinations:
          type: array
          description: The list of emails or url(webhook) used for sending the notification. For 'EMAIL' channel this can be a list of comma separated email addresses. For 'WEBHOOK' channel this should be a single URL.
          items:
            type: string
          minItems: 1
        config:
          $ref: '#/components/schemas/notification.NotificationConfig'
          description: Configuration information for this Notification entity.
      required:
      - config
      - destinations
      - status
    notification.NotificationResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique Identifier for the notification.
        customerId:
          type: string
          description: Unique Identifier for the customer of this notification.
        type:
          type: string
          description: Type of notification
          enum:
          - PAYIN
          - PAYOUT
          - BALANCE_LOW
          - BALANCE_HIGH
          - BALANCE
          - DDMANDATE
          - CUSTVSTAT
          - ACCOUNT_STATEMENT
          - PENDING_PAYMENTS
          - DD_INCOMING_DEBIT
          - DD_FAILED_CLAIM
          - DD_FUNDS_RETURNED
          - CARD_AUTH
          - CARD_AUTH_OFFLINE
          - CARD_CREATION
          - UPCOMING_CREDIT
          - UPCOMING_COLLECTION_CREDIT
          - UPCOMING_COLLECTION_DEBIT
          - CARD_STATUS_UPDATE
          - CARD_TOKEN_PROVISIONING
          - PAYMENT_COMPLIANCE_STATUS
          - DD_COLLECTION_STATUS
          - ACCOUNT_SWITCH_UPDATE
          - PAYMENT_FILE_UPLOAD
          - ACCOUNT_STATUS_CHANGE
          - PAYMENT_APPROVAL_STATUS_CHANGE
          - CUSTOMER_BATCH_PAYMENT_APPROVAL_STATUS_CHANGE
          - CARD_BULK_OPS_COMPLETED
          - CUSTOMER_STATUS
          - CREDIT_AUTH
          - DD_INDEMNITY_CLAIM_STATUS
          - APPLICATION_STATUS_CHANGE
          - CUSTOMER_CREATED
        channel:
          type: string
          description: Channel used to send the notification.
          enum:
          - EMAIL
          - WEBHOOK
        status:
          type: string
          description: Status of notification.
          enum:
          - ACTIVE
          - INACTIVE
        destinations:
          type: array
          description: A list of emails or url(webhook) used to send the notification. For 'EMAIL' channel this can be a list of comma separated email addresses. For 'WEBHOOK' channel this will be a single URL.
          items:
            type: string
        config:
          $ref: '#/components/schemas/notification.NotificationConfig'
          description: Configuration information for this Notification entity.
      required:
      - channel
      - config
      - customerId
      - destinations
      - id
      - status
      - type
    notification.WebHookFailureResponse:
      type: object
      properties:
        url:
          type: string
          description: Endpoint URL for receiving webhook data
        eventName:
          type: string
          description: Event which would trigger the webhook
          enum:
          - PAYIN
          - PAYOUT
          - BALANCE_LOW
          - BALANCE_HIGH
          - BALANCE
          - DDMANDATE
          - CUSTVSTAT
          - ACCOUNT_STATEMENT
          - PENDING_PAYMENTS
          - DD_INCOMING_DEBIT
          - DD_FAILED_CLAIM
          - DD_FUNDS_RETURNED
          - CARD_AUTH
          - CARD_AUTH_OFFLINE
          - CARD_CREATION
          - UPCOMING_CREDIT
          - UPCOMING_COLLECTION_CREDIT
          - UPCOMING_COLLECTION_DEBIT
          - CARD_STATUS_UPDATE
          - CARD_TOKEN_PROVISIONING
          - PAYMENT_COMPLIANCE_STATUS
          - DD_COLLECTION_STATUS
          - ACCOUNT_SWITCH_UPDATE
          - PAYMENT_FILE_UPLOAD
          - ACCOUNT_STATUS_CHANGE
          - PAYMENT_APPROVAL_STATUS_CHANGE
          - CUSTOMER_BATCH_PAYMENT_APPROVAL_STATUS_CHANGE
          - CARD_BULK_OPS_COMPLETED
          - CUSTOMER_STATUS
          - CREDIT_AUTH
          - DD_INDEMNITY_CLAIM_STATUS
          - APPLICATION_STATUS_CHANGE
          - CUSTOMER_CREATED
        customerBid:
          type: string
          description: Unique Identifier for the customer of this webhook.
        retry:
          type: boolean
          description: Turn webhook retry mechanism on/off
        lastFailedTime:
          type: string
          format: date-time
          description: Last failure time. Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g '2017-01-28T01:01:01+0000'
        data: {}
      required:
      - customerBid
      - eventName
      - lastFailedTime
      - retry
      - url
  securitySchemes:
    modulo_security:
      type: apiKey
      name: Authorization
      in: header
    TOKEN:
      type: apiKey
      name: Authorization
      in: header
x-readme:
  proxy-enabled: false