swagger: '2.0' info: title: Mastercard Bill Payment Validator Account Opening Guid 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: Guid paths: /merchants/{guid}/logos: parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' put: tags: - Guid summary: Mastercard Update a Logo for an Existing Merchant. description: Returns status and messages (if any validation failures) related to the logo of a sub-merchant. operationId: updateMerchantLogoByGuid requestBody: $ref: '#/components/requestBodies/MerchantLogoBody' responses: '200': $ref: '#/components/responses/LogoSuccess' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK post: tags: - Guid summary: Mastercard Create a Logo for an Existing Merchant. description: Returns status and messages (if any validation failures) related to the logo of a sub-merchant. operationId: createMerchantLogo requestBody: $ref: '#/components/requestBodies/MerchantLogoBody' responses: '200': $ref: '#/components/responses/LogoSuccess' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: tags: - Guid summary: Mastercard Delete a Logo for an Existing Merchant. description: Returns 204 status code if logo deleted successfully. operationId: deleteLogoByMerchantGuid 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 get: tags: - Guid summary: Mastercard Get the Logo for an Existing Merchant. description: Returns base64 encoded image, status and messages (if any validation failures) related to the logo of a sub-merchant. operationId: getLogoByMerchantGuid responses: '200': $ref: '#/components/responses/LogoSuccessWithImage' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK /sub-merchants/{guid}: put: tags: - Guid summary: Mastercard Update a Sub-merchant. description: Returns sub-merchant object with status. operationId: updateSubMerchant parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/IfMatch' - $ref: '#/components/parameters/MerchantGuidParam' requestBody: $ref: '#/components/requestBodies/SubMerchantBody' responses: '200': $ref: '#/components/responses/SubMerchantSuccess' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '412': $ref: '#/components/responses/PreconditionFailed' '428': $ref: '#/components/responses/PreconditionRequired' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK get: tags: - Guid summary: Mastercard Get Sub-merchant by Guid. description: Returns sub-merchant object with status. operationId: getSubMerchantByGuid parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' responses: '200': $ref: '#/components/responses/SubMerchantSuccess' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' 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: - Guid 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 /sub-merchants/{guid}/locations: parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' post: tags: - Guid summary: Mastercard Add a Unique Set of Sub-merchant's Locations description: Creates locations under an existing sub-merchant operationId: addLocations requestBody: $ref: '#/components/requestBodies/LocationsBulkRequestBody' responses: '200': $ref: '#/components/responses/LocationsBulkSuccess' '400': $ref: '#/components/responses/BadRequest' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK get: parameters: - $ref: '#/components/parameters/ClarityOffsetParam' - $ref: '#/components/parameters/ClarityPageNumberParam' - $ref: '#/components/parameters/ClaritySortDirectionParam' - $ref: '#/components/parameters/ClaritySortFieldParam' - $ref: '#/components/parameters/LocationSearchTextQueryParam' summary: Mastercard Get Sub-merchant's Locations description: Returns sub-merchant's locations with pagination metadata operationId: getAllLocations tags: - Guid responses: '200': $ref: '#/components/responses/PageableLocationsSuccess' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK /sub-merchants/{guid}/locations/{location_id}: get: summary: Mastercard Get Location by Id description: Returns location object operationId: getLocationById parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' - $ref: '#/components/parameters/LocationIdParam' tags: - Guid responses: '200': $ref: '#/components/responses/LocationSuccess' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK put: summary: Mastercard Update an Existing Location description: Updates a location object operationId: updateLocation tags: - Guid parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' - $ref: '#/components/parameters/LocationIdParam' - $ref: '#/components/parameters/IfMatch' requestBody: $ref: '#/components/requestBodies/LocationBody' responses: '200': $ref: '#/components/responses/LocationSuccess' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: summary: Mastercard Delete an Existing Location description: Returns 204 status code if Location deleted successfully operationId: deleteLocation parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' - $ref: '#/components/parameters/LocationIdParam' tags: - Guid 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 /sub-merchants/{guid}/locations/{location_id}/card-acceptor-names: parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' - $ref: '#/components/parameters/LocationIdParam' post: summary: Mastercard Add Card Acceptor Names description: Creates card acceptor names under a location of an existing sub-merchant operationId: addCardAcceptorNames tags: - Guid requestBody: $ref: '#/components/requestBodies/CardAcceptorNamesBulkRequestBody' responses: '200': $ref: '#/components/responses/CardAcceptorNamesBulkSuccess' '400': $ref: '#/components/responses/BadRequest' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK get: parameters: - $ref: '#/components/parameters/ClarityOffsetParam' - $ref: '#/components/parameters/ClarityPageNumberParam' - $ref: '#/components/parameters/ClaritySortDirectionParam' - $ref: '#/components/parameters/ClaritySortFieldParam' - $ref: '#/components/parameters/CardAcceptorNameSearchTextParam' summary: Mastercard Get Card Acceptor Names description: Returns Card Acceptor Names with pagination metadata operationId: getCardAcceptorNames tags: - Guid responses: '200': $ref: '#/components/responses/PageableCardAcceptorNamesSuccess' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK /sub-merchants/{guid}/locations/{location_id}/card-acceptor-names/{id}: get: summary: Mastercard Get Card Acceptor Name by Id description: Returns card acceptor name object operationId: getCardAcceptorNameById tags: - Guid parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' - $ref: '#/components/parameters/LocationIdParam' - $ref: '#/components/parameters/CardAcceptorNameIdParam' responses: '200': $ref: '#/components/responses/CardAcceptorSuccess' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK put: summary: Mastercard Update Card Acceptor Name by Id description: Updates card acceptor name object operationId: updateCardAcceptorNameById tags: - Guid parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' - $ref: '#/components/parameters/LocationIdParam' - $ref: '#/components/parameters/CardAcceptorNameIdParam' - $ref: '#/components/parameters/IfMatch' requestBody: $ref: '#/components/requestBodies/CardAcceptorNamesBody' responses: '200': $ref: '#/components/responses/CardAcceptorSuccess' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: summary: Mastercard Delete Existing Card Acceptor Name description: Returns 204 status code if Card Acceptor Name deleted successfully operationId: deleteCardAcceptorById tags: - Guid parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' - $ref: '#/components/parameters/LocationIdParam' - $ref: '#/components/parameters/CardAcceptorNameIdParam' 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 /sub-merchants/{guid}/locations/{location_id}/acquirer-merchant-ids: parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' - $ref: '#/components/parameters/LocationIdParam' post: summary: Mastercard Add Acquirer Reference Id and Card Acceptor Id Pairs description: Returns added pairs of Acquirer Reference ID and Card Acceptor ID. Non unique pairs are placed in the rejected list. operationId: addAcquirerMerchantIds tags: - Guid requestBody: $ref: '#/components/requestBodies/AcquirerMerchantIdsRequestBody' responses: '200': $ref: '#/components/responses/AcquirerMerchantIdsSuccess' '400': $ref: '#/components/responses/BadRequest' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK get: parameters: - $ref: '#/components/parameters/ClarityOffsetParam' - $ref: '#/components/parameters/ClarityPageNumberParam' - $ref: '#/components/parameters/ClaritySortDirectionParam' - $ref: '#/components/parameters/AcquirerMerchantIdsSortFieldParam' - $ref: '#/components/parameters/AcquirerMerchantIdsSearchTextParam' summary: Mastercard Get Accepted Acquirer Reference Id and Card Acceptor Id Pairs description: Returns accepted Acquirer Reference ID and CardAcceptor ID pairs with pagination metadata operationId: getAcceptedAcquirerMerchantIds tags: - Guid responses: '200': $ref: '#/components/responses/PageableAcceptedAcquirerMerchantIdsSuccess' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK /sub-merchants/{guid}/locations/{location_id}/acquirer-merchant-ids/{acquirer_merchant_id}: parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MerchantGuidParam' - $ref: '#/components/parameters/LocationIdParam' - $ref: '#/components/parameters/AcquirerMerchantIdParam' delete: summary: Mastercard Delete Existing Acquirer Reference Id and Card Acceptor Id Pair description: Returns 204 status code if acquirer reference ID and card acceptor ID pair deleted successfully operationId: deleteAcceptedAcquirerMerchantId tags: - Guid 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 /users/{user_guid}/virtual-card-accounts: get: tags: - Guid summary: Retrieve a list of all virtual cards linked to a user description: This endpoint allows users to retrieve a list of all virtual cards linked to a user operationId: findVcnCardsByUser parameters: - $ref: '#/components/parameters/userGUID' responses: '200': $ref: '#/components/responses/VirtualCards' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' post: parameters: - $ref: '#/components/parameters/userGUID' tags: - Guid summary: Register a virtual card linked to a user description: This endpoint allows users to register a virtual card linked to a user operationId: createVirtualCardWithControls requestBody: $ref: '#/components/requestBodies/NewVirtualCard' responses: '201': $ref: '#/components/responses/ResourceCreated' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' /users/{user_guid}/virtual-card-accounts/{account_guid}: get: parameters: - $ref: '#/components/parameters/userGUID' - $ref: '#/components/parameters/accountGUID' tags: - Guid summary: Retrieve virtual card account details linked to a user description: This endpoint allows users to retrieve virtual card account details linked to a user operationId: findVcnCardByUser responses: '200': $ref: '#/components/responses/VirtualCard' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' put: parameters: - $ref: '#/components/parameters/userGUID' - $ref: '#/components/parameters/accountGUID' tags: - Guid summary: Update virtual card account details linked to a user description: This endpoint allows users to update virtual card account details linked to a user operationId: updateUserCardAndControls requestBody: $ref: '#/components/requestBodies/UpdatedVirtualCard' responses: '200': $ref: '#/components/responses/OKResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' delete: tags: - Guid summary: Delete a virtual card account linked to a user description: This endpoint allows users to delete a virtual card account linked to a user parameters: - $ref: '#/components/parameters/userGUID' - $ref: '#/components/parameters/accountGUID' operationId: deleteUserVirtualCard responses: '204': $ref: '#/components/responses/NOContentResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' /users/{user_guid}: get: tags: - Guid summary: Retrieve user details description: This endpoint allows users to retrieve details of a particular user operationId: getUserById parameters: - $ref: '#/components/parameters/userGUID' responses: '200': $ref: '#/components/responses/User' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' put: tags: - Guid summary: Update a user description: This endpoint allows users to update details of a particular user operationId: updateUserById parameters: - $ref: '#/components/parameters/userGUID' requestBody: $ref: '#/components/requestBodies/User' responses: '200': $ref: '#/components/responses/OKResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' delete: tags: - Guid summary: Delete a user description: This endpoint allows users to delete a particular user parameters: - $ref: '#/components/parameters/userGUID' operationId: deleteUser responses: '204': $ref: '#/components/responses/NOContentResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' /real-card-accounts/{account_guid}: delete: tags: - Guid summary: Delete all virtual cards linked to a real card description: This endpoint allows users to delete all virtual cards linked to a real card account_guid parameters: - $ref: '#/components/parameters/accountGUID' operationId: DeleteVcnsByRealCardAccountGuid responses: '204': $ref: '#/components/responses/NOContentResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' /users/{user_guid}/virtual-card-accounts/{account_guid}/tokens: post: parameters: - $ref: '#/components/parameters/userGUID' - $ref: '#/components/parameters/accountGUID' tags: - Guid summary: Register a token linked to a user and a virtual card description: This endpoint allows users to register a token linked to a user and a virtual card operationId: TokenCreate requestBody: $ref: '#/components/requestBodies/NewToken' responses: '201': $ref: '#/components/responses/ResourceCreated' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' /users/{user_guid}/virtual-card-accounts/{account_guid}/tokens/{token_guid}: get: parameters: - $ref: '#/components/parameters/userGUID' - $ref: '#/components/parameters/accountGUID' - $ref: '#/components/parameters/tokenGUID' tags: - Guid summary: Retrieve token details linked to a user and a virtual card description: This endpoint allows users to retrieve token details linked to a user and a virtual card operationId: getTokenById responses: '200': $ref: '#/components/responses/Token' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' put: tags: - Guid parameters: - $ref: '#/components/parameters/userGUID' - $ref: '#/components/parameters/accountGUID' - $ref: '#/components/parameters/tokenGUID' summary: Update a token linked to a user and a virtual card description: This endpoint allows users to update a token linked to a user and a virtual card operationId: updateTokenById requestBody: $ref: '#/components/requestBodies/UpdatedToken' responses: '200': $ref: '#/components/responses/OKResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' delete: tags: - Guid parameters: - $ref: '#/components/parameters/userGUID' - $ref: '#/components/parameters/accountGUID' - $ref: '#/components/parameters/tokenGUID' summary: Delete a token linked to a user and a virtual card description: This endpoint allows users to delete a token linked to a user and a virtual card operationId: deleteTokenById responses: '204': $ref: '#/components/responses/NOContentResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/ResourceNotFoundError' components: schemas: PercentOwnership: title: Percent Ownership minLength: 1 maxLength: 5 pattern: ^(100(\.00?)?|[1-9]\d?(\.\d{1,2})?|0\.\d{1,2})$ type: string description: Percent Ownership. example: '25.50' nullable: true AcquirerMerchantIdsResource: title: Acquirer reference ID & card acceptor ID pairs resource description: Set of acquirer reference ID & card acceptor ID pairs resource properties: acceptedIds: $ref: '#/components/schemas/AcceptedAcquirerMerchantIdsResource' rejectedIds: description: Rejected acquirer reference ID & card acceptor ID pairs type: array items: $ref: '#/components/schemas/AcquirerMerchantId' example: [] SanctionScreening: title: Sanction Screening type: object required: - taxId - publiclyTraded - doBusinessWithSanctionedGeographies properties: taxId: title: Tax Identification description: Known as VAT Number in the US and GST in Canada. example: 123456789AB1234 type: string minLength: 1 maxLength: 30 formerLegalNames: title: List of Former Legal Names description: The merchant's former legal names uniqueItems: true type: array nullable: true items: $ref: '#/components/schemas/MerchantName' example: [] doBusinessWithSanctionedGeographies: title: Business With Sanctioned Geographies Indicator description: 'Indicates whether the merchant does business with sanctioned geographies. If it is true, then sanctionedGeographies property can''t be empty. ' type: boolean example: false sanctionedGeographies: title: List of Sanctioned Geographies description: 'List of sanctioned geographies that the merchant is doing business with. It can''t be empty if the doBusinessWithSanctionedGeographies property is true ' uniqueItems: true type: array nullable: true items: title: Sanctioned Geography type: string minLength: 1 maxLength: 60 description: Sanctioned geography example: Iran example: [] publiclyTraded: title: Merchant Publicly Traded Indicator description: Indicates whether a merchant is publicly traded. type: boolean example: false tickerSymbol: title: Merchant's Stock Symbol description: Publicly traded merchant's stock symbol. It's mandatory if the isPubliclyTraded attribute is true. type: string minLength: 1 maxLength: 10 example: NFLX nullable: true beneficialOwners: type: array title: List of Beneficial Owners description: Required only if publiclyTraded property is false and legalEntities property is empty. uniqueItems: true nullable: true items: $ref: '#/components/schemas/BeneficialOwner' example: [] legalEntities: type: array title: List of Legal Entities description: Required only if publiclyTraded property is false and beneficialOwners property is empty. uniqueItems: true nullable: true items: $ref: '#/components/schemas/LegalEntity' example: [] ShortEmail: title: Email Address maxLength: 100 minLength: 1 type: string description: Email address example: john.doe@example.com format: email nullable: true ImageBase64Encoded: title: Image Base 64 Encoded type: string description: Base 64 encoded image (JPG or PNG) minLength: 0 maxLength: 999999999 example: /9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYHBwcGBwcICQsJCAgKCAcHCg0KCgsMDAwMBwkODw0MDgsMDAz/2wBDAQICAgMDAwYDAwYMCAcIDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAz/wAARCAAQABADASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD638d/8HA2uah8em0jwP4L0W+8JxXZt459QmlW6vo1PMoKnbGCASAVY4xn0r6L+F//AAUzn8XatY3Op6HZ22h37AFoXYzWoJxkk8NjvgCvmXx1/wAG/wD4s0X4+HU/A3izw7D4RkuzPEuoiUXVjExOYtqqVkwCQDuXPGcV9JfCz/gmbf8AhTVrGz1TWbCbQ7BgWMAbzroA5IwQAue/JxnvX4TxVPjz63R/slO3Nr8HL/29fXltb8etj+puKKfhUsBR/spxvya6z59vtX0579vP7Nj/2Q== AcquirerReferenceId: title: Acquirer Reference ID (ARID) description: The acquirer BINs that a partner currently services under their portfolio. This is represented by Mastercard DE 31 - Subfield 2 (Clearing), DE 32 (Authorization), or Visa Field 32. type: string minLength: 6 maxLength: 6 pattern: ^[\d]+$ example: '123456' ResourceId: type: string minLength: 1 maxLength: 40 description: Unique identifier of resource nullable: true example: Mxyz123 CardAcceptor: title: Merchant Card Acceptor maxLength: 50 minLength: 1 type: string description: Merchant Card Acceptor example: ETHOCA NINJA GAMES LocationWithoutCardAcceptorsResource: type: object allOf: - $ref: '#/components/schemas/LocationWithoutCardAcceptors' - properties: id: $ref: '#/components/schemas/ResourceId' cardAcceptorLocationType: title: Card Acceptor Location Type type: string description: Types of card acceptor location - ONLINE, PHONE, CARD_PRESENT example: ONLINE nullable: true CardAcceptorDataResource: title: Merchant Card Acceptor Names type: object required: - matchType - cardAcceptorName - id - status properties: matchType: title: Card Acceptor Match Type maxLength: 50 minLength: 1 type: string description: The card acceptor match type example: EXACT cardAcceptorName: $ref: '#/components/schemas/CardAcceptor' id: $ref: '#/components/schemas/ResourceId' status: title: Response Status type: string description: The status of Card Acceptor Name - PENDING, PASS, FAILED example: PENDING SearchFieldResource: type: object properties: searchParameter: title: Search Parameter type: string maxLength: 28 minLength: 12 description: Merchant api search parameter example: cardAcceptorName nullable: true required: title: Required type: boolean description: Set true if this search parameter is mandatory example: true nullable: true searchFieldCards: $ref: '#/components/schemas/CardTypesResource' description: Merchant Api Search Field AcquirerMerchantIdResource: type: object title: Acquirer reference ID & card acceptor ID resource description: Acquirer reference ID & card acceptor ID resource required: - id allOf: - $ref: '#/components/schemas/AcquirerMerchantId' - type: object properties: id: $ref: '#/components/schemas/ResourceId' CardAcceptorData: title: Merchant Card Acceptor Names type: object required: - matchType - cardAcceptorName properties: matchType: title: Card Acceptor Match Type type: string description: Types of card acceptor match type example: EXACT enum: - EXACT - STARTS_WITH - STRICT_CONTAINS - CONTAINS cardAcceptorName: $ref: '#/components/schemas/CardAcceptor' PageableCardAcceptorNamesResource: title: Pageable card acceptor names resource description: Pageable card acceptor names resource with pagination metadata properties: data: type: array description: List of card acceptor resources items: $ref: '#/components/schemas/CardAcceptorDataResource' example: [] metadata: $ref: '#/components/schemas/ClarityResponseHeader' LocaleResource: allOf: - $ref: '#/components/schemas/Locale' - type: object properties: code: title: Code type: string description: The locale where the merchant anticipates their business to be located; often referred to as the Accept-Language in HTTP headers. example: EN_CA PageableLocationsResource: title: Pageable locations resource description: Pageable locations resource with pagination metadata properties: data: type: array description: List of Location resources items: $ref: '#/components/schemas/LocationWithoutCardAcceptorsResource' example: [] metadata: $ref: '#/components/schemas/ClarityResponseHeader' AcquirerMerchantId: type: object title: Acquirer reference ID & card acceptor ID pair description: Acquirer reference ID & card acceptor ID pair required: - acquirerReferenceId - cardAcceptorId properties: acquirerReferenceId: $ref: '#/components/schemas/AcquirerReferenceId' cardAcceptorId: $ref: '#/components/schemas/CardAcceptorId' firstPartyTrustEnabled: type: boolean description: Marks the ARID/CAID pair as relevant for the FPT engine. When false, the FPT engine won't use the ARID/CAID pair for identifying transactions. example: true default: false CardAcceptors: title: Merchant Card Acceptors maxItems: 1500 type: array uniqueItems: true description: List of merchant card acceptors nullable: true items: $ref: '#/components/schemas/CardAcceptor' LocationsBulkResource: title: Locations resource description: List of locations resource type: object properties: locations: type: array items: $ref: '#/components/schemas/BulkOperationResource' example: [] LastName: title: Last Name maxLength: 30 minLength: 1 type: string description: The individual's last name example: Fox nullable: true 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 LogoImageResource: allOf: - $ref: '#/components/schemas/LogoResource' - type: object properties: imageBase64Encoded: $ref: '#/components/schemas/ImageBase64Encoded' description: Schema for a sub-merchant logo including image binary SearchFieldsResource: title: Search Fields Response type: array description: Search Field nullable: true items: $ref: '#/components/schemas/SearchFieldResource' SecondName: title: Second Name maxLength: 30 minLength: 1 type: string description: The individual's second name example: Andrew nullable: true PrimaryContact: title: Primary Contact description: Primary contact details of the merchant required: - jobTitle - firstName - lastName - email properties: jobTitle: title: Job Title type: string minLength: 1 maxLength: 100 description: Job title of the primary contact example: Manager firstName: title: First Name type: string minLength: 1 maxLength: 50 description: First name of the primary contact example: John lastName: title: Last Name type: string minLength: 1 maxLength: 50 description: Last name of the primary contact example: Doe email: $ref: '#/components/schemas/ShortEmail' phone: title: Phone maxLength: 30 minLength: 3 type: string description: Phone number for primary contact example: 1-234-567-8901 nullable: true LocationResource: deprecated: true allOf: - $ref: '#/components/schemas/Location' - type: object properties: id: $ref: '#/components/schemas/ResourceId' rejectedCardAcceptorNames: $ref: '#/components/schemas/CardAcceptors' cardAcceptorLocationType: title: Card Acceptor Location Type type: string description: Types of card acceptor location - ONLINE, PHONE, CARD_PRESENT example: ONLINE nullable: true ResponseTime: type: string description: Total response time in ms minLength: 0 maxLength: 10 example: 300 ms AcquirerMerchantIds: title: Acquirer reference ID & card acceptor ID pairs maxItems: 100 minItems: 1 type: array uniqueItems: true description: Set of acquirer reference ID & card acceptor ID pairs items: $ref: '#/components/schemas/AcquirerMerchantId' LocationWithoutCardAcceptors: type: object required: - countryCode allOf: - $ref: '#/components/schemas/Address' - properties: website: title: Website maxLength: 100 minLength: 1 type: string description: URL for merchant's customer service focused information. example: https://merchantwebsite.example.com/customerservice.html nullable: true email: $ref: '#/components/schemas/ShortEmail' contactWebsite: title: Contact Website maxLength: 100 minLength: 1 type: string description: Merchant's contact website. example: https://merchantwebsite.example.com/contactus.html nullable: true displayAddressToCardHolder: title: Display Address To Card Holder type: boolean description: Set true to display this location's address to card holder example: true nullable: true displayPhoneToCardHolder: title: Display Phone To Card Holder type: boolean description: Set true to display this location's phone number to card holder example: true nullable: true refundPolicy: title: Refund Policy maxLength: 1500 minLength: 1 type: string description: Entire merchant refund policy, formatted for text display example: Complete merchant refund policy nullable: true terms: title: Terms and Conditions maxLength: 2000 minLength: 1 type: string description: Entire merchant Terms & Conditions, formatted for text display example: Entire merchant Terms & Conditions nullable: true customerServiceInstructions: title: Customer Service Information maxLength: 500 minLength: 1 type: string description: Free form text displayed to issuer that can be sent to the cardholder. Can be specific to transaction. example: Include Transaction ID in all communications. nullable: true additionalInfo: title: Additional Info maxLength: 1500 minLength: 1 type: string description: Additional information that a merchant would want a customer or Issuer to know in regards to a transaction. example: Customers can contact merchants for a refund 24 hours a day. nullable: true termsWebsite: title: Merchant Terms Website maxLength: 255 minLength: 1 type: string description: Merchant terms website URL example: https://merchantwebsite.example.com/terms.html nullable: true refundPolicyWebsite: title: Merchant Refund Policy Website maxLength: 255 minLength: 1 type: string description: Merchant refund policy website URL example: https://merchantwebsite.example.com/refunds.html nullable: true defaultLocation: title: Default Location type: boolean description: true if this is a default location of a merchant example: true cardAcceptorLocation: title: Card Acceptor Location maxLength: 150 minLength: 1 type: string description: Card Acceptor Location example: Pan American Airlines Canada nullable: true cardAcceptorLocationType: title: Card Acceptor Location Type type: string description: Types of card acceptor location - ONLINE, PHONE, CARD_PRESENT example: CARD_PRESENT nullable: true enum: - ONLINE - PHONE - CARD_PRESENT description: Merchant location details AcquirerMerchant: description: Acquirer & Merchant IDs information title: AcquirerMerchant required: - acquirerMerchantIds properties: acquirerMerchantIds: $ref: '#/components/schemas/AcquirerMerchantIds' SubMerchant: description: Schema for a sub-merchant allOf: - $ref: '#/components/schemas/Merchant' - type: object required: - subMerchantIdentifier properties: subMerchantIdentifier: $ref: '#/components/schemas/SubMerchantIdentifier' searchFields: $ref: '#/components/schemas/SearchFields' BaseMerchant: type: object description: Base merchant model schema required: - name - industryCode - primaryContact - legalAddress properties: name: title: Name maxLength: 60 minLength: 1 type: string description: Name of the merchant that the item was purchased from. example: Pan American Airlines categoryCode: title: Merchant Category Code maxLength: 4 minLength: 4 pattern: ^[0-9]*$ type: string description: A four-digit number listed in ISO 18245 for retail financial services. MCC is used to classify the business by the type of goods or services it provides. example: '3002' nullable: true orderAvailabilityDateTime: title: Order Availability Date type: string description: The earliest date an Issuer can search for orders (i.e. the date an Issuer cannot search before). Date-Time must be in [ISO 8601 format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) example: '2021-10-18T13:56:47.123+00:00' format: date-time nullable: true orderHistoryMonths: title: Order History in Months maximum: 12 minimum: 1 type: integer description: The number of months worth of data you have made available to search on. format: int32 example: 5 nullable: true orderLatencyDays: title: Order Latency in Days maximum: 365 minimum: 0 type: integer description: 'The numbers of days that need to elapse between an authorization for a purchase and when the purchase can be searched on. ' format: int32 example: 5 nullable: true industryCode: title: Industry Code maxLength: 3 minLength: 3 type: string description: Industry Code is used to classify the business by the type of industry. example: ACC primaryContact: $ref: '#/components/schemas/PrimaryContact' legalAddress: $ref: '#/components/schemas/LegalAddress' FirstPartyTrustEnrollmentType: title: First Party Trust Enrollment Types type: string description: Type of First Party Trust Enrollment example: CLARITY enum: - CLARITY - ISSM AcceptedAcquirerMerchantIdsResource: description: Accepted acquirer reference ID & card acceptor ID pairs type: array items: $ref: '#/components/schemas/AcquirerMerchantIdResource' Crm: title: Customer Relationship Management type: object description: Customer Relationship Management nullable: true properties: termsConditionsConsent: $ref: '#/components/schemas/TermsConditionsConsent' sanctionScreening: $ref: '#/components/schemas/SanctionScreening' paymentConfirmation: title: Payment Confirmation type: boolean description: Confirmation of payment account setup example: true default: false EntityName: title: Entity Legal/Business Name maxLength: 100 minLength: 1 type: string description: The entity's legal or business name. example: Walmart nullable: true ErrorResponse: required: - Errors type: object properties: Errors: $ref: '#/components/schemas/Errors' description: Error Response object Etag: title: Entity Tag maxLength: 100 minLength: 1 type: string description: Etag is a response header which is an identifier for a specific version of a resource. example: '"842DFBC17F921E7716642B9164F3B22B"' MerchantGuid: title: Merchant GUID maxLength: 16 minLength: 11 type: string description: Consumer Clarity internal merchant's GUID example: jK2dA5aybhQQBq6C LogoResource: type: object required: - status properties: status: title: Status maxLength: 100 minLength: 1 type: string description: Status of the logo example: ACTIVE messages: title: Messages type: array description: List of validation messages for a logo. nullable: true items: maxLength: 200 minLength: 1 type: string example: Logo under review example: [] description: Schema for a sub-merchant logo status BulkOperationResource: title: Bulk post resource description: Resource with responseCode and details type: object required: - status properties: id: $ref: '#/components/schemas/ResourceId' errors: type: array description: List of error objects nullable: true items: $ref: '#/components/schemas/Error' example: [] status: title: Response Status type: string description: The status of resource - PENDING, PASS, FAILED example: PENDING Merchant: description: Base merchant request schema required: - merchantType - locales - businessType allOf: - $ref: '#/components/schemas/BaseMerchant' - type: object properties: merchantType: title: Merchant Type type: string description: 'Type of a merchant. Allowed Values - + SUB_MERCHANT - + DIRECT - + GATEWAY - ' example: SUB_MERCHANT enum: - SUB_MERCHANT - DIRECT - GATEWAY locales: title: Merchant Locales minItems: 1 maxItems: 10 uniqueItems: true type: array description: Merchant Locales items: $ref: '#/components/schemas/Locale' locations: title: Merchant Locations minItems: 0 maxItems: 50 uniqueItems: true type: array description: Merchant Locations deprecated: true nullable: true items: $ref: '#/components/schemas/Location' contentTypes: title: Content Types uniqueItems: true type: array description: An indicator as to the type of products and services you offer. nullable: true example: - ADULT_LANGUAGE items: type: string enum: - ADULT_LANGUAGE - ADULT_PRODUCTS - ADULT_SERVICES - GAMBLING - ONLINE_DATING - OTHER crm: $ref: '#/components/schemas/Crm' businessType: title: Merchant Business Type type: string description: Business type describes the legal structure under which the business operates example: BUSINESS_CORPORATION enum: - SOLE_PROPRIETORSHIP - BUSINESS_CORPORATION - OTHER firstPartyTrustEnrollments: title: First Party Trust Enrollments description: A list of First Party Trust Enrollments type: array minLength: 0 maxLength: 2 uniqueItems: true nullable: true items: $ref: '#/components/schemas/FirstPartyTrustEnrollment' Errors: required: - Error type: object properties: Error: type: array description: List of error objects items: $ref: '#/components/schemas/Error' example: [] description: Errors object BeneficialOwner: title: Beneficial Owner description: Individual owning the merchant. type: object properties: firstName: $ref: '#/components/schemas/FirstName' secondName: $ref: '#/components/schemas/SecondName' lastName: $ref: '#/components/schemas/LastName' address: $ref: '#/components/schemas/ShortAddress' birthCountry: $ref: '#/components/schemas/CountryCode' birthDate: title: Beneficial Owner Birth Date description: Beneficial owner birth date. Date must be in a [ISO 8601 format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) type: string format: date example: '1977-05-23T00:00:00.000Z' nullable: true percentOwnership: $ref: '#/components/schemas/PercentOwnership' Address: title: Address description: Address entity associated to merchant's location and legal address. required: - countryCode allOf: - $ref: '#/components/schemas/ShortAddress' - properties: website: title: Website maxLength: 500 minLength: 1 type: string description: URL for merchant's website example: https://merchantwebsite.example.com nullable: true email: $ref: '#/components/schemas/Email' phone: title: Phone maxLength: 30 minLength: 3 type: string description: Phone number of the merchant's office example: 1-234-567-9999 nullable: true LegalEntity: title: Legal Entity description: Legal entity owning the merchant. type: object properties: name: $ref: '#/components/schemas/EntityName' dba: $ref: '#/components/schemas/EntityName' address: $ref: '#/components/schemas/ShortAddress' percentOwnership: $ref: '#/components/schemas/PercentOwnership' governmentOwned: title: Government Owned description: Indicates whether the legal entity is owned by a Government type: boolean example: false nullable: true CardTypes: title: Card Types type: array minItems: 1 maxItems: 4 uniqueItems: true description: A list of all of the card types that are accepted as a form of payment. items: type: string description: Type of card used for a transaction example: AMEX enum: - AMEX - DISCOVER - MC - VISA TermsConditionsConsent: title: Terms & conditions consent type: object required: - date - firstName - lastName - jobTitle - email - countryCode - consentUuid - consentVersion properties: date: type: string description: Date stamp in which the sub-merchant provided his consent on the terms and conditions. Date must be in [ISO 8601 format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format: date-time example: '2021-10-18T13:56:47.123+00:00' firstName: type: string minLength: 1 maxLength: 50 description: First name of person that gave consent example: John lastName: type: string minLength: 1 maxLength: 50 description: Last name of person that gave consent example: Doe jobTitle: type: string minLength: 1 maxLength: 100 description: Job title of person that gave consent example: Manager email: $ref: '#/components/schemas/Email' countryCode: $ref: '#/components/schemas/CountryCode' consentUuid: type: string minLength: 1 maxLength: 50 description: Universally Unique Identifier (UUID) of the consent that the user consented to example: 3d94ab7b-fe1c-4f7d-ad4c-93c1eb6d29c3 consentVersion: type: string minLength: 1 maxLength: 8 description: Version of the consent that the user consented to example: '1.0' SubMerchantResource: description: Sub-Merchant Response allOf: - $ref: '#/components/schemas/MerchantResource' - type: object properties: subMerchantIdentifier: $ref: '#/components/schemas/SubMerchantIdentifier' searchFields: $ref: '#/components/schemas/SearchFieldsResource' locationCount: $ref: '#/components/schemas/LocationCount' FirstPartyTrustEnrollment: title: First Party Trust Enrollment type: object required: - enrollmentType properties: enrollmentType: $ref: '#/components/schemas/FirstPartyTrustEnrollmentType' MerchantLogo: required: - imageBase64Encoded type: object properties: imageBase64Encoded: $ref: '#/components/schemas/ImageBase64Encoded' description: logo request schema for merchants LocationCount: title: Merchant Location count type: integer default: 0 example: 15 minimum: 0 maximum: 9999999 UserId: title: User Id maxLength: 300 minLength: 1 type: string description: The user id of the submitter/technical contact. example: princess.diana ClarityResponseHeader: allOf: - $ref: '#/components/schemas/ResponseHeader' - type: object properties: currentPage: type: integer description: Current page minimum: 0 maximum: 999999999 example: 2 FirstName: title: First Name maxLength: 30 minLength: 1 type: string description: The individual's first name example: Michael nullable: true CardAcceptorNamesBulkResource: title: Card Acceptor Names resource description: Set of Card Acceptor Names resource type: object properties: cardAcceptorNames: type: array uniqueItems: true items: $ref: '#/components/schemas/BulkOperationResource' example: [] SearchFields: title: Search Fields type: array description: 'SearchFields is an array of SearchField objects. The following validations apply: * If the searchFields array contains both TRANSACTION_AMOUNT and TRANSACTION_CURRENCY_CODE searchParameters, then the value of the "searchFieldCards" and "required" properties must be same for both items * If the searchFields array contains the TRANSACTION_AMOUNT searchParameter, then it must also contain the TRANSACTION_CURRENCY_CODE searchParameter (and vice versa)' nullable: true items: $ref: '#/components/schemas/SearchField' ShortAddress: title: Address description: Address. properties: addressLine1: title: Address Line 1 maxLength: 250 minLength: 1 type: string description: The street detail for the address. example: 223 Blythwood Rd nullable: true addressLine2: title: Address Line 2 maxLength: 250 minLength: 1 type: string description: The secondary street detail for the address. example: Suite 123 nullable: true countryCode: $ref: '#/components/schemas/CountryCode' regionCode: title: Region code maxLength: 3 minLength: 1 type: string description: Region where merchant's legal office is located example: 'ON' nullable: true city: title: City maxLength: 100 minLength: 1 type: string description: City where merchant's legal office is located example: Toronto nullable: true postalCode: title: Postal Code maxLength: 50 minLength: 1 type: string description: The zip/postal detail for the merchant's legal address example: M4N1A7 nullable: true MerchantName: title: Merchant's Name maxLength: 200 minLength: 3 type: string description: Merchant's partial or full name. example: Merchant 1 SalesforceAccountNumber: title: Sales Force Account Number maxLength: 100 minLength: 1 type: string description: Unique identifier for a merchant in sales force system. example: TY12SS33ERYUIOPDDSS34XX Locale: required: - merchantDescription - code - defaultLocale type: object properties: code: title: Code type: string description: The locale where the merchant anticipates their business to be located; often referred to as the Accept-Language in HTTP headers. example: EN_CA enum: - EN_US - EN_CA - EN_GB - ES_MX - ES_ES - ES_US - FR_CA - FR_FR - PT_BR - PT_PT - HE_IL merchantDescription: title: Merchant Description maxLength: 4000 minLength: 1 type: string description: Description of the primary merchant tied to the transaction and responsible for providing the products or services (description of the business, what they do, markets, etc.). Used to help cardholder understand business responsible for the charge. example: An airline that no longer exists. defaultLocale: title: Default Locale type: boolean description: This indicates whether or not this locale will be used as the default locale for displaying information to the customer. example: true description: Merchant Locale details FirstPartyTrustEnrollmentResource: title: First Party Trust Enrollment Resource type: object required: - enrollmentType properties: enrollmentType: minLength: 1 maxLength: 50 type: string description: Type of First Party Trust Enrollment example: CLARITY LocationsBulk: type: object required: - locations properties: locations: minItems: 1 maxItems: 25 type: array uniqueItems: true description: Set of Merchant Locations items: $ref: '#/components/schemas/LocationWithoutCardAcceptors' example: [] ValidationStatus: type: object description: Status of created Merchant nullable: true properties: messages: title: Messages type: array description: List of validation messages for a merchant. nullable: true items: $ref: '#/components/schemas/Error' example: [] contactUs: title: Contact-us message type: string maxLength: 500 minLength: 1 description: Ethoca's CX team contact example: Please reach out to Mastercard/Ethoca customer success team for any questions or concerns. nullable: true MerchantResource: description: Base merchant response schema required: - merchantType - locales - businessType allOf: - $ref: '#/components/schemas/BaseMerchant' - type: object properties: merchantType: title: Merchant Type type: string description: 'Type of a merchant. Allowed Values - + SUB_MERCHANT - + DIRECT - + GATEWAY - ' example: SUB_MERCHANT minLength: 1 maxLength: 50 guid: $ref: '#/components/schemas/MerchantGuid' status: title: Status maxLength: 20 minLength: 4 type: string description: '* CONFIGURATION - This status indicates that this merchant record is being modified. Any changes applied to a record with this status are NOT visible in production. There is no guarantee that the data is either valid or consistent. * TESTING - This status indicates that the merchant is being tested. The data for a record with this status is NOT visible in production and data modifications are not permitted. * LIVE - This status indicates that the merchant record is visible in production. The data has been validated and is used for transaction lookups. Data modifications are not permitted. * INACTIVE - This status indicates that this merchant record is NOT visible in production. Data modifications are not permitted. * LOCKED_FOR_EDIT - This status indicates that this merchant record is locked for modification by the customer success team. Data modifications are not permitted.' example: LIVE locales: title: Merchant Locale Details minItems: 1 maxItems: 10 uniqueItems: true type: array description: Merchant Locale Details items: $ref: '#/components/schemas/LocaleResource' locations: title: Merchant Location Details minItems: 0 maxItems: 50 uniqueItems: true type: array description: Merchant Location details deprecated: true nullable: true items: $ref: '#/components/schemas/LocationResource' contentTypes: title: Content Types uniqueItems: true type: array description: An indicator as to the type of products and services you offer. example: - ADULT_LANGUAGE items: type: string nullable: true validationStatus: $ref: '#/components/schemas/ValidationStatus' crm: $ref: '#/components/schemas/CrmResource' businessType: title: Merchant Business Type type: string description: Business type describes the legal structure under which the business operates minLength: 1 maxLength: 25 example: BUSINESS_CORPORATION firstPartyTrustEnrollments: title: First Party Trust Enrollments description: A list of First Party Trust Enrollments type: array uniqueItems: true minLength: 0 maxLength: 2 nullable: true items: $ref: '#/components/schemas/FirstPartyTrustEnrollmentResource' CardAcceptorId: title: Card Acceptor's ID (CAID) description: Identifies the card acceptor ID assigned by the acquirer. This ID must represent a unique identifier for each merchant name/location within the acquirer BIN. This is represented by Mastercard DE 42 and Visa Field 42. type: string minLength: 1 maxLength: 15 example: card_acceptor1 CrmResource: title: Customer Relationship Management Response description: Customer Relationship Management Response allOf: - $ref: '#/components/schemas/Crm' - type: object properties: sanctionScreeningStatus: title: Sanction Screening Status maxLength: 11 minLength: 6 type: string description: Indicates merchant's sanction screening status example: APPROVED default: DENIED billingAccountCreated: type: boolean description: Indicates whether a sub-merchant billing account has been set up in SalesForce example: true default: false salesforceAccountNumber: $ref: '#/components/schemas/SalesforceAccountNumber' ResponseHeader: type: object properties: totalRecords: type: integer format: int64 description: Total number of records found minimum: 0 maximum: 999999999 example: 500 totalPages: type: integer description: Total number of pages based on limit minimum: 0 maximum: 999999999 example: 10 currentPage: type: integer description: The current page number minimum: 1 maximum: 999999999 example: 2 responseTime: $ref: '#/components/schemas/ResponseTime' SearchField: type: object required: - searchFieldCards properties: searchParameter: title: Merchant API Search parameter type: string description: Merchant api search parameter example: ACQUIRER_REFERENCE_NUMBER nullable: true enum: - PAYMENT_TYPE - TRANSACTION_IDENTIFIER_VALUE - ACQUIRER_REFERENCE_NUMBER - TRANSACTION_DATE - CARD_FIRST_SIX - CARD_LAST_FOUR - ISSUER_AUTHORIZATION_CODE - TRANSACTION_AMOUNT - TRANSACTION_CURRENCY_CODE required: title: Required type: boolean description: If the search field is required example: true nullable: true searchFieldCards: $ref: '#/components/schemas/CardTypes' description: Schema for a Search Field SubMerchantIdentifier: title: Sub-Merchant Identifier maxLength: 100 minLength: 1 type: string description: The alphanumeric ID of the sub-merchant associated with the purchase details. Required for channel partner. example: GHF5F67DFSD468GJJXH78 Email: title: Email Address maxLength: 254 minLength: 1 type: string description: Email address example: john.doe@example.com format: email nullable: true PageableAcceptedAcquirerMerchantIdsResource: title: Pageable accepted acquirer reference ID & card acceptor ID pairs resource description: Pageable accepted acquirer reference ID & card acceptor ID pairs resource with pagination metadata properties: data: $ref: '#/components/schemas/AcceptedAcquirerMerchantIdsResource' metadata: $ref: '#/components/schemas/ClarityResponseHeader' CardAcceptorNamesBulk: title: Merchant Card Acceptor Names type: object required: - cardAcceptorNames properties: cardAcceptorNames: minItems: 1 maxItems: 250 type: array description: List of merchant card acceptors uniqueItems: true items: $ref: '#/components/schemas/CardAcceptorData' example: [] CardTypesResource: title: Card Types Response type: array uniqueItems: true description: A list of all of the card types that are accepted as a form of payment. items: type: string description: Type of card used for a transaction example: AMEX CountryCode: title: Country Code maxLength: 3 minLength: 3 type: string description: The [ISO 3166-1](https://www.iso.org/obp/ui/#search) alpha-3 compliant country code. example: CAN nullable: true LegalAddress: title: Legal Address description: Legal address of the merchant. required: - addressLine1 - countryCode - city - regionCode - postalCode - phone allOf: - $ref: '#/components/schemas/Address' - type: object properties: phone: title: Phone maxLength: 30 minLength: 3 type: string description: Phone number of the merchant's office example: 1-234-567-9991 Location: type: object required: - countryCode - defaultLocation allOf: - $ref: '#/components/schemas/LocationWithoutCardAcceptors' - properties: cardAcceptorNames: $ref: '#/components/schemas/CardAcceptors' Error: 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 VelocityControl: required: - period - negate type: object properties: maxTrans: minimum: 1 type: integer description: Maximum number of transactions allowed format: int32 example: 12 cumulativeLimit: minimum: 0 type: number description: Maximum allowed cumulative amount example: 1200 format: float period: minLength: 5 maxLength: 10 type: string description: Velocity period. Valid values are DAILY, WEEKLY, QUARTERLY, CONTINUOUS, MONTHLY, and YEARLY example: DAILY pattern: ^(DAILY|WEEKLY|QUARTERLY|CONTINUOUS|MONTHLY|YEARLY) availableBalance: minimum: 0 type: number description: The cumulative spend available for the velocity control for the specified period example: 1200 format: float currencyType: minLength: 4 maxLength: 8 type: string description: Type of the currency being used. Valid values are BASE and MERCHANT pattern: ^(BASE|MERCHANT) example: MERCHANT currencyCode: minLength: 3 maxLength: 3 pattern: ^[0-9]{3}$ type: string description: Mastercard supported International Organization for Standardization (ISO) 4217 currency codes example: '825' endDate: type: string format: date-time description: End date until which the control is valid, in ISO 8601 extended format "YYYY-MM-DDThh:mm:ss[.sss]Z", where [.sss] is optional and can be 1 to 3 digits example: '2020-10-06T11:09:42.10Z' negate: type: boolean description: Defines if the rules should be negated example: false description: The VelocityControl can limit the frequency, and the total cumulative amount of authorizations performed on the cardholders account within a specified time period CurfewControl: required: - days - fromTime - negate - toTime type: object properties: fromTime: minLength: 5 maxLength: 5 pattern: ^([01][0-9]|2[0-3]):([0-5][0-9])$ type: string description: The start time from which authorizations will be allowed example: 08:20 toTime: minLength: 5 maxLength: 5 pattern: ^([01][0-9]|2[0-3]):([0-5][0-9])$ type: string description: The end time at which authorizations will be allowed example: '11:00' timeZone: type: string description: Time zone of the from and to times example: UTC days: maxItems: 7 minItems: 1 type: array description: Days of week. Valid values are SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, and SATURDAY example: SUNDAY pattern: ^(SUNDAY|MONDAY|TUESDAY|WEDNESDAY|THURSDAY|FRIDAY|SATURDAY)$ items: type: string negate: type: boolean description: Defines if the rules should be negated example: false description: Curfew Control Vcn: allOf: - $ref: '#/components/schemas/Card' - properties: accountGuid: type: string format: uuid description: The globally unique identifier of the virtual card account example: 123e4567-e89b-12d3-a456-426614174000 description: type: string example: This is the description of what the VCN will be used for description: The description of what the VCN will be used for Token: allOf: - $ref: '#/components/schemas/Card' properties: accountGuid: type: string format: uuid description: The globally unique identifier of the token example: 123e4567-e89b-12d3-a456-426614174000 tokenUniqueRef: type: string maxLength: 64 description: The unique reference identifier of the token example: DE9JOVYK6FVSO8I32DLDPHGTC9NZ7SLKPVLMDQ0RRGK3WYD2 paymentAppInstanceId: type: string maxLength: 64 description: The unique app device identifier example: '128652974320250630' status: type: string pattern: ^(ACTIVE|SUSPENDED)$ description: Token Status. Valid values are ACTIVE and SUSPENDED example: ACTIVE TransactionLimitControl: required: - amount - negate type: object properties: amount: minimum: 0 type: number description: The limit that will apply on a per transaction basis example: 12 format: float negate: type: boolean description: Defines if the rules should be negated example: false description: The TransactionLimit control provides the ability to limit individual transaction authorizations to a maximum amount Error_2: type: object properties: Source: type: string example: source description: Source of error ReasonCode: type: string description: A unique constant identifying the error example: '123' Description: type: string example: Error desc description: Short description of the error Recoverable: type: boolean example: true description: Is recoverable error Details: type: string example: Detail information description: Optional detailed description of the issue UpdateVirtualCardAccount: type: object required: - expiry allOf: - $ref: '#/components/schemas/VcnUserDetail' - $ref: '#/components/schemas/UpdateVCN' - properties: realCardBillingCurrencyCode: pattern: ^[0-9]{3}$ type: string description: Currency code of the RCN example: '825' rules: $ref: '#/components/schemas/Controls' VirtualCardAccount: type: object required: - realCardAccountGuid - accountGuid allOf: - $ref: '#/components/schemas/VcnUserDetail' - $ref: '#/components/schemas/Vcn' - properties: realCardAccountGuid: type: string format: uuid description: The globally unique identifier of the real card account example: 123e4567-e89b-12d3-a456-426614174000 realCardBillingCurrencyCode: pattern: ^[0-9]{3}$ type: string description: Currency code of the RCN example: '825' rules: $ref: '#/components/schemas/Controls' MerchantIdControl: required: - acquirerId - acceptorId - negate type: object properties: acceptorId: minLength: 15 maxLength: 15 type: string description: The Merchant Id example: '123456789012345' acquirerId: minLength: 1 maxLength: 10 pattern: .*\S.* type: string description: The Acquiring Institution ID Code which identifies the acquiring institution (for example, merchant bank) or its agent example: '123456' negate: type: boolean description: Defines if the rules should be negated example: false description: The Merchant ID control provides the ability to limit authorizations to particular merchants ResourceIdentifier: description: A UUID which uniquely identifies a resource type: string format: uuid example: c63de020-a446-11eb-bcbc-0242ac130002 ValidityPeriodControl: required: - from - negate - to type: object properties: from: type: string format: date-time description: The start date from which the control is valid, in ISO 8601 extended format "YYYY-MM-DDThh:mm:ss[.sss]Z", where [.sss] is optional and can be 1 to 3 digits example: '2020-10-26T00:00:00Z' to: type: string format: date-time description: The end date till which the control is valid, in ISO 8601 extended format "YYYY-MM-DDThh:mm:ss[.sss]Z", where [.sss] is optional and can be 1 to 3 digits example: '2020-11-06T23:59:59Z' strictPreAuthCheck: type: boolean description: Defines if strict pre-auth check needs to be applied default: false example: true negate: type: boolean description: Defines if the rules should be negated example: false description: The ValidityPeriod control provides the ability to limit authorization activity to a defined time period MccControl: required: - mccs - negate type: object properties: negate: type: boolean description: Defines if the rules should be negated example: false mccs: minItems: 1 type: array description: List of merchant category codes example: - '1234' - '5678' items: type: string example: '1234' uniqueItems: true description: The Card Acceptor Business Codes (MCC) control can control the type of purchases for which a card is used Controls: type: array description: In Control Card Controls items: $ref: '#/components/schemas/Control' UserDetail: type: object required: - firstName - lastName - phone - email properties: firstName: type: string minLength: 1 maxLength: 100 pattern: .*\S.* description: First Name of User example: Emerson lastName: type: string minLength: 1 maxLength: 100 pattern: .*\S.* description: Last Name of User example: Bloggs phone: type: string minLength: 4 maxLength: 16 description: Phone number of User example: '+12345678910111' email: type: string minLength: 1 maxLength: 300 description: Email address of User example: emersonbloggs@gmail.com Card: type: object required: - accountNumber - expiry properties: accountNumber: type: string minLength: 12 maxLength: 19 pattern: ^[0-9]+ example: '1234567891234567' description: Card Account Number expiry: minLength: 7 maxLength: 7 type: string pattern: ^20[2-9][0-9]-(0[1-9]|1[012])$ description: Card expiry date in yyyy-MM format example: 2021-11 ErrorWrapper: type: object required: - Errors properties: Errors: $ref: '#/components/schemas/Errors_2' AgeingVelocityControl: required: - authorizationHoldDays - cumulativeLimit - timeZone - negate type: object properties: authorizationHoldDays: type: integer minimum: 0 maximum: 9999 description: Number of days an authorization holds before ageing off format: int32 example: 1234 cumulativeLimit: minimum: 0 type: number description: Maximum allowed cumulative amount example: 1000 format: float timeZone: type: string description: Time zone that is used for age-off calculations example: UTC-06:00 availableBalance: minimum: 0 type: number description: The cumulative spend available for the velocity control for the specified period example: 1000 format: float currencyType: minLength: 4 maxLength: 8 type: string description: Type of the currency being used. Valid values are BASE and MERCHANT example: MERCHANT pattern: ^(BASE|MERCHANT) currencyCode: minLength: 3 maxLength: 3 pattern: ^[0-9]{3}$ type: string description: Mastercard supported International Organization for Standardization (ISO) 4217 currency codes example: '825' negate: type: boolean description: Defines if the rules should be negated example: false description: The AgingVelocityControl provides the requester with the ability to set a notional credit line through the CumulativeControl. This control keeps track of the current remaining available credit and approves a transaction only if the requested amount is less than or equal to the remaining available credit AmountRangeControl: required: - currencyType - maxAmount - minAmount - negate type: object properties: minAmount: minimum: 0 type: number description: Minimum allowed amount format: float example: 1000 maxAmount: minimum: 0 type: number description: Maximum allowed amount format: float example: 10000 strictPreAuthCheck: type: boolean description: Defines if strict pre-auth check needs to be applied default: false example: true currencyType: minLength: 4 maxLength: 8 type: string description: Type of the currency being used. Valid values are BASE and MERCHANT example: MERCHANT pattern: ^(BASE|MERCHANT) currencyCode: minLength: 3 maxLength: 3 pattern: ^[0-9]{3}$ type: string description: Mastercard supported International Organization for Standardization (ISO) 4217 currency codes example: '825' negate: type: boolean description: Defines if the rules should be negated example: false description: The exact amount range control will approve a transaction only if the requested amount is equal or greater than MinAmount and less than or equal to MaxAmount. In other words, if Min Amount <= Amount <= Max Amount VcnUserDetail: type: object required: - firstName - lastName - phone properties: firstName: type: string minLength: 1 maxLength: 100 description: First Name of User example: Emerson lastName: type: string minLength: 1 maxLength: 100 description: Last Name of User example: Bloggs phone: type: string minLength: 4 maxLength: 16 description: Phone number of User example: '+13556434378' UpdateVCN: type: object properties: expiry: minLength: 7 maxLength: 7 type: string pattern: ^20[2-9][0-9]-(0[1-9]|1[012])$ description: Expiry date in yyyy-MM format example: 2021-11 description: type: string example: This is the description of what the VCN will be used for description: The description of what the VCN will be used for TokenUpdate: allOf: - $ref: '#/components/schemas/Card' properties: status: type: string pattern: ^(ACTIVE|SUSPENDED)$ description: Token Status. Valid values are ACTIVE and SUSPENDED example: ACTIVE TimeOfDayControl: required: - negate - timeZone - times type: object properties: times: maxItems: 7 minItems: 1 type: array description: Times of day items: $ref: '#/components/schemas/TimeOfDay' timeZone: type: string description: Time zone of the from and to times example: UTC negate: type: boolean description: Defines if the rules should be negated example: false description: The TimeOfDayControl provides the ability to limit authorization activity to defined time periods for each day Errors_2: type: object required: - Error properties: Error: $ref: '#/components/schemas/ErrorList' Control: type: object required: - action - alias description: In Control Rule properties: action: minLength: 1 maxLength: 1 type: string description: control rule actions. Valid values are A (Approve), D (Decline), W (Warn), P (Promo) and F (Forced) example: A alias: type: string description: control rule alias name. alias should be unique maxLength: 100 minLength: 1 pattern: .*\S.* example: DAILY LIMIT transactionLimits: type: array description: transaction limit controls provides the ability to limit individual transaction authorizations to a maximum amount uniqueItems: true items: $ref: '#/components/schemas/TransactionLimitControl' geographies: type: array description: geography controls provides the ability to control where a card is physically used uniqueItems: true items: $ref: '#/components/schemas/GeographyControl' velocities: type: array description: velocity controls can limit the frequency, and the total cumulative amount of authorizations performed on the cardholders account within a specified time period items: $ref: '#/components/schemas/VelocityControl' validityPeriods: type: array description: validity period controls items: $ref: '#/components/schemas/ValidityPeriodControl' amountRanges: type: array description: amount range controls items: $ref: '#/components/schemas/AmountRangeControl' merchantIds: type: array description: merchant id controls uniqueItems: true items: $ref: '#/components/schemas/MerchantIdControl' ageingVelocities: type: array description: ageing velocity controls items: $ref: '#/components/schemas/AgeingVelocityControl' curfews: type: array description: curfew controls allows you to limit authorization activity on a card to a certain time period during set days. You can also set the time zone for this control items: $ref: '#/components/schemas/CurfewControl' timeOfDays: type: array description: time of day controls provides the ability to limit authorization activity to defined time periods for each day items: $ref: '#/components/schemas/TimeOfDayControl' merchantCategories: type: array description: merchant category controls uniqueItems: true items: $ref: '#/components/schemas/MccControl' GeographyControl: required: - countryCodes - negate type: object properties: countryCodes: minItems: 1 type: array description: Country codes to be included in the rule items: type: string example: - '840' negate: type: boolean description: Defines if the rules should be negated example: false description: The GeographicControl provides the ability to control where a card is physically used ErrorList: type: array minItems: 1 items: $ref: '#/components/schemas/Error_2' TimeOfDay: required: - day - fromTime - toTime type: object properties: day: minLength: 6 maxLength: 9 type: string example: SUNDAY description: Days of week. Valid values are SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, and SATURDAY pattern: ^(SUNDAY|MONDAY|TUESDAY|WEDNESDAY|THURSDAY|FRIDAY|SATURDAY) fromTime: minLength: 5 maxLength: 5 pattern: ^([01][0-9]|2[0-3]):([0-5][0-9])$ type: string description: The start time from which authorizations will be allowed example: 08:21 toTime: minLength: 5 maxLength: 5 pattern: ^([01][0-9]|2[0-3]):([0-5][0-9])$ type: string description: The end time from which authorizations will be allowed example: '12:00' examples: 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: '' 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: '' 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: '' 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: '' PreconditionRequired: summary: Precondition Required for the request description: If the request doesn't contain the If-Match header, a PreconditionRequired error response is returned to the caller with HTTP Status code 428. value: Errors: Error: - Source: service ReasonCode: missing required header Description: If-Match, Recoverable: false Details: '' 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: '' 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/ PreconditionFailed: summary: Precondition Failed for the request description: If the Etag value sent in the If-Match header doesn't match with the hash of the merchant saved in the system, a PreconditionFailed error response is returned to the caller with HTTP Status code 412. value: Errors: Error: - Source: service ReasonCode: 'invalid data: If-Match' Description: Merchant has been modified by another user. Please refresh the merchant data and try again Recoverable: false Details: '' 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: '' 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: '' 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: '' 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: '' Token: value: accountNumber: '1234567891234567' expiry: 2021-11 accountGuid: 123e4567-e89b-12d3-a456-426614174000 tokenUniqueRef: DE9JOVYK6FVSO8I32DLDPHGTC9NZ7SLKPVLMDQ0RRGK3WYD2 paymentAppInstanceId: '128652974320250630' status: ACTIVE AuthorizationError: value: Errors: Error: - Source: token-management-service ReasonCode: authorization.missing Description: Error description Recoverable: true Details: Detail information NotFoundError: value: Errors: Error: - Source: token-management-service ReasonCode: not.found Description: Error description Recoverable: true Details: Detail information ForbiddenError: value: Errors: Error: - Source: token-management-service ReasonCode: authorization.forbidden Description: Error description Recoverable: true Details: Detail information UpdateUserCardAndControl: value: firstName: Emerson lastName: Bloggs phone: '+353871123456' expiry: 2021-11 description: This is the description of what the VCN will be used for realCardBillingCurrencyCode: '840' rules: - action: A alias: DAILY LIMIT transactionLimits: - amount: 12 negate: true geographies: - countryCodes: - USA negate: true velocities: - maxTrans: 12 cumulativeLimit: 1200 period: DAILY availableBalance: 1200 currencyType: MERCHANT currencyCode: '825' negate: true validityPeriods: - from: '2020-10-06T11:09:42.10Z' to: '2020-11-06T11:09:42.10Z' strictPreAuthCheck: true negate: true amountRanges: - minAmount: 1000 maxAmount: 10000 strictPreAuthCheck: true currencyType: MERCHANT currencyCode: '825' negate: true merchantIds: - acceptorId: '123456789012345' acquirerId: '123456' negate: true ageingVelocities: - authorizationHoldDays: 1234 cumulativeLimit: 1000 timeZone: UTC-06:00 currencyType: MERCHANT currencyCode: '825' negate: true curfews: - fromTime: 08:20 toTime: '11:00' timeZone: UTC days: - SUNDAY negate: true timeOfDays: - times: - day: SUNDAY fromTime: 08:21 toTime: '12:40' timeZone: UTC negate: true merchantCategories: - negate: true mccs: - 1234 - 5678 CardDetails: value: - firstName: Emerson lastName: Bloggs phone: '+353871123456' realCardAccountGuid: 123e4567-e89b-12d3-a456-426614174000 accountNumber: '1234567891234567' expiry: 2021-11 accountGuid: 123e4567-e89b-12d3-a456-426614174000 description: This is the description of what the VCN will be used for realCardBillingCurrencyCode: '840' rules: - action: A alias: DAILY LIMIT transactionLimits: - amount: 12 negate: true geographies: - countryCodes: - USA negate: true velocities: - maxTrans: 12 cumulativeLimit: 1200 period: DAILY availableBalance: 1200 currencyType: MERCHANT currencyCode: '825' endDate: '2020-10-06T11:09:42.10Z' negate: true validityPeriods: - from: '2020-10-06T11:09:42.10Z' to: '2020-11-06T11:09:42.10Z' strictPreAuthCheck: true negate: true amountRanges: - minAmount: 1000 maxAmount: 10000 strictPreAuthCheck: true currencyType: MERCHANT currencyCode: '825' negate: true merchantIds: - acceptorId: '123456789012345' acquirerId: '123456' negate: true ageingVelocities: - authorizationHoldDays: 1234 cumulativeLimit: 1000 timeZone: UTC-06:00 availableBalance: 1000 currencyType: MERCHANT currencyCode: '825' negate: true curfews: - fromTime: 08:20 toTime: '11:00' timeZone: UTC days: - SUNDAY negate: true timeOfDays: - times: - day: SUNDAY fromTime: 08:21 toTime: '12:40' timeZone: UTC negate: true merchantCategories: - negate: true mccs: - 1234 - 5678 BadRequestError: value: Errors: Error: - Source: token-management-service ReasonCode: invalid.parameter Description: Error description Recoverable: true Details: Detail information UserDetail: value: firstName: Emerson lastName: Bloggs phone: '+12345678910111' email: emersonbloggs@gmail.com TokenUpdate: value: accountNumber: '1234567891234567' expiry: 2021-11 status: ACTIVE responses: PageableAcceptedAcquirerMerchantIdsSuccess: description: Pageable accepted acquirer reference ID and card acceptor ID response content: application/json: schema: $ref: '#/components/schemas/PageableAcceptedAcquirerMerchantIdsResource' CardAcceptorNamesBulkSuccess: description: Card Acceptor Names response content: application/json: schema: $ref: '#/components/schemas/CardAcceptorNamesBulkResource' AcquirerMerchantIdsSuccess: description: Acquirer Reference ID and CardAcceptor ID response content: application/json: schema: $ref: '#/components/schemas/AcquirerMerchantIdsResource' LogoSuccess: description: Successful Operation content: application/json: schema: $ref: '#/components/schemas/LogoResource' SubMerchantSuccess: description: Successful Operation headers: Etag: required: true schema: $ref: '#/components/schemas/Etag' content: application/json: schema: $ref: '#/components/schemas/SubMerchantResource' LocationSuccess: description: Location response headers: Etag: required: true schema: $ref: '#/components/schemas/Etag' content: application/json: schema: $ref: '#/components/schemas/LocationWithoutCardAcceptorsResource' CardAcceptorSuccess: description: Card Acceptor response headers: Etag: required: true schema: $ref: '#/components/schemas/Etag' content: application/json: schema: $ref: '#/components/schemas/CardAcceptorDataResource' LocationsBulkSuccess: description: Locations response content: application/json: schema: $ref: '#/components/schemas/LocationsBulkResource' SuccessWithoutBody: description: Successful Operation LogoSuccessWithImage: description: Successful Operation content: application/json: schema: $ref: '#/components/schemas/LogoImageResource' Default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: ServerError: $ref: '#/components/examples/ServerError' PageableCardAcceptorNamesSuccess: description: Pageable card acceptor names resource with pagination metadata content: application/json: schema: $ref: '#/components/schemas/PageableCardAcceptorNamesResource' PageableLocationsSuccess: description: Pageable locations resource with pagination metadata content: application/json: schema: $ref: '#/components/schemas/PageableLocationsResource' PreconditionRequired: description: Pre Condition Failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: PreConditionFailed: $ref: '#/components/examples/PreconditionRequired' 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' 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' PreconditionFailed: description: Pre Condition Failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: PreConditionFailed: $ref: '#/components/examples/PreconditionFailed' UnauthorizedError: description: Authentication Required headers: WWW-Authenticate: description: Method of authentication schema: type: string content: application/json: examples: Unauthorized: $ref: '#/components/examples/AuthorizationError' schema: $ref: '#/components/schemas/ErrorWrapper' OKResponse: description: OK User: description: User details content: application/json: schema: $ref: '#/components/schemas/UserDetail' examples: UserDetail: $ref: '#/components/examples/UserDetail' ResourceNotFoundError: description: Resource Not Found content: application/json: examples: ResourceNotFound: $ref: '#/components/examples/NotFoundError' schema: $ref: '#/components/schemas/ErrorWrapper' Token: description: Token detail content: application/json: schema: $ref: '#/components/schemas/Token' examples: Token: $ref: '#/components/examples/Token' NOContentResponse: description: No Content ResourceCreated: description: Resource Created headers: Location: description: location of the resource schema: type: string ForbiddenError: description: Not Authorized content: application/json: examples: Forbidden: $ref: '#/components/examples/ForbiddenError' schema: $ref: '#/components/schemas/ErrorWrapper' VirtualCard: description: Virtual card details content: application/json: schema: $ref: '#/components/schemas/VirtualCardAccount' examples: VirtualCardAccount: $ref: '#/components/examples/CardDetails' VirtualCards: description: List of virtual cards content: application/json: schema: type: array items: $ref: '#/components/schemas/VirtualCardAccount' examples: UserCardsDetails: $ref: '#/components/examples/CardDetails' BadRequestError: description: Invalid Request content: application/json: examples: BadRequest: $ref: '#/components/examples/BadRequestError' schema: $ref: '#/components/schemas/ErrorWrapper' parameters: CardAcceptorNameSearchTextParam: name: search_text in: query required: false description: "Input field used as wild search against Card Acceptor. \nThe service searches for substring, following the %search_text% pattern.\n" schema: type: string maxLength: 100 example: Test ClarityPageNumberParam: name: page_number in: query required: false description: current page number schema: type: integer default: 0 minimum: 0 example: 2 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' IfMatch: name: If-Match in: header required: true example: '"842DFBC17F921E7716642B9164F3B22B"' description: If-Match is a request header which makes the request conditional. Client must send the corresponding value from the latest Etag response header received for this merchant. schema: $ref: '#/components/schemas/Etag' LocationIdParam: name: location_id in: path required: true example: Mxyz123 description: Unique identifier of location schema: $ref: '#/components/schemas/ResourceId' 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' ClaritySortDirectionParam: name: sort_direction in: query required: false description: Direction to sort the data using sort_field in response schema: type: string default: DESC enum: - ASC - DESC example: ASC AcquirerMerchantIdParam: name: acquirer_merchant_id in: path required: true example: Mxyz123 description: Unique identifier of Acquirer Reference Id and Card Acceptor Id Pair schema: $ref: '#/components/schemas/ResourceId' AcquirerMerchantIdsSearchTextParam: name: search_text in: query required: false description: 'Input field used as wild search against Acquirer Reference ID and Card Acceptor ID. The service searches for substring, following the %search_text% pattern. ' schema: type: string maxLength: 30 example: Test LocationSearchTextQueryParam: name: search_text in: query required: false description: Input field used as wild search in region/city/country like regex %search_text% schema: type: string maxLength: 100 example: Toronto AcquirerMerchantIdsSortFieldParam: name: sort_field in: query required: false description: Field to Sort data in response schema: type: string default: acquirerReferenceId maxLength: 30 example: acquirerReferenceId ClaritySortFieldParam: name: sort_field in: query required: false description: Field to Sort data in response schema: type: string default: modifiedDateTime maxLength: 100 example: modifiedDateTime ClarityOffsetParam: name: offset in: query required: false description: The number of items to skip before starting to collect the result set schema: type: integer default: 50 minimum: 0 example: 0 CardAcceptorNameIdParam: name: id in: path required: true example: Mxyz123 description: Unique identifier of the card acceptor name. schema: $ref: '#/components/schemas/ResourceId' tokenGUID: name: token_guid in: path description: The globally unique identifier of the token being queried required: true schema: $ref: '#/components/schemas/ResourceIdentifier' example: 8f242496-b71a-11eb-8529-0242ac130003 accountGUID: name: account_guid in: path description: The globally unique identifier of the card being queried required: true schema: $ref: '#/components/schemas/ResourceIdentifier' example: 8f242496-b71a-11eb-8529-0242ac130003 userGUID: name: user_guid in: path description: The globally unique identifier of the user being queried required: true schema: $ref: '#/components/schemas/ResourceIdentifier' example: 8f242496-b71a-11eb-8529-0242ac130003 requestBodies: CardAcceptorNamesBulkRequestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardAcceptorNamesBulk' MerchantLogoBody: required: true content: application/json: schema: $ref: '#/components/schemas/MerchantLogo' AcquirerMerchantIdsRequestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AcquirerMerchant' CardAcceptorNamesBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardAcceptorData' LocationsBulkRequestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LocationsBulk' 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 LocationBody: required: true content: application/json: schema: $ref: '#/components/schemas/LocationWithoutCardAcceptors' SubMerchantBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubMerchant' User: required: true content: application/json: schema: $ref: '#/components/schemas/UserDetail' examples: UserDetail: $ref: '#/components/examples/UserDetail' NewToken: required: true content: application/json: schema: $ref: '#/components/schemas/Token' examples: Token: $ref: '#/components/examples/Token' UpdatedToken: required: true content: application/json: schema: $ref: '#/components/schemas/TokenUpdate' examples: TokenUpdate: $ref: '#/components/examples/TokenUpdate' NewVirtualCard: required: true content: application/json: schema: $ref: '#/components/schemas/VirtualCardAccount' examples: VirtualCardAccount: $ref: '#/components/examples/CardDetails' UpdatedVirtualCard: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateVirtualCardAccount' examples: UpdateVirtualCardAccount: $ref: '#/components/examples/UpdateUserCardAndControl'