Mastercard Merchants API is one of 172 APIs that Mastercard publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Merchants. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, code examples, a changelog, a support channel, and a getting-started guide.
This API exposes
8 operations
across 7 paths,
and defines 117 schemas.
It is described by OpenAPI 3.2.0, at version 1.0.
Requests are made against 8 base URLs: https://sandbox.api.mastercard.com/carbon, https://api.mastercard.com/carbon, https://api.ethocaweb.com/ethoca/merchant-self-services, https://sandbox.api.ethocaweb.com/ethoca/merchant-self-services, https://sandbox.api.mastercard.com/installments, https://api.mastercard.com/installments, https://api.mastercard.com/locations/merchants, https://sandbox.api.mastercard.com/locations/merchants.
The identity and technical contract details declared by the specification.
X-MC-Correlation-ID
string
Category
object
User understandable information about an MCC categorization.
4 properties
SupportedMerchantCategories
array
List of supported merchant categories.
MerchantCategory
object
Information for a supported merchant category.
2 properties
2 required
CrmResource
Customer Relationship Management Response
Merchant
Base merchant request schema
3 required
CountryCode
stringnull
The [ISO 3166-1](https://www.iso.org/obp/ui/search) alpha-3 compliant country code.
FirstPartyTrustEnrollmentType
string
Type of First Party Trust Enrollment
SubMerchant
Schema for a sub-merchant
Errors
object
Errors object
1 property
1 required
MerchantStatus
string
Merchant Status must be one of - ACTIVATED, DEACTIVATED
MerchantType
string
Merchant Type must be one of - PARTNER, ACQUIRER, SUBMERCHANT
CardAcceptor
string
Merchant Card Acceptor
FirstName
stringnull
The individual's first name
Address
Address entity associated to merchant's location and legal address.
1 required
LocationWithoutCardAcceptors
object
1 required
FirstPartyTrustEnrollment
object
1 property
1 required
AlertsOrgProfile
object
Details of organization profiles containing member name, id and type
5 properties
SanctionScreening
object
8 properties
3 required
BaseMerchant
object
Base merchant model schema
8 properties
4 required
ResourceId
stringnull
Unique identifier of resource
UserId
string
The user id of the submitter/technical contact.
ShortEmail
stringnull
Email address
MerchantGuid
string
Consumer Clarity internal merchant's GUID
CardAcceptors
arraynull
List of merchant card acceptors
SubMerchantResource
Sub-Merchant Response
AlertsSubOrgProfile
object
Sub organization member details containing member name, id and type
4 properties
CardTypesResource
array
A list of all of the card types that are accepted as a form of payment.
SearchFieldResource
object
Merchant Api Search Field
3 properties
Location
object
2 required
SubMerchantIdentifier
string
The alphanumeric ID of the sub-merchant associated with the purchase details. Required for channel partner.
PercentOwnership
stringnull
Percent Ownership.
SearchFieldsResource
arraynull
Search Field
MerchantResource
Base merchant response schema
3 required
Error
object
Error object
5 properties
SecondName
stringnull
The individual's second name
PrimaryContact
object
Primary contact details of the merchant
5 properties
4 required
LegalAddress
Legal address of the merchant.
6 required
LegalEntity
object
Legal entity owning the merchant.
5 properties
BeneficialOwner
object
Individual owning the merchant.
7 properties
ValidationStatus
objectnull
Status of created Merchant
2 properties
SearchField
object
Schema for a Search Field
3 properties
1 required
MerchantName
string
Merchant's partial or full name.
TermsConditionsConsent
object
8 properties
8 required
Locale
object
Merchant Locale details
3 properties
3 required
EntityName
stringnull
The entity's legal or business name.
Etag
string
Etag is a response header which is an identifier for a specific version of a resource.
SearchFields
arraynull
SearchFields is an array of SearchField objects. The following validations apply: If the searchFields array contains both TRANSACTIONAMOUNT and TRANSACTIONCURR…
Email
stringnull
Email address
Crm
objectnull
Customer Relationship Management
3 properties
CardTypes
array
A list of all of the card types that are accepted as a form of payment.
ErrorResponse
object
Error Response object
1 property
1 required
LastName
stringnull
The individual's last name
AlertsMerchantMemberId
string
Internal Universally Unique Identifier (UUID) which uniquely identifies the merchants
ShortAddress
object
Address.
6 properties
FirstPartyTrustEnrollmentResource
object
1 property
1 required
SalesforceAccountNumber
string
Unique identifier for a merchant in sales force system.
MidDetailsPage
object
Contains mids of a merchant.
7 properties
5 required
MerchantParticipations
array
List of merchant participation reference objects.
maid
string
Mastercard Assigned ID (MAID) as specified in Customer Interface Specification for ISO data element DE48 SE32.
countryCode
string
Legally registered country code of merchant. Refer to (https://www.iso.org/obp/ui/search) for ISO 3166 alpha 3 code values.
duns
string
A unique identifier assigned by Dun and Bradstreet is used to identify a business.
submitterICA
string
ICA(s) of partner(s) institution(s) who submitted this merchant participation.
searchMaidType
string
Flag to identify provided MAID type. This is mandatory for participation requests with MAID.
limit
integer
The number of items you asked the list to be limited to.
Merchant_2
object
Merchant object
21 properties
maids
array
Mastercard Assigned ID (MAID). Adding a MAID based merchant object requires the mandatory provision of maids, while updating a merchant does not necessitate it.
Errors_2
object
Error object which returns the list of Error objects.
1 property
1 required
walletAcceptance
string
States whether the merchant accepts the wallet or not.
walletMerchantId
string
One or more wallet merchant IDs separated by the pipe symbol.
websiteUrl
string
The URL of the merchant website.
Address_2
object
The address of the merchant.
6 properties
requestEndpoint
string
original request endpoint
MerchantSearchParameters
object
Parameters to search merchant objects. At least one parameter is required in the request.
5 properties
acquirerICA
string
ICA of acquirer which will be part of auth transaction. Insert leading zeros to ensure that the acquirerICA is either 6, 9, or 11 characters in length.
errorReason
string
Reason for error.
ErrorWrapper
object
The error response object which gets returned in case of any error.
1 property
1 required
walletId
integer
Indicates the wallet, 1 for ApplePay, 2 for GooglePay, and 3 for SamsungPay.
acceptorId
string
Mastercard assigned ID.
MerchantMidSearchParameters
object
Parameters to search mid for a given merchant.
5 properties
3 required
wallets
array
Merchant wallets.
requestId
integer
The request ID is obtained by calling POST /merchants/participations API.
MerchantSearch
object
Merchant object
16 properties
mids
array
Merchant IDs assigned by the acquirer.
dbaName
string
Trade name used by merchant to conduct business and is known to the consumer.
merchantParticipationStatus
string
Status of request
wallet
object
Contains merchant wallet information.
3 properties
2 required
errors
array
Error object which contains a list of error objects.
1 required
MerchantSearches
array
List of Merchant objects
offset
integer
The number of items you asked for at the start of the list to be offset from.
total
integer
The total number of items in the collection.
mid
string
Merchant ID assigned by the acquirer.
MerchantParticipation
object
Merchant participation reference
14 properties
3 required
Error_2
object
Error object which contains details about the Error.
5 properties
4 required
count
integer
The number of items in this batch (the size of the item array).
status
string
Status of request
maidType
string
Flag to identify provided MAID type. This is mandatory for participation requests with MAID.
MidDetails
array
API will return a list of wallet name, wallet acceptance, and wallet merchant id.
optIn
string
Merchant opt-in or opt-out preference for non-merchant negotiated product codes, such as, SPP, SPS, SBJ, and SBK or GCS.
MidDetail
object
Contains mid with status.
3 properties
2 required
httpErrorStatusCode
integer
HTTP error code of original POST /merchants/participations API.
nonMerchantNegotiatedParticipation
string
Merchant opt-in or opt-out preference for non-merchant negotiated product codes, such as, SPP, SPS, SBJ, and SBK.
merchantLegalName
string
Legally registered name of the merchant.
merchantGroup
string
Merchant Group. An identifier used to determine the merchant category type to qualify for the right MAID (MAID is assigned internally by Mastercard). It is imp…
Merchants
array
List of Merchant objects
acceptorIds
array
MAID IDs assigned by Mastercard.
Merchants_2
object
5 properties
ErrorResponse_2
object
Only returned in the event of an error condition
1 property
1 required
Error_3
object
Details of the error condition such as the source of the error, reason code for the error, if the error is recoverable, and details about the error
5 properties
4 required
Merchant_3
object
Merchant detail information
30 properties
Errors_3
object
Only returned in the event of an error condition
1 property
1 required
MerchantSearch_2
object
Merchant Search Request Info
11 properties
The full machine-readable OpenAPI contract behind this narrative.
Other APIs Mastercard publishes across the network.
