Payment Service v6 Event Notifications is an API which (in contrast to the other APIs) is hosted/implemented by the partner. PXP System sends a notification to the partner-hosted API whenever any events of interest to the partner occur. Currently only merchant state change events are supported (see Notifications for more information).

Requests will be sent by PXP to the partner using HTTPs POST, with payload in JSON format, e.g.:

POST /events HTTP/1.1
Host: https://api.example.com:443
Basic-Authorization: xxxxxxxx
Content-Type: application/json; charset=utf-8
Content-Length: xxxxx

{ 
   "id":"0b1f3914-b6e7-462f-ae49-3fc3fbaa5814",
   "createdOn":"2019-01-08 09:44:40:465",
   "type":"MerchantStateChangedEvent",
   "data":{ 
      "merchantStateChangedEvent":{ 
         "merchantId":"5752ad4b-f47f-43b5-8930-06c8cdab69cc",
         "state":{ 
            "type":"Blocked",
            "reason":""
         },
         "cardPresentMid":""
      }
   }
}

🚧
Request Authentication
Note the headers sent, in particular the Basic-Authorization header containing agreed in advance username/password which must be validated by the partner's API endpoint.
In addition the partner may decide to restrict calls to the API coming only from PXP System's source IP.

Endpoints

The test and live endpoint URLs which will be used by the partner system for handling event notifications sent by Payment Service v6 need to be configured in the PXP System. This needs to be requested from support@pxpfinancial.com.
In case basic authentication is used, the credentials (Username and Password) also need to be provided for configuration.

YAML Contract

The below contract defines the structure of the event notifications:

swagger: '2.0'
info:
  title: Payment Service v6 - Event Notifications
  description: Payment Service v6 - Event Notifications
  version: 6.0.0
schemes:
  - https
host: api.example.com
paths:
  /events:
    post:
      summary: Handles event notifications sent by the PXP system.
      description: Handles event notifications sent by the PXP system.
      produces:
        - application/json
      parameters:
        - in: body
          name: Event
          required: true
          schema:
              $ref: '#/definitions/Event'
      responses:
        '200':
          description: Event successfully received by the subscriber.
        '400':
          description: The subscriber could not process the event. The event will not be re-sent again.
        '500':
          description: Technical error occurred, the event will be sent again.

definitions:
  Event:
    description: Envelope for different types of events. The 'data' property contains the properties for the specified event type.
    type: object
    properties:
      id:
        type: string
        description: The unique identifier of the event. Can be used for tracking which events have been already processed.
        example: AAF851BE-94C4-4F96-87F3-6EAE1AA2D51D
      createdOn:
        type: string
        description: The UTC date and time when the event was sent. Used for identifying the correct order of events.
        example: 2010-10-18 23:10:27:231        
      type:
        type: string
        description: The type of the event. Used for specifying what properties will be put in the 'data' property. 
        enum: 
          - MerchantStateChangedEvent
          - PreScreenMerchantStateChangedEvent
      data:
        type: object
        description: Contains the specific event data. Only one of the following properties must be sent, matching the event type.
        properties:
          merchantStateChangedEvent:
            $ref: '#/definitions/MerchantStateChangedEvent'
          preScreenMerchantStateChangedEvent:
            $ref: '#/definitions/PreScreenMerchantStateChangedEvent'
    required:
    - id
    - createdOn
    - type
    - data
    
  MerchantStateChangedEvent:
    type: object
    description: Indicates that a merchant's state has been changed. Contains the data of the new state.
    properties:        
      merchantId:
        type: string
        description: The unique identifier of the merchant, which was received in the merchant registration response.
        example: f0deffbc-9c87-40aa-b863-5e2b6caf14a7
      state:
        type: object
        description: The new state of the merchant. See https://developer.kalixa.com/docs/merchant-onboarding-notifications for additional information about states and state reasons.
        properties:
          type:
            type: string
            description: The name of the state.
            example: Declined
            enum:
              - Declined
              - PendingOnPreScreeningData
              - PendingOnUnderwritingData
              - PendingOnDocuments
              - PendingOnContract
              - PendingOnActivation
              - Active
              - ConditionallyActive
              - Blocked
              - Closed
          reason:
            type: string
            description: Additional details about the state. Applicable only for some states. See https://developer.kalixa.com/docs/merchant-onboarding-notifications for additional information about states and state reasons.
            example: Already Processing
        required:
        - type
      cardPresentMid:
        type: string
        description: The merchant identifier to be used in payment initiations for a card present (CP/POS) shop. See https://developer.kalixa.com/v1.0/docs/conditionally-mandatory-parameters for more information about submitting card payments for POS (CP) merchants.
        example: 7171800701
    required:
    - merchantId
    - state

  PreScreenMerchantStateChangedEvent:
    type: object
    description: Indicates that a prescreen-merchant's state has been changed. Contains the data of the new state.
    properties:        
      preScreenMerchantId:
        type: string
        description: The unique identifier of the prescreen-merchant, which was received in the prescreen-merchant registration response.
        example: f0deffbc-9c87-40aa-b863-5e2b6caf14a7
      state:
        type: object
        description: The new state of the prescreen-merchant. See https://developer.kalixa.com/docs/merchant-onboarding-notifications for additional information about states and state reasons.
        properties:
          type:
            type: string
            description: The name of the state.
            example: Declined
            enum:
              - Approved
              - Declined
              - Pending
        required:
        - type        
    required:
    - preScreenMerchantId
    - state

📘
Response
Note that an empty response is currently required, with the appropriate HTTP Status Code as per the contract above (200, 400 or 500).