Files
adyen-openapi/yaml/NotificationConfigurationService-v3.yaml
2021-07-09 17:59:36 +02:00

853 lines
31 KiB
YAML

openapi: 3.1.0
servers:
- url: https://cal-test.adyen.com/cal/services/Notification/v3
info:
version: '3'
x-publicVersion: true
title: 'Adyen for Platforms: Notification Configuration API'
description: 'The Notification Configuration API provides endpoints for setting
up and testing notifications that inform you of events on your platform, for example
when a KYC check or a payout has been completed.
For more information, refer to our [documentation](https://docs.adyen.com/platforms/notifications).
## Authentication
To connect to the Notification Configuration API, you must use basic authentication
credentials of your web service user. If you don''t have one, contact our [Adyen
Support Team](https://support.adyen.com/hc/en-us/requests/new). Then use its credentials
to authenticate your request, for example:
```
curl
-U "ws@MarketPlace.YourMarketPlace":"YourWsPassword" \
-H "Content-Type: application/json" \
...
```
Note that when going live, you need to generate new web service user credentials
to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).
## Versioning
The Notification Configuration API supports versioning of its endpoints through
a version suffix in the endpoint URL. This suffix has the following format: "vXX",
where XX is the version number.
For example:
```
https://cal-test.adyen.com/cal/services/Notification/v3/createNotificationConfiguration
```'
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://www.adyen.help/hc/en-us/community/topics
email: developer-experience@adyen.com
x-groups:
- General
paths:
/createNotificationConfiguration:
post:
summary: Subscribe to notifications.
description: Creates a subscription to notifications informing you of events
on your platform. After the subscription is created, the events specified
in the configuration will be sent to the URL specified in the configuration.
Subscriptions must be configured on a per-event basis (as opposed to, for
example, a per-account holder basis), so all event notifications of a marketplace
and of a given type will be sent to the same endpoint(s). A marketplace may
have multiple endpoints if desired; an event notification may be sent to as
many or as few different endpoints as configured.
operationId: post-createNotificationConfiguration
x-groupName: General
x-sortIndex: 1
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
basic:
$ref: '#/components/examples/post-createNotificationConfiguration-basic'
schema:
$ref: '#/components/schemas/CreateNotificationConfigurationRequest'
responses:
'200':
content:
application/json:
examples:
basic-200:
$ref: '#/components/examples/post-createNotificationConfiguration-basic-200'
schema:
$ref: '#/components/schemas/GetNotificationConfigurationResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/deleteNotificationConfigurations:
post:
summary: Delete an existing notification subscription configuration.
description: This endpoint is used to delete an existing notification subscription
configuration. After the subscription is deleted, no further event notifications
will be sent to the URL that was in the subscription.
operationId: post-deleteNotificationConfigurations
x-groupName: General
x-sortIndex: 6
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteNotificationConfigurationRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/getNotificationConfiguration:
post:
summary: Retrieve an existing notification subscription configuration.
description: This endpoint is used to retrieve the details of the configuration
of a notification subscription.
operationId: post-getNotificationConfiguration
x-groupName: General
x-sortIndex: 2
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetNotificationConfigurationRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetNotificationConfigurationResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/getNotificationConfigurationList:
post:
summary: Retrieve a list of existing notification subscription configurations.
description: This endpoint is used to retrieve the details of the configurations
of all of the notification subscriptions in the marketplace of the executing
user.
operationId: post-getNotificationConfigurationList
x-groupName: General
x-sortIndex: 3
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetNotificationConfigurationListResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/testNotificationConfiguration:
post:
summary: Test an existing notification configuration.
description: This endpoint is used to test an existing notification subscription
configuration. For each event type specified, a test notification will be
generated and sent to the URL configured in the subscription specified.
operationId: post-testNotificationConfiguration
x-groupName: General
x-sortIndex: 4
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TestNotificationConfigurationRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TestNotificationConfigurationResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
/updateNotificationConfiguration:
post:
summary: Update an existing notification subscription configuration.
description: This endpoint is used to update an existing notification subscription
configuration. If updating the event types, all event types desired must be
provided, otherwise the previous event type configuration will be overwritten.
operationId: post-updateNotificationConfiguration
x-groupName: General
x-sortIndex: 5
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
basic:
$ref: '#/components/examples/post-updateNotificationConfiguration-basic'
schema:
$ref: '#/components/schemas/UpdateNotificationConfigurationRequest'
responses:
'200':
content:
application/json:
examples:
basic-200:
$ref: '#/components/examples/post-updateNotificationConfiguration-basic-200'
schema:
$ref: '#/components/schemas/GetNotificationConfigurationResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
components:
schemas:
CreateNotificationConfigurationRequest:
properties:
configurationDetails:
description: Details of the prospective notification subscription configuration.
$ref: '#/components/schemas/NotificationConfigurationDetails'
required:
- configurationDetails
DeleteNotificationConfigurationRequest:
properties:
notificationIds:
description: A list of IDs of the notification subscription configurations
to be deleted.
items:
format: int64
type: integer
type: array
required:
- notificationIds
EmptyRequest: {}
ExchangeMessage:
properties:
messageCode:
type: string
messageDescription:
type: string
GenericResponse:
properties:
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
submittedAsync:
description: 'Indicates whether the request is processed asynchronously.
Depending on the request''s platform settings, the following scenarios
may be applied:
* **true**: The request is queued and will be executed when the providing
service is available in the order in which the requests are received.
* **false**: The processing of the request is immediately attempted; it
may result in an error if the providing service is unavailable.'
type: boolean
GetNotificationConfigurationListResponse:
properties:
configurations:
description: Details of the notification subscription configurations.
items:
$ref: '#/components/schemas/NotificationConfigurationDetails'
type: array
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
submittedAsync:
description: 'Indicates whether the request is processed asynchronously.
Depending on the request''s platform settings, the following scenarios
may be applied:
* **true**: The request is queued and will be executed when the providing
service is available in the order in which the requests are received.
* **false**: The processing of the request is immediately attempted; it
may result in an error if the providing service is unavailable.'
type: boolean
required:
- configurations
GetNotificationConfigurationRequest:
properties:
notificationId:
description: The ID of the notification subscription configuration whose
details are to be retrieved.
format: int64
type: integer
required:
- notificationId
GetNotificationConfigurationResponse:
properties:
configurationDetails:
description: Details of the notification subscription configuration.
$ref: '#/components/schemas/NotificationConfigurationDetails'
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
submittedAsync:
description: 'Indicates whether the request is processed asynchronously.
Depending on the request''s platform settings, the following scenarios
may be applied:
* **true**: The request is queued and will be executed when the providing
service is available in the order in which the requests are received.
* **false**: The processing of the request is immediately attempted; it
may result in an error if the providing service is unavailable.'
type: boolean
required:
- configurationDetails
NotificationConfigurationDetails:
properties:
active:
description: Indicates whether the notification subscription is active.
type: boolean
apiVersion:
description: The API version of the notification to send.
format: int32
type: integer
description:
description: A description of the notification subscription configuration.
type: string
eventConfigs:
description: The types of events whose notifications apply to this configuration.
items:
$ref: '#/components/schemas/NotificationEventConfiguration'
type: array
messageFormat:
deprecated: true
description: 'The data format of the notification to be sent.
>Permitted values: `JSON`, `SOAP`.'
enum:
- JSON
- SOAP
type: string
notificationId:
description: 'The ID of the configuration.
>Required if updating an existing configuration, ignored during the creation
of a configuration.'
format: int64
type: integer
notifyPassword:
description: The password to use when accessing the notifyURL with the specified
username.
type: string
notifyURL:
description: The URL to which the notifications are to be sent.
type: string
notifyUsername:
description: The username to use when accessing the notifyURL.
type: string
sendActionHeader:
deprecated: true
description: 'Indicates whether an action header should be included.
>Only applies to SOAP messages (as specified in messageFormat).'
type: boolean
sslProtocol:
description: 'The SSL protocol employed by the endpoint.
>Permitted values: `SSL`, `SSLInsecureCiphers`, `TLS`, `TLSv10`, `TLSv10InsecureCiphers`,
`TLSv11`, `TLSv12`.'
enum:
- SSL
- SSLInsecureCiphers
- TLS
- TLSv10
- TLSv10InsecureCiphers
- TLSv11
- TLSv12
type: string
required:
- eventConfigs
- notifyURL
NotificationEventConfiguration:
properties:
eventType:
description: 'The type of event triggering the notification.
>Permitted values: `ACCOUNT_HOLDER_CREATED`, `ACCOUNT_CREATED`, `ACCOUNT_UPDATED`,
`ACCOUNT_HOLDER_UPDATED`, `ACCOUNT_HOLDER_STATUS_CHANGE`, `ACCOUNT_HOLDER_STORE_STATUS_CHANGE`,
`ACCOUNT_HOLDER_VERIFICATION`, `ACCOUNT_HOLDER_LIMIT_REACHED`, `ACCOUNT_HOLDER_PAYOUT`,
`PAYMENT_FAILURE`, `SCHEDULED_REFUNDS`, `REPORT_AVAILABLE`, `TRANSFER_FUNDS`,
`BENEFICIARY_SETUP`, `COMPENSATE_NEGATIVE_BALANCE`.'
enum:
- ACCOUNT_CLOSED
- ACCOUNT_CREATED
- ACCOUNT_FUNDS_BELOW_THRESHOLD
- ACCOUNT_HOLDER_CREATED
- ACCOUNT_HOLDER_LIMIT_REACHED
- ACCOUNT_HOLDER_PAYOUT
- ACCOUNT_HOLDER_STATUS_CHANGE
- ACCOUNT_HOLDER_STORE_STATUS_CHANGE
- ACCOUNT_HOLDER_UPCOMING_DEADLINE
- ACCOUNT_HOLDER_UPDATED
- ACCOUNT_HOLDER_VERIFICATION
- ACCOUNT_UPDATED
- BENEFICIARY_SETUP
- COMPENSATE_NEGATIVE_BALANCE
- DIRECT_DEBIT_INITIATED
- PAYMENT_FAILURE
- REFUND_FUNDS_TRANSFER
- REPORT_AVAILABLE
- SCHEDULED_REFUNDS
- TRANSFER_FUNDS
- TRANSFER_NOT_PAIDOUT_TRANSFERS
type: string
includeMode:
description: 'Indicates whether the specified eventType is to be sent to
the endpoint or all events other than the specified eventType (and other
specified eventTypes) are to be sent.
>Permitted values: `INCLUDE`, `EXCLUDE`.
>- `INCLUDE`: send the specified eventType.
>- `EXCLUDE`: send all eventTypes other than the specified eventType (and
other eventTypes marked with `EXCLUDE`).'
enum:
- EXCLUDE
- INCLUDE
type: string
required:
- eventType
- includeMode
ServiceError:
properties:
errorCode:
description: The error code mapped to the error message.
type: string
errorType:
description: The category of the error.
type: string
message:
description: A short explanation of the issue.
type: string
pspReference:
description: The PSP reference of the payment.
type: string
status:
description: The HTTP response status.
format: int32
type: integer
TestNotificationConfigurationRequest:
properties:
eventTypes:
description: 'The event types to test. If left blank, then all of the configured
event types will be tested.
>Permitted values: `ACCOUNT_HOLDER_CREATED`, `ACCOUNT_CREATED`, `ACCOUNT_UPDATED`,
`ACCOUNT_HOLDER_UPDATED`, `ACCOUNT_HOLDER_STATUS_CHANGE`, `ACCOUNT_HOLDER_STORE_STATUS_CHANGE`
`ACCOUNT_HOLDER_VERIFICATION`, `ACCOUNT_HOLDER_LIMIT_REACHED`, `ACCOUNT_HOLDER_PAYOUT`,
`PAYMENT_FAILURE`, `SCHEDULED_REFUNDS`, `REPORT_AVAILABLE`, `TRANSFER_FUNDS`,
`BENEFICIARY_SETUP`, `COMPENSATE_NEGATIVE_BALANCE`.'
items:
enum:
- ACCOUNT_CLOSED
- ACCOUNT_CREATED
- ACCOUNT_FUNDS_BELOW_THRESHOLD
- ACCOUNT_HOLDER_CREATED
- ACCOUNT_HOLDER_LIMIT_REACHED
- ACCOUNT_HOLDER_PAYOUT
- ACCOUNT_HOLDER_STATUS_CHANGE
- ACCOUNT_HOLDER_STORE_STATUS_CHANGE
- ACCOUNT_HOLDER_UPCOMING_DEADLINE
- ACCOUNT_HOLDER_UPDATED
- ACCOUNT_HOLDER_VERIFICATION
- ACCOUNT_UPDATED
- BENEFICIARY_SETUP
- COMPENSATE_NEGATIVE_BALANCE
- DIRECT_DEBIT_INITIATED
- PAYMENT_FAILURE
- REFUND_FUNDS_TRANSFER
- REPORT_AVAILABLE
- SCHEDULED_REFUNDS
- TRANSFER_FUNDS
- TRANSFER_NOT_PAIDOUT_TRANSFERS
type: string
type: array
notificationId:
description: The ID of the notification subscription configuration to be
tested.
format: int64
type: integer
required:
- notificationId
TestNotificationConfigurationResponse:
properties:
errorMessages:
description: Any error messages encountered.
items:
type: string
type: array
eventTypes:
description: 'The event types that were tested.
>Permitted values: `ACCOUNT_HOLDER_CREATED`, `ACCOUNT_CREATED`, `ACCOUNT_UPDATED`,
`ACCOUNT_HOLDER_UPDATED`, `ACCOUNT_HOLDER_STATUS_CHANGE`, `ACCOUNT_HOLDER_STORE_STATUS_CHANGE`
`ACCOUNT_HOLDER_VERIFICATION`, `ACCOUNT_HOLDER_LIMIT_REACHED`, `ACCOUNT_HOLDER_PAYOUT`,
`PAYMENT_FAILURE`, `SCHEDULED_REFUNDS`, `REPORT_AVAILABLE`, `TRANSFER_FUNDS`,
`BENEFICIARY_SETUP`, `COMPENSATE_NEGATIVE_BALANCE`.'
items:
enum:
- ACCOUNT_CLOSED
- ACCOUNT_CREATED
- ACCOUNT_FUNDS_BELOW_THRESHOLD
- ACCOUNT_HOLDER_CREATED
- ACCOUNT_HOLDER_LIMIT_REACHED
- ACCOUNT_HOLDER_PAYOUT
- ACCOUNT_HOLDER_STATUS_CHANGE
- ACCOUNT_HOLDER_STORE_STATUS_CHANGE
- ACCOUNT_HOLDER_UPCOMING_DEADLINE
- ACCOUNT_HOLDER_UPDATED
- ACCOUNT_HOLDER_VERIFICATION
- ACCOUNT_UPDATED
- BENEFICIARY_SETUP
- COMPENSATE_NEGATIVE_BALANCE
- DIRECT_DEBIT_INITIATED
- PAYMENT_FAILURE
- REFUND_FUNDS_TRANSFER
- REPORT_AVAILABLE
- SCHEDULED_REFUNDS
- TRANSFER_FUNDS
- TRANSFER_NOT_PAIDOUT_TRANSFERS
type: string
type: array
exchangeMessages:
description: The notification message and related response messages.
items:
$ref: '#/components/schemas/ExchangeMessage'
type: array
notificationId:
description: The ID of the notification subscription configuration.
format: int64
type: integer
okMessages:
description: A list of messages describing the testing steps.
items:
type: string
type: array
pspReference:
description: The reference of a request. Can be used to uniquely identify
the request.
type: string
resultCode:
description: The result code.
type: string
submittedAsync:
description: 'Indicates whether the request is processed asynchronously.
Depending on the request''s platform settings, the following scenarios
may be applied:
* **true**: The request is queued and will be executed when the providing
service is available in the order in which the requests are received.
* **false**: The processing of the request is immediately attempted; it
may result in an error if the providing service is unavailable.'
type: boolean
required:
- notificationId
- eventTypes
- okMessages
- exchangeMessages
UpdateNotificationConfigurationRequest:
properties:
configurationDetails:
description: Details of the notification subscription configuration to be
updated.
$ref: '#/components/schemas/NotificationConfigurationDetails'
required:
- configurationDetails
securitySchemes:
ApiKeyAuth:
in: header
name: X-API-Key
type: apiKey
BasicAuth:
scheme: basic
type: http
examples:
post-createNotificationConfiguration-basic:
summary: Create a notification configuration
value:
configurationDetails:
active: true
description: Test notification769551
eventConfigs:
- NotificationEventConfiguration:
eventType: ACCOUNT_HOLDER_VERIFICATION
includeMode: INCLUDE
messageFormat: SOAP
notifyURL: https://www.adyen.com/notification-handler
notifyUsername: testUserName
notifyPassword: testPassword
sendActionHeader: true
sslProtocol: SSL
post-createNotificationConfiguration-basic-200:
summary: Example response for request 'basic'
value:
pspReference: '8616178952143018'
submittedAsync: 'false'
configurationDetails:
active: 'true'
description: Test notification769551
eventConfigs:
- NotificationEventConfiguration:
eventType: ACCOUNT_HOLDER_VERIFICATION
includeMode: INCLUDE
messageFormat: SOAP
notificationId: 28467
notifyURL: https://www.adyen.com/notification-handler
sendActionHeader: 'true'
sslProtocol: SSLInsecureCiphers
post-updateNotificationConfiguration-basic:
summary: Update notification configurations
value:
configurationDetails:
active: false
description: new description799847
eventConfigs:
- NotificationEventConfiguration:
eventType: ACCOUNT_HOLDER_CREATED
includeMode: EXCLUDE
- NotificationEventConfiguration:
eventType: ACCOUNT_CREATED
includeMode: INCLUDE
notificationId: 21259
notifyPassword: testPassword2
notifyURL: http://www.adyen.com
notifyUsername: testUserName2
sendActionHeader: false
sslProtocol: TLSv10
post-updateNotificationConfiguration-basic-200:
summary: Example response for request 'basic'
value:
pspReference: '8516178951636344'
submittedAsync: 'false'
configurationDetails:
active: 'false'
description: new description799847
eventConfigs:
- NotificationEventConfiguration:
eventType: ACCOUNT_CREATED
includeMode: INCLUDE
- NotificationEventConfiguration:
eventType: ACCOUNT_HOLDER_CREATED
includeMode: EXCLUDE
messageFormat: JSON
notificationId: 21259
notifyURL: http://www.adyen.com
sendActionHeader: 'false'
sslProtocol: TLSv10