Handling event notifications sent by Payment Service v6
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 [email protected].
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).