openapi: 3.0.0 info: version: 1.0.2 title: Swift Notifications API description: >- Events API following the CloudEvents specification (https://cloudevents.io/). The Swift API Channel emits and receives notifications conforming to this specification. - Swift customers sending events or notifications implement this specification as a consumer of the API, providing the event payload in the CloudEvents "data" element. The event data must conform to the API/schema specification that is provided in the CloudEvents "dataschema" element in the payload. - Swift customers receiving events must implement this specification as a provider of the API. All events that the customer subscribes to shall be emitted through this API - the customer identifies and processes the event based on the CloudEvents attributes such as the event type and source. contact: name: Developer Hub url: 'https://developer.swift.com' email: developer@swift.com license: name: API Restricted License url: 'https://developer.swift.com/api-license' servers: - description: Production environment url: https://api.swiftnet.sipn.swift.com/swift-notif/v1 - description: Test environment url: https://api-test.swiftnet.sipn.swift.com/swift-notif/v1 - description: Sandbox environment url: https://sandbox.swift.com/swift-notif/v1 paths: /notifications: post: tags: - Swift Asynchronous Notifications summary: Emits a notification conforming to the CloudEvents specification. description: >- Emits an event from Swift using Cloud Events as the standard to describe an event. Cloud Events "structured mode", where the Cloud Events metadata attributes are part of the request body, is used to keep the event protocol-agnostic and the specification conformant to Swift API Design Guidelines. All events would be emitted through the same endpoint with the Cloud Events metadata indicating the event type and the schema for the "data" element. operationId: CloudEventsPost parameters: - $ref: '#/components/parameters/X-Request-ID' - $ref: '#/components/parameters/X-BIC' requestBody: required: true content: application/cloudevents+json; charset=UTF-8: schema: $ref: '#/components/schemas/CloudEventsResource' example: id: 006cc91c-a85c-41ed-afa1-0242ac120002 source: 'gss.screening.api' specversion: '1.0' type: 'com.gss.screening.result' datacontenttype: 'application/json' dataschema: 'https://app.swaggerhub.com/apis/SWIFT-API/GSS_Transaction_Screening/2.0.1#/components/...' subject: ef97ffc8-2d8c-408a-9195-44a0489df831 time: '2024-07-01T21:47:07Z' data: requestId: 'c0ab6991-aa88-4696-beaa-fd7be04aaff5' transactionId: 'ef97ffc8-2d8c-408a-9195-44a0489df831' gssId: '006cc91c-a85c-41ed-afa1-0242ac120002' idempotencyKey: 'c0ab6991-aa88-4696-beaa-fd7be04aaff5' eventDateTime: '2023-01-01T12:12:12.123Z' result: status: "PASS" outcome: "ALERT_DISPOSITION.NO_MATCH" bankBIC: "DEUTPLPK" responses: '201': description: Created. '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: api_request_is_malformed: value: code: SwAP501 severity: Fatal text: API request is malformed. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: invalid_token: value: severity: Fatal code: SwAP502 text: Invalid OAuth token. insufficient_scope: value: severity: Fatal code: SwAP503 text: >- OAuth access token has insufficient scope for the requested service. '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: 403-SwAP503: value: severity: Fatal code: SwAP503 text: OAuth access token has insufficient scope for the requested service. '413': description: Payload Too Large content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: 403-SwAP503: value: severity: Fatal code: SwAP503 text: Payload Too Large. '415': description: Unsupported Media Type content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: 415-BadZip: value: severity: Fatal code: # Error codes should allow your API to be identified! text: Media type application/zip is not supported. '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: too_many_requests: value: severity: Transient code: SwAP507 text: >- Request cannot be processed at this time. Please try again. '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '504': description: Gateway Timeout content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: service_timeout: value: severity: Transient code: SwAP591 text: Service provider timeout. Please try later. default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' components: parameters: X-Request-ID: description: "Specify an unique end to end tracking request ID. The element will be populated by the SWIFT API gateway." name: X-Request-ID in: header schema: type: string X-BIC: name: X-BIC in: header description: >- The customer BIC that will be receiving the Cloud Event. required: true style: simple explode: false schema: pattern: ^[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}$ type: string example: CCLABEBB schemas: CloudEventsResource: type: object properties: id: description: "A unique identifier for the event. MUST be unique within the scope of the event producer. MUST be a non-empty string." type: string source: description: "Identifies the context in which the event happened. Event producers MUST ensure that source + id is unique for each distinct event. MUST be a non-empty URI reference (absolute URI recommended)." type: string format: uri-reference specversion: description: "The version of the CloudEvents specification which the event uses. MUST be a non-empty string wth the version denoted as major.minor (e.g. '1.0')" type: string type: description: "Describes the type of event related to the originating occurrence. MUST be a non-empty string. SHOULD be prefixed with a reverse DNS name." type: string datacontenttype: description: "The content type of the 'data' value." type: string dataschema: description: "Identifies the schema that 'data' adheres to. If present MUST be a non-empty URI - NOTE: For Swift events, dataschema MUST be supplied even though it remains optional in the specification as per the CloudEvents specification." type: string format: uri-reference subject: description: "This describes the subject of the event in the context of the event producer (identified by 'source'). A subscriber will typically subscribe to events emitted by a source, but the source identifier alone might not be sufficient as a qualifier for any specific event if the source context has internal sub-structure." type: string time: # Timestamp of when the event occurrence happened $ref: '#/components/schemas/ISONormalisedDateTime' data: type: object additionalProperties: true required: - id - source - type - specversion - dataschema ErrorMessage: type: object additionalProperties: false properties: severity: type: string enum: - Fatal - Transient - Logic code: type: string text: type: string user_message: type: string more_info: type: string format: uri required: - severity - code - text ISONormalisedDateTime: type: string description: an ISODateTime whereby all timezoned dateTime values are UTC. pattern: ^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.[0-9]+)?(?:Z)$ securitySchemes: oauthBearerToken: type: http scheme: bearer bearerFormat: opaque OAuth 2.0 description: >- The access token obtained as a result of OAuth 2.0 JWT Bearer Token Flow - RFC 7523. Please visit [SWIFT OAuth Token API](https://developer.swift.com/swift-oauth-token-api) for more information and examples. In this declaration only the basic security element to Transientsport the bearer token of an OAuth2 process is declared. This securityScheme is applied to the consumer of the API - for Swift async events, this is the party sending/emitting the event to Swift. security: - oauthBearerToken: []