openapi: 3.0.3
info:
title: Mastercard Ethoca Consumer Clarity for Merchant Transactions
description: >-
Ethoca's Consumer Clarity for Merchant Transactions brokers order
information between an organization and an issuer or an organization and
their customer. As a result, issuers are connected to merchant order and
account history details in real time, which helps reduce disputes and
friendly fraud.
termsOfService: https://www.ethocaweb.com/consumerclarity/assets/static/termsOfUse.html
contact:
name: Consumer Clarity Support
email: [email protected]
license:
name: Copyright (c) 2023 Ethoca Limited. All Rights Reserved.
url: https://www.ethoca.com/terms-of-use
version: 4.2.0
externalDocs:
description: Learn more about the Consumer Clarity Merchant API
url: >-
https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/
servers:
- url: https://sandbox.api.ethocaweb.com/
description: Ethoca Sandbox Test url.
- url: https://mtf.api.ethocaweb.com/
description: Ethoca Mtf url.
- url: https://api.ethocaweb.com/
description: Ethoca prod url.
tags:
- name: Transactions
description: transactions controller post end point
- name: HealthChecks
description: Health Check controller get end point
paths:
/api/orders:
post:
tags:
- Apis
- Orders
- Transactions
summary: Searches order details based on the search criteria
description: Search for orders based on transaction fields that you currently support
operationId: getTransactionDetails
parameters:
- $ref: '#/components/parameters/eth_date'
- $ref: '#/components/parameters/authorization'
requestBody:
$ref: '#/components/requestBodies/OrderApi'
responses:
'200':
$ref: '#/components/responses/OrderApiAcknowledgement'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'405':
$ref: '#/components/responses/MethodNotAllowed'
/api/orders/healthchecks:
get:
tags:
- Apis
- Orders
- Health Checks
operationId: getHealthDetails
description: Health or Echo or Heartbeat endpoint ensuring that the API is running
summary: Health endpoint to ensure confirm connectivity to transaction API
responses:
'200':
$ref: '#/components/responses/HealthCheckResponse'
components:
parameters:
eth_date:
name: X-Eth-Date
in: header
description: Date time in UTC format when request was sent to the Merchant API
required: false
example: '2017-06-19T13:18:16Z'
schema:
type: string
minLength: 10
maxLength: 25
authorization:
name: Authorization
in: header
description: >-
Every request sent to the Merchant API must be authorized. To facilitate
authorization, every request must contain a time stamped, symmetric-key
based HMAC signature header. The HMAC signature ensures that the API
secret key and key ID are exchanged securely between Ethoca and the
merchant out-of-band. The entropy of the issued API key must be no less
than 128 bits. ETHOCA-SHA1 KeyRef=<API
Key_ID>,Signature=<base64UrlSafe_hmac_signature>
required: true
example: 1c723b9ddda75f6348cd939c5a3140f58e58c70d
schema:
type: string
requestBodies:
OrderApi:
description: The request object Merchant API expects
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderApi'
responses:
HealthCheckResponse:
description: |-
The code indicates the response.
- OK = The API is up and running
- failure = The API is not running
content:
application/json:
schema:
$ref: '#/components/schemas/HealthCheckResponse'
OrderApiAcknowledgement:
description: The response object Merchant API returns
content:
application/json:
schema:
$ref: '#/components/schemas/OrderApiAcknowledgement'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
UnauthorizedExample:
$ref: '#/components/examples/UnauthorizedExample'
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
BadRequestExample:
$ref: '#/components/examples/BadRequestExample'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
ForbiddenExample:
$ref: '#/components/examples/ForbiddenExample'
MethodNotAllowed:
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
MethodNotAllowedExample:
$ref: '#/components/examples/MethodNotAllowedExample'
examples:
BadRequestExample:
value:
Errors:
Error:
- Source: Service
ReasonCode: Missing attributes
Description: request is missing mandatory attributes
Recoverable: false
Details: request is missing mandatory attributes
ForbiddenExample:
value:
Errors:
Error:
- Source: Service
ReasonCode: Forbidden
Description: request is not authorized
Recoverable: false
Details: request is not authorized
MethodNotAllowedExample:
value:
Errors:
Error:
- Source: Service
ReasonCode: Method not allowed
Description: Method is not allowed
Recoverable: false
Details: Method is not allowed
UnauthorizedExample:
value:
Errors:
Error:
- Source: Service
ReasonCode: Unauthorized
Description: request is not authenticated
Recoverable: false
Details: request is not authenticated
schemas:
PaymentType:
title: Transaction Card Type
type: string
minLength: 2
maxLength: 8
pattern: ^[A-Za-z0-9]{2,8}$
description: |
The card brand or network as provided by the issuer
Allowed values:
- AMEX
- DISCOVER
- MC
- VISA
Definition of allowed values:
- AMEX: American Express
- DISCOVER: Discover
- MC: Mastercard
- VISA: Visa
example: MC
CardLastFour:
title: Card Last Four
minLength: 4
maxLength: 4
type: string
pattern: ^\d{4}$
description: Last four characters of the card used in the transaction
example: '1234'
CurrencyCode:
minLength: 3
maxLength: 3
type: string
description: >-
Currency code applied to order. This currency will apply to all
amount/price fields throughout entire payload. Must be three character
ISO currency code (https://en.wikipedia.org/wiki/ISO_4217#Active_codes)
example: USD
HealthCheckResponse:
type: string
maxLength: 7
minLength: 2
description: |-
The code indicates if the API is up or not
- OK = The API is up and running
- failure = The API is down
example: OK
OrderApi:
type: object
required:
- requestReference
- searchCriteria
properties:
requestReference:
$ref: '#/components/schemas/RequestReference'
searchCriteria:
$ref: '#/components/schemas/SearchCriteria'
RequestReference:
title: Request References
description: Request Information details, such as tracking details
type: object
properties:
originatorChannel:
title: Original Requester Channel
type: string
minLength: 1
maxLength: 20
description: |
Example value :
- DIGITAL
- CALL_CENTRE
- FIRST_PARTY_TRUST
example: DIGITAL
originatorId:
title: Requester ID
type: string
minLength: 1
maxLength: 100
description: Hashed Requesters/Aggregator Issuer ID
example: 420f0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b35304255715f
sourceId:
title: Source ID
type: string
minLength: 1
maxLength: 100
description: Aggregator's Actual Issuer ID Hashed
example: 66666688ggg0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b324gf
originatorDescription:
title: Requester Description
type: string
minLength: 1
maxLength: 100
description: Description about the issuer
example: Test Issuer
correlationId:
title: Correlation Id
description: Correlation ID between Ethoca and merchant tracking
type: string
minLength: 1
maxLength: 201
example: zebj8evpeo
locale:
type: string
minLength: 5
maxLength: 5
description: >
The locale, or language-country combination, associated with the
caller of the service in ISO 639-1 and ISO-3166-1 format
- 'en-US'
- 'en-CA'
- 'en-GB'
- 'es-ES'
- 'es-MX'
- 'es-US'
- 'fr-CA'
- 'fr-FR'
- 'pt-BR'
- 'pt-PT'
- 'he-IL'
example: en-US
SearchCriteria:
title: Search Criteria for order lookup
description: Parameters used to look up order
type: object
properties:
paymentType:
title: Transaction Card Type
type: string
minLength: 2
maxLength: 8
description: |
The card brand or network as provided by the issuer
Allowed values:
- AMEX
- DISCOVER
- MC
- VISA
Definition of allowed values:
- AMEX: American Express
- DISCOVER: Discover
- MC: Mastercard
- VISA: Visa
example: MC
transactionIdentifierType:
type: string
minLength: 1
maxLength: 20
description: >
Payment type-specific transaction identifier type associated with
the value specified in transactionIdentifierValue.
Current values:
- BANKNET_REF_NUM
- INVOICE_REF_NUM
Definition of current values:
- Mastercard: DE 63, Subfield 2: Banknet Reference Number
- American Express: TAB Field 26: Invoice/Reference Number
example: BANKNET_REF_NUM
transactionIdentifierValue:
title: Transaction Identifier Value
type: string
minLength: 1
maxLength: 30
description: >-
Transaction identifier value associated with the type specified in
transactionIdentifierType
example: T123456
acquirerReferenceNumber:
title: Acquirer Reference Number (ARN)
minLength: 23
maxLength: 23
type: string
description: Acquirer Reference Number of the transaction
example: '12345678901234567890123'
transactionDateTime:
title: Transaction Date and/or Time
minLength: 10
maxLength: 25
type: string
description: >
Date, time, and time zone of the authorization of the transaction
(for example, "2020-06-18T17:11:05-05:00"), OR Date and time of the
transaction in Coordinated Universal Time (UTC) (for example,
"2020-06-18T17:11:05+00:00"), OR If time or time zone is unknown,
then date of the transaction (for example, "2020-06-18"). ISO 8601
format. This is the date and time of the authorization of the
transaction, not the date and time of the settlement of the
transaction.
example: '2020-06-18T17:11:05-05:00'
cardFirstSix:
title: Card First Six
minLength: 6
maxLength: 6
type: string
pattern: ^\d{6}$
description: First six characters of the card used in the transaction
example: '123456'
cardLastFour:
title: Card Last Four
minLength: 4
maxLength: 4
type: string
pattern: ^\d{4}$
description: Last four characters of the card used in the transaction
example: '1234'
issuerAuthorizationCode:
title: Issuer Authorization Code
maxLength: 6
minLength: 6
type: string
description: Issuer authorization code for the transaction
example: '123456'
transactionAmount:
title: Transaction Value
minLength: 1
maxLength: 12
type: string
description: >
Total amount value associated with the transaction.
<br/><br/>Decimal point period is expected to denote separation of
the fractional suffix
from the rest of the amount, if applicable for the currency. Decimal
point period must not be the first character. Examples:<br>- USD
exponent
is 2, so $250 USD value should be represented as 250.00, 34¢
USD
value should be represented as 0.34<br>- JPY exponent is 0, so
¥250
JPY value should be represented as 250
example: '250.35'
transactionCurrencyCode:
title: Transaction Currency Code
maxLength: 3
minLength: 3
type: string
description: >-
Alphabetic currency code associated with the value in ISO 4217
format
example: USD
merchantId:
title: Merchant Identifier
description: >-
The alphanumeric ID of the sub-merchant associated with the purchase
details. Required for channel partner
type: string
minLength: 1
maxLength: 100
example: GHF5F67DFSD468GJJXH78
cardAcceptorId:
title: Card Acceptor Id
description: >-
An identifier for the store location or transaction point. Also
known as Card Acceptor ID and it is assigned by the merchant
acquirer.
type: string
minLength: 1
maxLength: 15
example: 12345671234567
cardAcceptorName:
title: Card Acceptor Name
description: >-
Merchant 'doing business as' name, or website name<br>- Mastercard:
DE 43, Subfield 1; Card Acceptor Name<br>- Visa: TC 05, positions
92-116; Merchant Name
type: string
minLength: 1
maxLength: 50
example: MicrosoftXBox
cardAcceptorLocation:
title: Card Acceptor Location
description: >-
Merchant city, telephone number, email address, or URL<br>-
Mastercard: DE 43, Subfield 3: Card Acceptor City<br>- Visa: TC 05,
positions 117-129: Merchant City
type: string
minLength: 1
maxLength: 50
example: Austin
cardAcceptorRegionCode:
title: CardAcceptor Region Code
description: >-
The abbreviation for a subdivision (State, Province, Parish,
Territory, etc.) provided in the ISO 639-1 and ISO-3166-2 format
type: string
minLength: 1
maxLength: 3
pattern: ^[A-Za-z0-9]*$
example: TX
cardAcceptorCountryCode:
title: CardAcceptor Country Code
description: >-
The Country Code associated with the cardAcceptorNames location
data.
type: string
minLength: 2
maxLength: 3
example: US
AccountProfile:
type: object
properties:
email:
type: string
minLength: 1
maxLength: 200
pattern: ^[A-Za-z0-9]{1,200}$
description: Customer's email address for communication
example: [email protected]
phone:
minLength: 3
maxLength: 30
type: string
description: >-
Primary phone number on the account; include the country code and
any applicable separators
example: +1-234-567-8901
userIdName:
minLength: 1
maxLength: 65
type: string
description: >-
Merchant unique identifier for customer (if email address is used as
the User ID, this field should still be populated)
example: testuser123
customerNameDuration:
type: integer
minimum: 0
maximum: 99999
description: >-
Duration from customer registration to purchase date (in full
months). If less than 1 full month or 30 days, then use zero.
format: int32
example: 1
accountCreationDateTime:
minLength: 20
maxLength: 20
type: string
format: date-time
description: >-
Date & Time the account was created or opened. (String based date
time representation in International Date Time Format (ISO 8601) in
UTC - yyyy-mm-ddThh:mm:ssZ)
example: '2017-06-19T13:18:18Z'
accountLastUsageDateTime:
type: string
description: >-
Date of the last access or usage or transaction for this account
(note that this may be different from lastLoginDate if customer uses
guest checkout, etc.)(String based date time representation in
International Date Time Format (ISO 8601) in UTC -
yyyy-mm-ddThh:mm:ssZ)
minLength: 20
maxLength: 20
format: date-time
example: '2017-06-19T13:18:18Z'
totalSpendAmount:
type: string
minLength: 1
maxLength: 12
description: >-
Total amount spent on this account since it was created. Maximum
number of fractional digits supported is 2.
example: '250.35'
cardholderVisitCountPrior:
type: integer
minimum: 0
maximum: 99999
description: Number of visits from cardholder prior to purchase transaction date
format: int32
example: 7
cardholderVisitCountSince:
type: integer
minimum: 0
maximum: 99999
description: >-
Number of visits from cardholder since purchase date to Purchase
Inquiry transaction date
format: int32
example: 9
monthsSinceFirstPurchase:
type: integer
minimum: 0
maximum: 99999
description: Months since the first purchase made by account holder and device
format: int32
example: 2
countOfPurchasesSinceRegistration:
type: integer
minimum: 0
maximum: 99999
description: Number of purchases since account and device were registered
format: int32
example: 90
countOfDisputedPurchasesSinceRegistration:
type: integer
minimum: 0
maximum: 99999
description: >-
Number of disputed purchases since account and device were
registered
format: int32
example: 9
additionalRelatedDisputes:
type: integer
minimum: 0
maximum: 99999
description: Number of additional related disputes
format: int32
example: 3
disputeHistoryMatch:
type: boolean
description: >-
Indicates whether this cardholder has disputed orders with this
merchant in the past 6 months
example: true
lastLoginDateTime:
minLength: 20
maxLength: 20
type: string
description: >-
Date of last login to customer account (string based date/time
representation in International Date Time Format (ISO 8601) in UTC -
yyyy-mm-ddThh:mm:ssZ)
format: date-time
example: '2017-06-19T13:18:18Z'
membershipSubscriptionType:
minLength: 1
maxLength: 75
type: string
description: >-
Additional information about type of membership or subscription.
Example: level in membership, annual subscription, etc.
example: Gold Membership
goodOrders90DaysOld:
type: boolean
description: >-
Indicates whether the Device ID and bank card match what was used
with the current disputed transaction and if there are previous
orders that are at least 90 days old
example: true
accountPrimaryDeviceId:
minLength: 1
maxLength: 40
type: string
description: Primary Device ID
example: JCKJ78UY666L90
accountPrimaryDeviceName:
minLength: 1
maxLength: 20
type: string
description: Primary Device Name
example: Mark's iPad
accountAuthenticationConducted:
minLength: 1
maxLength: 50
type: string
description: >-
Type of authentication conducted (2.F1) (Password provided and
authenticated, any levels in between?, guest checkout)
example: Password Authentication
passwordLastUpdatedDateTime:
description: >-
Password last updated date and time. (String based date/time
representation in International Date Time Format (ISO 8601) in UTC -
yyyy-mm-ddThh:mm:ssZ)
type: string
minLength: 20
maxLength: 20
format: date-time
example: '2017-06-19T13:18:18Z'
passwordAuthenticationDateTime:
type: string
description: >-
Password Authentication date and time (String based date/time
representation in International Date Time Format (ISO 8601) in UTC -
yyyy-mm-ddThh:mm:ssZ)
format: date-time
minLength: 20
maxLength: 20
example: '2017-06-19T13:18:18Z'
emailAccountHistory:
type: integer
minimum: 0
maximum: 99999
description: >-
Duration of email account since first registered (by initial
purchase - in full months). If less than 1 full month or 30 days,
then use zero
format: int32
example: 9
accountCreationIpAddress:
minLength: 1
maxLength: 45
type: string
description: IP Address for device used when creating the account
example: 127.0.0.1
name:
$ref: '#/components/schemas/NameType'
accountShippingAddress:
$ref: '#/components/schemas/AddressType'
accountBillingAddress:
$ref: '#/components/schemas/AddressType'
consequence:
$ref: '#/components/schemas/Consequence'
historicOrders:
type: array
description: List of the historic orders for this account
items:
$ref: '#/components/schemas/HistoricOrder'
AddressType:
type: object
properties:
line1:
minLength: 1
maxLength: 100
type: string
description: The street detail for the address
example: 223 Blythwood Rd
line2:
minLength: 1
maxLength: 100
type: string
description: The secondary street detail for the address
example: Main floor
line3:
minLength: 1
maxLength: 100
type: string
description: The tertiary street detail for the address
example: Main floor
city:
minLength: 1
maxLength: 100
type: string
description: The city detail for the address
example: Toronto
countrySubdivision:
minLength: 1
maxLength: 80
type: string
description: The state/province detail for the address
example: Ontario
postalCode:
minLength: 1
maxLength: 10
type: string
description: The zip/postal detail for the address
example: M4N1A7
country:
minLength: 1
maxLength: 80
type: string
description: The country detail for the address
example: Canada
latitude:
minLength: 1
maxLength: 11
type: string
description: The latitude coordinate of the address
example: '30.286254'
longitude:
minLength: 1
maxLength: 11
type: string
description: The longitude coordinate of the address
example: '-97.739378'
AirTravel:
type: object
description: List of air travel reservations
required:
- id
- passengerNameRecord
- designatorCode
- flightNumber
- originAirportCode
- destinationAirportCode
properties:
id:
minLength: 1
maxLength: 100
type: string
description: >-
AirTravel unique identifier (merchant generated sequence-based ID
for each reservation, for example 1, 2, 3, 4...)
example: 1
passengerNameRecord:
minLength: 1
maxLength: 6
type: string
description: The Passenger Name Record or Record Locator for the reservation
example: XY8UI9
designatorCode:
minLength: 2
maxLength: 2
type: string
description: The two digit IATA airline code
example: AI
airlineName:
type: string
minLength: 1
maxLength: 100
description: The full name of the airline
example: Paradise Island Airlines
flightNumber:
minLength: 1
maxLength: 10
type: string
description: >-
The flight number assigned to that travel leg, not the full flight
designator
example: '8788'
flightPrice:
minLength: 1
maxLength: 12
type: string
description: The cost of a single flight on the itinerary
example: '245.99'
originAirportCode:
minLength: 3
maxLength: 3
type: string
description: The 3 digit IATA code for the originating airport
example: LAX
originAirportName:
type: string
minLength: 1
maxLength: 200
description: The full name of the originating airport
example: Metropolis International Airport
destinationAirportCode:
minLength: 3
maxLength: 3
type: string
description: The 3 digit IATA code for the destination airport
example: ISL
destinationAirportName:
type: string
minLength: 1
maxLength: 200
description: The full name of the destination airport
example: Smallville Regional Airport
scheduledDepartureDateTime:
type: string
minLength: 20
maxLength: 20
description: >-
The scheduled time of departure (String based date/time
representation in International Date Time Format (ISO 8601) in UTC -
yyyy-mm-ddThh:mm:ssZ)
format: date-time
example: '2017-06-19T13:18:18Z'
departureTimezone:
type: string
minLength: 1
maxLength: 50
description: The timezone of the departure as it appears in the TZ database
example: Europe/Paris
actualDepartureDateTime:
minLength: 20
maxLength: 20
type: string
description: >-
The actual time of departure (String based date/time representation
in International Date Time Format (ISO 8601) in UTC -
yyyy-mm-ddThh:mm:ssZ)
format: date-time
example: '2017-06-19T13:18:18Z'
scheduledArrivalDateTime:
type: string
minLength: 20
maxLength: 20
description: >-
The scheduled time of arrival (String based date/time representation
in International Date Time Format (ISO 8601) in UTC -
yyyy-mm-ddThh:mm:ssZ)
format: date-time
example: '2017-06-19T13:18:18Z'
arrivalTimezone:
type: string
minLength: 1
maxLength: 50
description: The timezone of the arrival as it appears in the TZ database
example: Europe/Istanbul
actualArrivalDateTime:
minLength: 20
maxLength: 20
type: string
description: >-
The actual time of arrival (String based date/time representation in
International Date Time Format (ISO 8601) in UTC -
yyyy-mm-ddThh:mm:ssZ)
format: date-time
example: '2017-06-19T13:18:18Z'
fareClass:
minLength: 1
maxLength: 25
type: string
description: The type of fare the passenger paid (such as First Class or Economy)
example: Economy
flightStatus:
type: string
minLength: 7
maxLength: 11
description: |
The status of the flight
Allowed values:
- Arrived
- Cancelled
- Delayed
- Departed
- Diverted
- En_Route
- Past_Flight
- Scheduled
example: Arrived
mealInfo:
minLength: 1
maxLength: 50
type: string
description: The information about the meal that was requested/available
example: Available
specialRequest:
minLength: 1
maxLength: 500
type: string
description: >-
Any special requests or instructions for the flight (such as lap
child, wheelchair, or unaccompanied minor)
example: Wheelchair Requested.
passengers:
type: array
description: The list of passengers flying on this particular flight
items:
$ref: '#/components/schemas/Passenger'
Consequence:
type: object
properties:
consequenceStatus:
type: boolean
description: >-
Indicates whether there is a consequence/merchant action for this
account/transaction if it is disputed
example: true
consequence:
minLength: 1
maxLength: 500
type: string
description: >-
Free form text displayed to issuer that can be shared verbatim with
the cardholder. Can be specific to customer or generated in real
time based on other aspects of order
example: No Change/Cancellation is Allowed.
CreditReimbursement:
type: object
description: List of credits for the order
required:
- id
- creditReimbursementDateTime
properties:
id:
minLength: 1
maxLength: 100
type: string
description: >-
Credit Reimbursement Object ID (merchant generated sequence based ID
for each credit, for example 1, 2,
# --- truncated at 32 KB (108 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mastercard/refs/heads/main/openapi/mastercard-ethoca-consumer-clarity-for-merchant-transactions-openapi.yml