Mastercard States API

swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening States API
  description: This service is provided on behalf of the Mastercard Remote Payment and Presentment (RPPS) Bill Payment Processing Network, which supports consumer to business "push" bill payments (i.e. those which are not funded by debit/credit card transactions) in the U.S.
  version: '1.0'
  x-artifactId: billpay-api
  contact:
    name: Bill Pay Development Support
    email: Bill_Pay_Development_Support@mastercard.com
host: sandbox.api.mastercard.com
basePath: /billpayAPI/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: States
paths:
  /fraud-states:
    put:
      tags:
      - States
      operationId: fraudState
      description: This endpoint allows the initiator to delete an existing fraud record or confirm a suspended fraud record for both Mastercard and Issuer built transactions. Operation type FDD will delete existing fraud records from FLD, irrespective of the fraud state i.e., success / rejected / suspended. And operation type FDE will confirm an existing fraud record which was suspended due to reasons such as potential duplicates, billing variance, suspicious amounts, etc.
      summary: Delete an Existing Fraud Record or Confirm a Suspended Fraud Record for Both Mastercard and Issuer Built Transactions.
      requestBody:
        $ref: '#/components/requestBodies/FraudStateRequest'
      responses:
        '200':
          $ref: '#/components/responses/FraudStateChanged'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitExceededError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sub-merchants/{guid}/states:
    parameters:
    - $ref: '#/components/parameters/UserIdParam'
    - $ref: '#/components/parameters/SubmitterFirstNameParam'
    - $ref: '#/components/parameters/SubmitterLastNameParam'
    - $ref: '#/components/parameters/MerchantGuidParam'
    put:
      tags:
      - States
      summary: Mastercard Activate/deactivate a Sub-merchant.
      description: "Returns 204 if merchant is activated/deactivated successfully. It takes a state attribute with two possible values:\n\n  - INACTIVE\n    - For LIVE and LOCKED_FOR_EDIT merchants, this endpoint changes the merchant to INACTIVE status.\n    - For CONFIGURATION merchants, it physically deletes the merchant, rather than deactivating it.\n\n  - ACTIVE\n    - Reactivates an INACTIVE merchant by placing it in CONFIGURATION status. From there, the flow follows the onboarding process where the merchant is in CONFIGURATION status and its attributes\nare available for editing."
      operationId: changeSubMerchantState
      requestBody:
        $ref: '#/components/requestBodies/ChangeSubMerchantStateBody'
      responses:
        '204':
          $ref: '#/components/responses/SuccessWithoutBody'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Default'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Error_2:
      type: object
      properties:
        Source:
          maxLength: 100
          minLength: 0
          type: string
          description: Source of the error
          example: Service
          nullable: true
        ReasonCode:
          maxLength: 100
          minLength: 0
          type: string
          description: A unique constant identifying the error
          example: format.invalid
          nullable: true
        Description:
          maxLength: 1000
          minLength: 0
          type: string
          description: Short description of the error
          example: Short description of the error
          nullable: true
        Recoverable:
          type: boolean
          description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
          example: false
          default: false
          nullable: true
        Details:
          maxLength: 1000
          minLength: 0
          type: string
          description: Optional detailed description of the issue
          example: Detailed description of the error
          nullable: true
      description: Error object
    FraudBase:
      type: object
      properties:
        refId:
          description: Unique identification generated by the transaction originator using UUID logic to unambiguously link a request and response message.
          example: ecb2d942-eabd-42b6-87fd-69c19692bdc6
          maxLength: 36
          minLength: 36
          type: string
        timestamp:
          description: Timestamp of the request initiation by the originator in the format 'YYYY-MM-DDThh:mm:ss:mmm+hh:mm'. The value of '+hh:mm' portion should always be '-05:00' or '-06:00' reflecting CST time.
          example: '2022-05-24T20:34:37+6:00'
          maxLength: 25
          minLength: 25
          type: string
        icaNumber:
          description: ICA number of the Issuer or Acquirer or Provider initiating the fraud submission request.
          example: '1076'
          maxLength: 7
          minLength: 3
          type: string
    SafeFraudProvider:
      description: Indicates the originator of the request. Value 10 is for Issuer and 20 for Acquirer.
      type: string
      example: '10'
      pattern: ^(10|20)
      minLength: 2
      maxLength: 2
    UserId:
      title: User Id
      maxLength: 300
      minLength: 1
      type: string
      description: The user id of the submitter/technical contact.
      example: princess.diana
    ErrorResponse:
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors_2'
      description: Error Response object
    FirstName:
      title: First Name
      maxLength: 30
      minLength: 1
      type: string
      description: The individual's first name
      example: Michael
      nullable: true
    MerchantGuid:
      title: Merchant GUID
      maxLength: 16
      minLength: 11
      type: string
      description: Consumer Clarity internal merchant's GUID
      example: jK2dA5aybhQQBq6C
    ErrorWrapper:
      description: Object containing the list of combination of error reason codes and their corresponding description (can provide up to 5 errors for a record). It will be absent if the request is processed by FLD application successfully.
      title: Error Response
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    FraudState:
      description: Indicates the type of operation to be performed for the given audit control number. The value FDD is to indicate delete operation and FDE is to indicate confirm operation.
      type: string
      minLength: 1
      maxLength: 50
      enum:
      - FDD
      - FDE
    FraudDeleteAndConfirm:
      allOf:
      - $ref: '#/components/schemas/APIDataElement'
      - type: object
        required:
        - providerId
        - auditControlNumber
        - operationType
        properties:
          providerId:
            $ref: '#/components/schemas/SafeFraudProvider'
          operationType:
            $ref: '#/components/schemas/FraudState'
          auditControlNumber:
            description: Unique number generated by FLD application and provided in the response message for a successful fraud record submission (FDA event). This is used as a reference to subsequently modify, delete or convert a suspended to a confirmed fraud record.
            type: string
            minLength: 15
            maxLength: 15
            example: '418142102142002'
          memo:
            description: Brief description by the originator providing some comment supporting the action.
            type: string
            minLength: 1
            maxLength: 1000
            example: This is a sample FDD / FDE request.
    Errors:
      title: Errors
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          description: Errors array wrapped in an error object
          items:
            $ref: '#/components/schemas/Error'
          example: []
    Errors_2:
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          description: List of error objects
          items:
            $ref: '#/components/schemas/Error_2'
          example: []
      description: Errors object
    Fraud:
      allOf:
      - $ref: '#/components/schemas/FraudBase'
      - type: object
        required:
        - responseCode
        - responseMessage
        properties:
          responseCode:
            description: Response code indicating success or failure of the transaction at an API level. Errors at a record level will be handled through 'errorDetails' element associated with each record.
            type: string
            minLength: 3
            maxLength: 3
            example: '000'
          responseMessage:
            description: Transaction response description corresponding to the response code.
            type: string
            minLength: 1
            maxLength: 100
            example: Success
          icaNumber:
            description: ICA number of the originator provided in the request API which is echoed back. This attribute will be absent if the request is not processed by FLD application.
            type: string
            minLength: 3
            maxLength: 7
            example: '1076'
          auditControlNumber:
            description: Unique number generated by FLD application and provided in the response message for a successful fraud record submission ('FDA' event). This is used as a reference in the request API to subsequently modify, delete or convert a suspended to a confirmed fraud record and is echoed back. This attribute will be absent if the request is not processed by FLD application.
            type: string
            minLength: 15
            maxLength: 15
            example: '418142102142002'
          duplicateAuditControlNumbers:
            description: List of existing Audit Control Number which matches the request submitted for Mastercard-built or Issuer-built. This attribute will appear in case of the records already present while trying to submit or update the existing record.
            type: array
            items:
              type: string
            minItems: 1
            maxItems: 5
            uniqueItems: true
          matchLevelIndicator:
            description: Indicates if it is a Mastercard-built or Issuer-built record. Possible values are 'M' for Mastercard built record and 'I' for Issuer built record. This attribute will be absent if the request is not processed by FLD application.
            type: string
            minLength: 1
            maxLength: 1
            example: M
          financialTransactionIndicator:
            description: Indicates if the fraud record is being submitted against a financial transaction (having a clearing record) or a declined auth transaction (without a clearing record). Possible values are 'APPROVED' for financial transactions (having a clearing record) and 'DECLINED' for declined auth transactions (without a clearing record). This attribute will be absent if the request is not processed by FLD application.
            type: string
            minLength: 1
            maxLength: 20
            example: DECLINED
          authorizationResponse:
            description: Provides the 'Auth Response Code' and 'Auth Response Code Description' combination if 'Financial Transaction Indicator' value is 'DECLINED'. This attribute will be absent for all other scenarios.
            type: string
            minLength: 1
            maxLength: 200
            example: 05 - Do not honor
          previousStatus:
            description: Previous status of the transaction in terms of an FDC, FDD and FDE event.
            type: string
            minLength: 1
            maxLength: 50
            example: CONFIRMED-REJECTED
          currentStatus:
            description: Current status of the transaction in terms of an FDA, FDC, FDD and FDE event.
            type: string
            minLength: 1
            maxLength: 50
            example: CONFIRMED-SUCCESS
          channel:
            description: Fraud request submission fld channel name.
            type: string
            minLength: 1
            maxLength: 50
            example: Online
          errorDetails:
            $ref: '#/components/schemas/ErrorWrapper'
    SubMerchantState:
      required:
      - state
      properties:
        state:
          type: string
          description: State of the Sub-Merchant
          example: ACTIVE
          enum:
          - ACTIVE
          - INACTIVE
        inactivationReason:
          title: Reason for Inactivation
          type: string
          description: Reason for Inactivation. Required when state is INACTIVE.
          example: My business is closing
          minLength: 1
          maxLength: 250
    LastName:
      title: Last Name
      maxLength: 30
      minLength: 1
      type: string
      description: The individual's last name
      example: Fox
      nullable: true
    APIDataElement:
      required:
      - refId
      - timestamp
      - icaNumber
      type: object
      properties:
        refId:
          description: Unique identification generated by the transaction originator using UUID logic to unambiguously link a request and response message.
          type: string
          minLength: 36
          maxLength: 36
          example: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp:
          type: string
          description: Timestamp of the request initiation by the originator in the format 'YYYY-MM-DDThh:mm:ss:mmm+hh:mm'. The value of '+hh:mm' portion should always be '-05:00' or '-06:00' reflecting CST time.
          minLength: 25
          maxLength: 25
          example: '2021-02-02T02:34:37-06:00'
        icaNumber:
          description: ICA number of the Issuer or Acquirer initiating the fraud submission request.
          type: string
          minLength: 3
          maxLength: 7
          example: '1076'
        issuerSCAExemption:
          description: Issuer SCA (Strong Customer Authentication) Exemption value. Please refer to [Table 16](https://developer.mastercard.com/fld-fraud-submission/documentation/parameters/annexure-1/#table-16-issuer-sca-strong-customer-authentication-exemption) for possible values.
          type: string
          minLength: 1
          maxLength: 2
          example: 09
    Error:
      title: ErrorMessage
      required:
      - Description
      - ReasonCode
      type: object
      properties:
        Source:
          type: string
          description: The application or component that generated this error.
          minLength: 3
          maxLength: 50
          example: FLD
        ReasonCode:
          type: string
          description: Reason code is a unique constant identifying the error case encountered during request processing.
          minLength: 5
          maxLength: 100
          example: VALIDATION_ERROR
        Description:
          type: string
          description: Human-readable short description of the reasonCode
          minLength: 10
          maxLength: 250
          example: Reference Id is not provided
        Details:
          type: string
          description: Optional detailed description provides information about data received and calculated during request processing.  This helps the user to diagnose errors.
          minLength: 0
          maxLength: 1000
          example: This is mandatory field while requesting for fraud submission.
        Recoverable:
          type: boolean
          description: Recoverable flag indicates whether this error is always returned for this request, or retrying could change the outcome.  For example, 'true' or 'false'.
          example: false
  responses:
    UnauthorizedError:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    Default:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ServerError:
              $ref: '#/components/examples/ServerError'
    RateLimitExceededError:
      description: Too Many Requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            RateLimitExceededExample:
              $ref: '#/components/examples/RateLimitExceededExample'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ResourceNotFound:
              $ref: '#/components/examples/ResourceNotFound'
            EntityNotFound:
              $ref: '#/components/examples/EntityNotFound'
            AlertsEntityNotFound:
              $ref: '#/components/examples/AlertsEntityNotFound'
    SuccessWithoutBody:
      description: Successful Operation
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InvalidData:
              $ref: '#/components/examples/InvalidData'
            AlertsInvalidData:
              $ref: '#/components/examples/AlertsInvalidData'
            InvalidParameterSet:
              $ref: '#/components/examples/InvalidParameterSet'
            FormatInvalid:
              $ref: '#/components/examples/FormatInvalid'
            AlertsFormatInvalid:
              $ref: '#/components/examples/AlertsFormatInvalid'
            MissingRequiredHeader:
              $ref: '#/components/examples/MissingRequiredHeader'
    ForbiddenError:
      description: Consent not given.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            ForbiddenExample:
              $ref: '#/components/examples/ForbiddenExample'
    FraudStateChanged:
      description: Fraud data changed successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fraud'
          examples:
            FraudDataDeleted:
              $ref: '#/components/examples/FraudDataDeleted'
            FraudDataDeleteIcaNotAuthorize:
              $ref: '#/components/examples/FraudDataDeleteIcaNotAuthorize'
            FraudDataConfirmed:
              $ref: '#/components/examples/FraudDataConfirmed'
            FraudDataConfirmedTxnDateOlder:
              $ref: '#/components/examples/FraudDataConfirmedTxnDateOlder'
    BadRequestError:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestRefIdMissing:
              $ref: '#/components/examples/BadRequestRefIdMissing'
  examples:
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: fld
            ReasonCode: UNAUTHORIZED_REQUEST
            Description: Unauthorized request
            Recoverable: false
    AlertsEntityNotFound:
      summary: Entity Not Found Error Response For Alerts
      description: If a requested entity(e.g. Sub-Merchant or Card Acceptor ID or Card Acceptor Name) doesn't exist in the system, then EntityNotFound error response is returned to the caller with HTTP Status code 404.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: subMerchantId'
            Description: Sub-Merchant 99ca4b15-72a6-41dd-8127-573d4b07669c not found
            Recoverable: false
            Details: ''
    MissingRequiredHeader:
      summary: Missing Required Header Error Response
      description: If a required request header is missing or null, then MissingRequiredHeader error response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: missing required header
            Description: Submitter-First-Name
            Recoverable: false
            Details: ''
    FraudDataConfirmedTxnDateOlder:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40-06:00'
        responseCode: '200'
        responseMessage: Failure
        errorDetails:
          Errors:
            Error:
            - ReasonCode: '21508'
              Description: Transaction date is older than 18 months.
    RateLimitExceededExample:
      value:
        Errors:
          Error:
          - Source: fld
            ReasonCode: RATE_LIMIT_EXCEEDED
            Description: You have exceeded the service rate limit. Maximum allowed 10 TPS.
            Recoverable: true
            details: null
    ResourceNotFound:
      summary: Resource Not Found Error Response
      description: If request URI doesn't match with any available endpoints, then ResourceNotFound error response is returned the caller with HTTP Status code 404.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: resource.not.found
            Description: Not Found
            Recoverable: false
            Details: /merchant-self-services/sub-merchantTs/
    ServerError:
      summary: Server Error Response
      description: If an unexpected internal server error occurs, then ServerError response is returned to the caller with HTTP Status code 500.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: server.error
            Description: Internal Server Error
            Recoverable: false
            Details: ''
    BadRequestRefIdMissing:
      value:
        Errors:
          Error:
          - Source: fld
            ReasonCode: VALIDATION_ERROR
            Description: Reference Id is not provided
            Recoverable: false
    FormatInvalid:
      summary: Format Invalid Error Response For Consumer Clarity
      description: If a field is not correctly formatted (e.g. a String value is sent in an Integer type field), then FormatInvalid response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: format.invalid
            Description: orderHistoryMonths
            Recoverable: false
            Details: ''
    FraudDataConfirmed:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40-06:00'
        responseCode: '000'
        responseMessage: Success
        icaNumber: '1076'
        auditControlNumber: '123111111000025'
        previousStatus: CONFIRMED-SUSPENDED
        currentStatus: CONFIRMED-SUCCESS
    AlertsFormatInvalid:
      summary: Format Invalid Error Response For Alerts
      description: If a field is not correctly formatted (e.g. a String value is sent in an Integer type field), then FormatInvalid response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: merchantCategoryCode'
            Description: must match \"^[0-9]*$\"
            Recoverable: false
            Details: ''
    EntityNotFound:
      summary: Entity Not Found Error Response For Consumer Clarity
      description: If a requested entity(e.g. Merchant or Logo) doesn't exist in the system, then EntityNotFound error response is returned to the caller with HTTP Status code 404.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: GUID'
            Description: Merchant 1E37M8VSX1D28QYX not found
            Recoverable: false
            Details: ''
    FraudDeleteExample:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:37-06:00'
        icaNumber: '1076'
        providerId: '10'
        auditControlNumber: '123111111000025'
        operationType: FDD
        memo: This is a sample FDD request.
    InvalidParameterSet:
      summary: Invalid Parameter Set Error Response
      description: If request body is malformed or missing, then InvalidParameterSet error response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: invalid.parameter.set
            Description: request body is malformed
            Recoverable: false
            Details: ''
    FraudConfirmExample:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:37-06:00'
        icaNumber: '1076'
        providerId: '10'
        auditControlNumber: '123111111000025'
        operationType: FDE
        memo: This is a sample FDE request.
    InvalidData:
      summary: Invalid Data Error Response For Consumer Clarity
      description: If a field or set of fields fails a validation (eg. NotNull, Length, Pattern etc.), then InvalidData response will be returned to the caller for each invalid field with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: merchantType'
            Description: must not be blank
            Recoverable: false
            Details: ''
    FraudDataDeleted:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40-06:00'
        responseCode: '000'
        responseMessage: Success
        icaNumber: '1076'
        auditControlNumber: '123111111000025'
        previousStatus: CONFIRMED-SUCCESS
        currentStatus: CONFIRMED-DELETED
    AlertsInvalidData:
      summary: Invalid Data Field Error Response For Alerts
      description: If a field or set of fields fails a validation (eg. NotNull, Length, Pattern etc.), then InvalidData response will be returned to the caller for each invalid field with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: name'
            Description: size must be between 3 and 200
            Recoverable: false
            Details: ''
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: fld
            ReasonCode: CONSENT_NOT_GIVEN
            Description: User Consent Not Given
            Recoverable: false
    FraudDataDeleteIcaNotAuthorize:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40-06:00'
        responseCode: '200'
        responseMessage: Failure
        errorDetails:
          Errors:
            Error:
            - ReasonCode: '80207'
              Description: The user is not licensed for this particular BIN range.
  requestBodies:
    ChangeSubMerchantStateBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SubMerchantState'
          examples:
            inactivation:
              value:
                state: INACTIVE
                inactivationReason: My business is closing
            activation:
              value:
                state: ACTIVE
    FraudStateRequest:
      description: Delete an existing fraud record or confirm a suspended fraud record for both Mastercard and Issuer built transactions.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FraudDeleteAndConfirm'
          examples:
            FraudConfirmExample:
              $ref: '#/components/examples/FraudConfirmExample'
            FraudDeleteExample:
              $ref: '#/components/examples/FraudDeleteExample'
  parameters:
    SubmitterFirstNameParam:
      name: Submitter-First-Name
      in: header
      required: true
      example: Diana
      description: The first name of the submitter/technical contact.
      schema:
        $ref: '#/components/schemas/FirstName'
    MerchantGuidParam:
      name: guid
      in: path
      required: true
      description: Consumer Clarity internal merchant's GUID
      example: jK2dA5aybhQQBq6C
      schema:
        $ref: '#/components/schemas/MerchantGuid'
    SubmitterLastNameParam:
      name: Submitter-Last-Name
      in: header
      required: true
      example: Princess
      description: The last name of the submitter/technical contact.
      schema:
        $ref: '#/components/schemas/LastName'
    UserIdParam:
      name: User-Id
      in: header
      required: true
      example: princess.diana
      description: The user id of the submitter/technical contact.
      schema:
        $ref: '#/components/schemas/UserId'