openapi: 3.0.3
info:
title: Mastercard Commercial Event Notifications
description: >-
Receive near real-time payment alerts enabling accurate completion and
reconciliation of commercial payments
version: 1.2.0
contact:
name: API Support
email: [email protected]
url: https://developer.mastercard.com/support
servers:
- url: https://api.mastercard.com/commercial-event-notifications
description: Production server URL
- url: https://sandbox.api.mastercard.com/commercial-event-notifications
description: Sandbox server URL
tags:
- name: FieldMapping
description: >-
FieldMapping Operations - Retrieving field information for notification
message content
- name: Subscription
description: >-
Subscription Operations - Creating, retrieving, updating and deleting
subscriptions
- name: Notifications
description: Notification Operations - Retrieving collection of generated notifications
paths:
/fieldmappings:
get:
summary: Retrieving fieldmappings
description: >-
Retrieve field information for notification message content, which can
be used to set up subscription filter specifications for those
notifications.
tags:
- Field Mapping
operationId: getFieldMapping
responses:
'200':
$ref: '#/components/responses/FieldMappingSuccess'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
/subscriptions:
post:
summary: Creating subscriptions
description: >-
Create a subscription that will cause notifications to be generated for
the specified events.
tags:
- Subscriptions
operationId: createSubscription
requestBody:
$ref: '#/components/requestBodies/CreateSubscription'
responses:
'201':
$ref: '#/components/responses/CreatedSubscription'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
callbacks:
pushNotificationsMessage:
to registered notification url:
post:
requestBody:
description: Push Notifications message for subscribed events
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/notification'
responses:
'200':
description: >
Your server implementation should return this HTTP status
code
if the data was received successfully
get:
summary: Retrieving subscriptions
description: Retrieve the subscriptions defined for this client.
tags:
- Subscriptions
operationId: getAllSubscriptions
parameters:
- $ref: '#/components/parameters/subscriptionsOffsetParam'
- $ref: '#/components/parameters/subscriptionsLimitParam'
- $ref: '#/components/parameters/sortParam'
responses:
'200':
$ref: '#/components/responses/GetSubscription'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
/subscriptions/{id}:
get:
summary: Retrieving subscription by id
description: Retrieve the details of a subscription.
tags:
- Subscriptions
- Subscription
operationId: getSubscription
parameters:
- $ref: '#/components/parameters/subscriptionIdParam'
responses:
'200':
$ref: '#/components/responses/GetSubscriptionsById'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
put:
summary: Updating subscription
description: Update an existing subscription.
tags:
- Subscriptions
- Subscription
operationId: updateSubscription
parameters:
- $ref: '#/components/parameters/subscriptionIdParam'
requestBody:
$ref: '#/components/requestBodies/UpdateSubscription'
responses:
'200':
$ref: '#/components/responses/UpdatedSubscription'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
delete:
summary: Deleting subscription
description: >-
Deletes a subscription, with the effect that no further notifications
will be generated for that subscription.
tags:
- Subscriptions
- Subscription
operationId: deleteSubscription
parameters:
- $ref: '#/components/parameters/subscriptionIdParam'
responses:
'204':
description: >-
No content, indicates that the subscription has been deleted
successfully
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/notifications:
get:
summary: Getting notifications
description: >
This endpoint represents the collection of notifications that have been
generated for the client within the retention period for notifications.
A GET on this endpoint retrieves the notifications in a paginated
manner.
tags:
- Notifications
operationId: getNotifications
parameters:
- $ref: '#/components/parameters/startDateParam'
- $ref: '#/components/parameters/endDateParam'
- $ref: '#/components/parameters/subscriptionNameParam'
- $ref: '#/components/parameters/subjectNameParam'
- $ref: '#/components/parameters/pushStatusParam'
- $ref: '#/components/parameters/notificationsOffsetParam'
- $ref: '#/components/parameters/notificationsLimitParam'
responses:
'200':
$ref: '#/components/responses/GetNotificationResponse'
'400':
$ref: '#/components/responses/NotFound'
'403':
$ref: '#/components/responses/Forbidden'
components:
schemas:
Subscription:
properties:
id:
description: >-
Subscription id, auto-generated by the system and read-only for the
client
type: string
minLength: 1
maxLength: 255
readOnly: true
example: >-
CNSa91bf379b48a593fd17f07f431bad8fb296796498f4e9982ea134394c1fa4f071556724070
name:
description: >-
Subscription name - must be unique for the client and must comprise
letters, numbers, dashes and underscores only. To check for
uniqueness, you can retrieve the existing collection of
subscriptions by performing a GET on the /subscriptions resource
type: string
minLength: 1
maxLength: 50
example: TEST_SUBSCRIPTION
subjectType:
description: >-
The type of event to which this subscription refers. Currently
allowed values are 'PAYMENT_AUTHORIZATION', 'PAYMENT_UPDATE',
'CLEARING', 'BPC_PAYMENT_AUTHORIZATION', 'TOKEN_PROVISIONING_EVENT'
and 'TOKEN_LIFECYCLE_EVENT'.
type: string
minLength: 1
maxLength: 50
enum:
- PAYMENT_AUTHORIZATION
- PAYMENT_UPDATE
- CLEARING
- BPC_PAYMENT_AUTHORIZATION
- TOKEN_PROVISIONING_EVENT
- TOKEN_LIFECYCLE_EVENT
example: PAYMENT_AUTHORIZATION
subscriberId:
description: The id of the subscriber (client) to which the subscription belongs
type: string
minLength: 1
maxLength: 255
readOnly: true
example: >-
CNSa91bf379b48a593fd17f07f431bad8fb296796498f4e9982ea134394c1fa4f071556724071
active:
description: >-
Denotes whether the subscription is active (in which case
notifications will be generated for matching events) or not (in
which case no notifications will be generated for this subscription)
type: boolean
example: true
specifications:
description: >-
A list of criteria specifications that define what events will cause
notifications to be generated. If the list of specifications is
empty, then notifications will be generated for all events for the
specified subject type that the client is entitled to receive.
type: array
items:
$ref: '#/components/schemas/Specification'
required:
- name
- active
- subjectType
Specification:
description: >-
Specifies criteria to determine whether an event should cause a
notification to be generated.
type: object
properties:
id:
description: >-
Specification id, auto-generated by the system and read-only for the
client
type: string
minLength: 1
maxLength: 255
readOnly: true
example: >-
CNSa91bf379b48a593fd17f07f431bad8fb296796498f4e9982ea134394c1fa4f071556724072
type:
description: >-
The type of item to which the criteria refers. Currently the type
'FIELD' is allowed, which refers to matching a field in the
notification itself
type: string
minLength: 1
maxLength: 255
default: FIELD
example: FIELD
operator:
description: >-
The operator that defines how this specification (criteria)
logically relates to other specifications in the list. The first
specification in the list will have an operator of 'WHERE' and
subsequent specifications will have an 'AND' or 'OR' relationship
with their preceding specification
type: string
minLength: 1
maxLength: 255
default: WHERE
example: WHERE
fieldMappingName:
description: The name of the field that is to be checked
type: string
minLength: 1
maxLength: 255
example: purchaseRequest.rcnAlias
fieldOperator:
description: >-
The check operation that is to be performed. Currently one of
allowed values are 'EQUALS', 'GREATER_THAN', 'LESS_THAN', 'BETWEEN'
type: string
minLength: 1
maxLength: 255
default: EQUALS
example: EQUALS
expectedContent:
$ref: '#/components/schemas/FieldContent'
children:
description: >-
A list of nested child specifications, used where needed to
implement complex matching logic
type: array
items:
$ref: '#/components/schemas/Specification'
required:
- type
- operator
- fieldMappingName
- fieldOperator
- expectedContent
FieldMapping:
description: >-
A collection of field definitions any of which can be used to specify
matching criteria when creating a subscription.
type: object
properties:
id:
description: Field mapping id
type: string
minLength: 1
maxLength: 255
readOnly: true
example: >-
CNSa91bf379b48a593fd17f07f431bad8fb296796498f4e9982ea134394c1fa4f071556724073
name:
description: The name used to refer to the field in the specification criteria.
type: string
minLength: 1
maxLength: 255
example: purchaseRequest.rcnAlias
displayName:
description: Descriptive name of the field
type: string
minLength: 1
maxLength: 255
example: Purchase request RCN alias
subjectType:
description: >-
The type of subject to which the field refers. Currently allowed
values are 'PAYMENT_AUTHORIZATION', 'PAYMENT_UPDATE', 'CLEARING',
'BPC_PAYMENT_AUTHORIZATION', 'TOKEN_PROVISIONING_EVENT' and
'TOKEN_LIFECYCLE_EVENT'.
type: string
minLength: 1
maxLength: 50
example: PAYMENT_AUTHORIZATION
contentType:
description: >-
What type of information the field (and therefore the matching
criteria for that field) will contain. Currently one of allowed
values are 'INTEGER', 'number', 'TEXT', 'DATE', 'CURRENCY'.
type: string
default: TEXT
example: TEXT
FieldContent:
description: >-
The structure used to specify what content in the field should cause a
match.
type: object
required:
- contentType
- value
properties:
contentType:
description: >-
The type of value that is being checked. Currently one of allowed
values are 'INTEGER', 'number', 'TEXT', 'DATE', 'CURRENCY'
type: string
minLength: 1
maxLength: 255
default: TEXT
example: TEXT
value:
description: The actual value to be checked
type: object
example: Travel Expense RCN
anotherValue:
description: >-
An additional value to be checked, if the match operator takes more
than one value (e.g. 'BETWEEN')
type: object
example: Travel Expense RCN
SubscriptionDetails:
properties:
id:
description: >-
Subscription id, auto-generated by the system and read-only for the
client
type: string
minLength: 1
maxLength: 255
readOnly: true
example: >-
CNSa91bf379b48a593fd17f07f431bad8fb296796498f4e9982ea134394c1fa4f071556724070
name:
description: >-
Subscription name - must be unique for the client and must comprise
letters, numbers, dashes and underscores only. To check for
uniqueness, you can retrieve the existing collection of
subscriptions by performing a GET on the /subscriptions resource
type: string
minLength: 1
maxLength: 50
example: TEST_SUBSCRIPTION
subjectType:
description: >-
The type of event to which this subscription refers. Currently
allowed values are 'PAYMENT_AUTHORIZATION', 'PAYMENT_UPDATE',
'CLEARING', 'BPC_PAYMENT_AUTHORIZATION', 'TOKEN_PROVISIONING_EVENT',
'TOKEN_LIFECYCLE_EVENT'
type: string
minLength: 1
maxLength: 50
example: PAYMENT_AUTHORIZATION
subscriberId:
description: The id of the subscriber (client) to which the subscription belongs
type: string
minLength: 1
maxLength: 255
readOnly: true
example: >-
CNSa91bf379b48a593fd17f07f431bad8fb296796498f4e9982ea134394c1fa4f071556724071
active:
description: >-
Denotes whether the subscription is active (in which case
notifications will be generated for matching events) or not (in
which case no notifications will be generated for this subscription)
type: boolean
example: true
specifications:
description: >-
A list of criteria specifications that define what events will cause
notifications to be generated. If the list of specifications is
empty, then notifications will be generated for all events for the
specified subject type that the client is entitled to receive.
type: array
items:
$ref: '#/components/schemas/SpecificationDetails'
required:
- name
- active
- subjectType
SpecificationDetails:
description: >-
Specifies criteria to determine whether an event should cause a
notification to be generated.
type: object
properties:
id:
description: >-
Specification id, auto-generated by the system and read-only for the
client
type: string
minLength: 1
maxLength: 255
readOnly: true
example: >-
CNSa91bf379b48a593fd17f07f431bad8fb296796498f4e9982ea134394c1fa4f071556724072
type:
description: >-
The type of item to which the criteria refers. Currently the type
'FIELD' is allowed, which refers to matching a field in the
notification itself
type: string
minLength: 1
maxLength: 255
default: FIELD
example: FIELD
operator:
description: >-
The operator that defines how this specification (criteria)
logically relates to other specifications in the list. The first
specification in the list will have an operator of 'WHERE' and
subsequent specifications will have an 'AND' or 'OR' relationship
with their preceding specification
type: string
minLength: 1
maxLength: 255
default: WHERE
example: WHERE
fieldMapping:
readOnly: true
allOf:
- $ref: '#/components/schemas/FieldMapping'
fieldOperator:
description: >-
The check operation that is to be performed. Currently one of
allowed values are 'EQUALS', 'GREATER_THAN', 'LESS_THAN', 'BETWEEN'
type: string
minLength: 1
maxLength: 255
default: EQUALS
example: EQUALS
expectedContent:
$ref: '#/components/schemas/FieldContent'
children:
description: >-
A list of nested child specifications, used where needed to
implement complex matching logic
type: array
items:
$ref: '#/components/schemas/SpecificationDetails'
required:
- type
- operator
- fieldMappingName
- fieldOperator
- expectedContent
ICCPAuthorizationNotificationContent:
description: >-
The content of the notification, the structure of which depends on the
subject.
type: object
properties:
messageTypeIndicator:
description: >-
Message Type Identifier. Following are the possible values for
messageTypeIndicator: 0110 (Authorization Response), 0120
(Authorization Advice), 0400 (Reversal Request) and 0420 (Reversal
Advice).
type: string
minLength: 4
maxLength: 4
example: '0110'
systemTraceAuditNumber:
description: >-
Systems Trace Audit Number (STAN) is a number a message initiator
assigns to uniquely identify a transaction. This value is derived
from DE 11.
type: string
minLength: 1
maxLength: 255
example: '011174'
financialNetworkCode:
description: >-
Financial network code derived from DE 63, subfield 1 identifies the
specific program or service (for example, the financial network,
financial program, or card program) with which the transaction is
associated.
type: string
example: MCC
banknetReferenceNumber:
description: >-
Banknet reference number derived from DE 63, subfield 2 is generated
by the Authorization Platform for each originating message it
routes. The reference number is guaranteed to be a unique value for
any transaction within the specified financial network on any
processing day.
type: string
example: Q4A91A
transactionAmount:
description: >-
The transaction amount represented in minor units, which are the
smallest units of a currency. The value is determined by the number
of decimal places associated with the currency. Refers to DE 63,
subfield 2.
type: number
example: 7550
transactionCurrencyCode:
description: Currency of the transaction (merchant currency) refers to DE 49.
type: string
example: USD
billingAmount:
description: >-
Cardholder billing amount (DE 6) indicates the transaction amount in
the issuers currency. It is the amount billed to the cardholder in
the cardholder account currency, excluding cardholder billing fees
and is represented in minor units, which are the smallest units of a
currency. The value is determined by the number of decimal places
associated with the currency.
type: number
example: 7550
billingCurrencyCode:
description: >-
The currency code of the cardholder billing defines the currency of
DE 6 (Amount, Cardholder Billing).
type: string
example: USD
responseCode:
description: >-
DE 39 (Response Code) defines the disposition of a previous message
or an action taken as a result of receipt of a previous message.
Response codes also are used to indicate approval or decline of a
transaction. In the event an authorization is declined, the response
code indicates the reason for rejection and may indicate an action
to be taken at the card acceptor (for example, capture card).
type: string
example: '00'
authorizationCode:
description: >-
DE 38 (Authorization ID Response) contains the online authorization
code provided by the issuer on the original authorization response.
It is a transaction response ID code that the authorizing
institution assigns. DE 38 is used to transmit a card issuers
authorization code for Authorization transactions. In general, the
authorization code used in DE 38 may be any combination of
alphanumeric characters.
type: string
example: '502359'
transmissionRawDate:
description: >-
DE 7, subfield 1 (Date) is the date (UTC) that the message was
entered into the Mastercard Network in the format MMDD.
type: string
example: '1103'
transmissionRawTime:
description: >-
DE 7, subfield 2 (Time) is the time (UTC) that the message was
entered into the Mastercard Network in the format HHmmss.
type: string
example: '101611'
settlementDate:
description: >-
Referring to DE 15, the reporting date to which a transaction
applies in the format MMDD. This is the UTC date that the
authorization is processed, not the date on which settlement will
occur.
type: string
example: '0930'
cardHolderTransactionTypeCode:
description: DE 3, subfield 1 describes the specific transaction type.
type: string
example: '00'
posTransactionStatus:
description: >-
DE 61, subfield 7 indicates the purpose or status of the request.
Following are the possible values for posTransactionStatus: 0
(Normal request [original presentment]), 2 (Identity Check Phone
Order), 3 (ATM Installment Inquiry), 4 (Preauthorization
request), 5 (Time Based Payment Authorization RequestBrazil
domestic transactions), 6 (ATC Update), 8 (Account Status Inquiry
Service (ASI)), 9 (Tokenization Request/Notification).
type: string
example: '0'
traceId:
description: >-
Contains data from DE 63 (Network Data), subfield 1 (Financial
Network Code) and subfield 2 (Banknet Reference Number) and DE 15
(Date, Settlement) that is in the original Authorization Request
Response/0110 message.
type: string
example: 'MCC9999991231 '
merchant:
description: Merchant details
type: object
properties:
merchantId:
description: >-
DE 42 (Card Acceptor ID Code) identifies the card acceptor that
defines the point of the transaction in both local and
interchange environments. DE 42 is used as a merchant ID to
uniquely identify the merchant in a POS transaction.
type: string
example: '497520000000000'
categoryCode:
description: >-
DE 18 (Merchant Type) is the classification (card acceptor
business code/merchant category code [MCC]) of the merchants
type of business or service.
type: string
example: '5542'
name:
description: >-
DE 43 (Acceptor Name and Location), subfield 1 (Acceptor Name)
contains the merchant name against the merchant id. Merchant
name is the merchant doing business as name.
type: string
example: JASPERHITECH
city:
description: >-
ContainsDE 43 (Acceptor Name and Location), subfield 3 (Acceptor
City) indicates the city of the merchant.
type: string
example: Jasper
stateOrCountryCode:
description: >-
DE 43, subfield 5 contains the ISO 3166-1 country code of the
merchant.
type: string
example: TN
realPaymentCard:
description: Real Payment Card Details
type: object
properties:
number:
description: >-
DE 2 (Primary Account Number [PAN]) is a series of digits
(represented masked) used to identify a customer account or
relationship.
type: string
example: '************0112'
expiryMonth:
description: >-
DE 14 (Date, Expiration) specifies the year and month after
which an issuer assigns a cardholders card to be expired .
type: string
example: '12'
expiryYear:
description: >-
DE 14 (Year, Expiration) specifies the year and month after
which an issuer assigns a cardholders card to be expired .
type: string
example: '24'
virtualPaymentCard:
description: Virtual Payment Card Details
type: object
properties:
number:
description: >-
DE 48, subelement 33, subfield 2 (Account Number) indicates the
PAN (represented masked) mapping account number.
type: string
example: '************6213'
expiryMonth:
description: >-
DE 48, subelement 33, subfield 3 (Expiration Date) indicates the
expiration date of the PAN mapping account in format YYMM.
type: string
example: '09'
expiryYear:
description: >-
DE 48, subelement 33, subfield 3 (Expiration Date) indicates the
expiration date of the PAN mapping account in format YYMM.
type: string
example: '27'
inControlOnBehalfServiceResult:
description: >-
In Control Service Result details, derived from DE 48 (Additional
DataPrivate Use). DE 48 is reserved for private organizations to
define data unique to specific networks or specific programs and
services. DE 48 provides other supplemental data in a message when a
specific ISO-designated data element is not available. It is a
free-format, variable-length data element that may be used for
multiple purposes.
type: object
properties:
rcnServiceResultCode:
description: >-
In Control RCN Spend Control Service (generally will be null).
DE 48, subelement 71 (On-behalf [OB] Services) notifies the
issuer of the On-behalf Service performed on the transaction and
the results. Subelement 71 will support up to ten services for a
transaction.
type: string
example: ''
vcnServiceResultCode:
description: >-
VCN Service Result Code. DE 48, subelement 71 (On-behalf [OB]
Services) notifies the issuer of the On-behalf Service performed
on the transaction and the results. Subelement 71 will support
up to ten services for a transaction.
type: string
example: V
originalMessage:
description: >-
Original message identifying information, in the case of a follow-up
message. DE 90 (Original Data Elements) is the data elements in the
original message, intended to identify a transaction for correction
or reversal.
type: object
properties:
messageTypeIndicator:
description: >-
DE 90, subfield 1 (Original Message Type Identifier) indicates
the Message Type Identifier (MTI) of the original message.
type: string
minLength: 4
maxLength: 4
example: '0110'
systemTraceAuditNumber:
description: >-
DE 90, subfield 2 (Original DE 11 [Systems Trace Audit Number])
indicates the Systems Trace Audit Number (STAN) that was in DE
11 of the original message.
type: string
example: '11174'
transmissionRawDateTime:
description: >-
DE 90, subfield 3 (Original DE 7 [Transmission Date and Time])
indicates the Transmission Date and Time that was in DE 7 of the
original message.
type: string
example: '1029112800'
advice:
description: Advice information (valid for advice messages only, MTI=04xx).
type: object
properties:
reasonCode:
description: >-
DE 60, subfield 1 (Advice Reason Code) indicates to the receiver
of an Advice message the specific reason for the transmission of
the Advice message.
type: string
example: '650'
replacementAmounts:
description: >-
Replacement amounts, applicable for reversals, indicate the new
values that replace the amounts in the original transaction. These
amounts are represented in minor units, which are the smallest unit
of a currency and vary depending on the number of decimal places
used by the currency.
type: object
properties:
transactionAmount:
description: >-
DE 95, subfield 1 (Actual Amount, Transaction) indicates the
actual transaction amount. The amount for the replacement
transaction represented in minor units, which are the smallest
units of a currency. The value is determined by the number of
decimal places associated with the currency.
type: number
example: 1200
settlementAmount:
description: >-
DE 95, subfield 2 (Actual Amount, Settlement) indicates the
actual settlement amount in the settlement currency. The amount
# --- truncated at 32 KB (179 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mastercard/refs/heads/main/openapi/mastercard-commercial-event-notifications-openapi.yml