Merchant
Correlation Id for the request
Success
Server Error
GET /api/demographics/v1/Merchants HTTP/1.1
Host: localhost:5000
Accept: */*
{
"content": {
"content": [
{
"_links": {
"business": {
"href": "/api/Demographics/v1.0/Merchants/1234567812345678"
}
},
"hierarchyNodeKey": "1234567800000001",
"dbaName": "Sandbox Merchant 1",
"merchantNumber": "1234567812345678"
},
{
"_links": {
"business": {
"href": "/api/Demographics/v1.0/Merchants/1234567812345679"
}
},
"hierarchyNodeKey": "1234567800000001",
"dbaName": "Sandbox Merchant 2",
"merchantNumber": "1234567812345679"
},
{
"_links": {
"business": {
"href": "/api/Demographics/v1.0/Merchants/1234567812345680"
}
},
"hierarchyNodeKey": "1234567800000001",
"dbaName": "Sandbox Merchant 3",
"merchantNumber": "1234567812345680"
},
{
"_links": {
"business": {
"href": "/api/Demographics/v1.0/Merchants/1234567812345681"
}
},
"hierarchyNodeKey": "1234567800000001",
"dbaName": "Sandbox Merchant 4",
"merchantNumber": "1234567812345681"
},
{
"_links": {
"business": {
"href": "/api/Demographics/v1.0/Merchants/1234567812345682"
}
},
"hierarchyNodeKey": "1234567800000001",
"dbaName": "Sandbox Merchant 5",
"merchantNumber": "1234567812345682"
},
{
"_links": {
"business": {
"href": "/api/Demographics/v1.0/Merchants/1234567812345683"
}
},
"hierarchyNodeKey": "1234567800000001",
"dbaName": "Sandbox Merchant 6",
"merchantNumber": "1234567812345683"
},
{
"_links": {
"business": {
"href": "/api/Demographics/v1.0/Merchants/1234567812345684"
}
},
"hierarchyNodeKey": "1234567800000001",
"dbaName": "Sandbox Merchant 7",
"merchantNumber": "1234567812345684"
},
{
"_links": {
"business": {
"href": "/api/Demographics/v1.0/Merchants/1234567812345685"
}
},
"hierarchyNodeKey": "1234567800000001",
"dbaName": "Sandbox Merchant 8",
"merchantNumber": "1234567812345685"
},
{
"_links": {
"business": {
"href": "/api/Demographics/v1.0/Merchants/1234567812345686"
}
},
"hierarchyNodeKey": "1234567800000001",
"dbaName": "Sandbox Merchant 9",
"merchantNumber": "1234567812345686"
},
{
"_links": {
"business": {
"href": "/api/Demographics/v1.0/Merchants/1234567812345687"
}
},
"hierarchyNodeKey": "Not Available",
"dbaName": "Sandbox Merchant 10",
"merchantNumber": "1234567812345687"
}
],
"page": {
"number": 2,
"size": 10,
"sort": {
"fields": {}
},
"totalPages": 21,
"numberOfElements": 10,
"totalElements": 204,
"first": false,
"last": false
}
},
"metadata": {
"exchangeId": "ID-c434347f-4893-42bb-866b-47f1b049297d",
"timestamp": "2024-09-08T17:30:04.7388825Z"
}
}This endpoint allows the creation of a new merchant. It validates the provided business model for essential fields like DbaName, HierarchyNodeKey, and UserName. Additional checks ensure compliance with business rules and configurations, such as paper statement preferences and MCC code validations. If validation passes, the merchant is created, and changes are safely queued for further processing. The response includes the newly created merchant's details.
Correlation Id for the request
The unique identifier for the business.
524398752The key representing the hierarchy node to which the business belongs.
7412523The Doing-Business-As (DBA) name of the merchant.
Jane's SandwichesThe merchant's unique identification number.
987654321The website of the business.
https:/www.janessandwiches.comIndicates whether the business accepts paper statements.
trueIndicates whether the business accepts paper tax forms.
falseThe identifier representing the type of the company.
2Indicates whether the business is part of a chain of merchants.
falseCreated a merchant successfully.
Bad Request: Validation failed due to missing or invalid information (e.g., DBA Name, HierarchyNodeKey, or MCC code).
Unauthorized: User does not have the required role or access.
Internal Server Error: This could be due to system errors. Please contact support for assistance
POST /api/demographics/v1/Merchants HTTP/1.1
Host: localhost:5000
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 719
{
"businessID": 524398752,
"hierarchyNodeKey": "7412523",
"dbaName": "Jane's Sandwiches",
"merchantNumber": "987654321",
"emailAddress": "[email protected]",
"webSite": "https:/www.janessandwiches.com",
"phones": [
{
"phoneTypeCodeID": 1,
"areaCode": "415",
"phoneNumber": "5551234",
"extension": "101"
}
],
"acceptsPaperStatements": true,
"acceptsPaperTaxForms": false,
"companyTypeId": 2,
"isChainMerchant": false,
"seasonalSchedule": {
"january": true,
"february": false,
"march": true,
"april": true,
"may": true,
"june": false,
"july": true,
"august": true,
"september": false,
"october": true,
"november": true,
"december": false
},
"salesInformation": {
"salesInformationID": 1001,
"businessID": 2002,
"assignedUser": 3003,
"referralPartner": "John Doe",
"compensationType": 2
}
}{
"_links": {
"self": {
"href": "/api/demographics/v1.0/merchants/987654321"
}
},
"businessID": 524398752,
"hierarchyNodeKey": "7412523",
"dbaName": "Jane's Sandwiches",
"merchantNumber": "987654321",
"emailAddress": "[email protected]",
"webSite": "https:/www.janessandwiches.com",
"phones": [
{
"phoneTypeCodeID": 1,
"areaCode": "415",
"phoneNumber": "5551234",
"extension": "101"
}
],
"acceptsPaperStatements": true,
"acceptsPaperTaxForms": false,
"companyTypeId": 2,
"isChainMerchant": false,
"seasonalSchedule": {
"january": true,
"february": false,
"march": true,
"april": true,
"may": true,
"june": false,
"july": true,
"august": true,
"september": false,
"october": true,
"november": true,
"december": false
},
"salesInformation": {
"salesInformationID": 1001,
"businessID": 2002,
"assignedUser": 3003,
"referralPartner": "John Doe",
"compensationType": 2
}
}Merchant number.
Correlation Id for the request
Returns a single merchant successfully.
If merchantNumber is null or white space.
If merchant is not found.
Error occurred returning merchant.
GET /api/demographics/v1/Merchants/{merchantNumber} HTTP/1.1
Host: localhost:5000
Accept: */*
{
"_links": {
"self": {
"href": "/api/demographics/v1.0/merchants/987654321"
}
},
"businessID": 524398752,
"hierarchyNodeKey": "7412523",
"dbaName": "Jane's Sandwiches",
"merchantNumber": "987654321",
"emailAddress": "[email protected]",
"webSite": "https:/www.janessandwiches.com",
"phones": [
{
"phoneTypeCodeID": 1,
"areaCode": "415",
"phoneNumber": "5551234",
"extension": "101"
}
],
"acceptsPaperStatements": true,
"acceptsPaperTaxForms": false,
"companyTypeId": 2,
"isChainMerchant": false,
"seasonalSchedule": {
"january": true,
"february": false,
"march": true,
"april": true,
"may": true,
"june": false,
"july": true,
"august": true,
"september": false,
"october": true,
"november": true,
"december": false
},
"salesInformation": {
"salesInformationID": 1001,
"businessID": 2002,
"assignedUser": 3003,
"referralPartner": "John Doe",
"compensationType": 2
}
}This endpoint updates the details of an existing merchant based on the provided merchantNumber and business object. If the merchant is locked, the update may be staged rather than applied immediately. Queues a merchant change event after a successful update
MerchantNumber used to update.
Correlation Id for the request
The unique identifier for the business.
524398752The key representing the hierarchy node to which the business belongs.
7412523The Doing-Business-As (DBA) name of the merchant.
Jane's SandwichesThe merchant's unique identification number.
987654321The website of the business.
https:/www.janessandwiches.comIndicates whether the business accepts paper statements.
trueIndicates whether the business accepts paper tax forms.
falseThe identifier representing the type of the company.
2Indicates whether the business is part of a chain of merchants.
falseUpdates a merchant successfully.
Accepted: Request change was accepted.
Bad Request: If merchant number is null/empty or business object is null or If data is invalid or MCC code not found.
Unauthorized: User does not have the required role or access.
Not Found: Resource not found exception.
Conflict: Request change was rejected because there is another one.
Internal Server Error: This could be due to system errors. Please contact support for assistance.
PUT /api/demographics/v1/Merchants/{merchantNumber} HTTP/1.1
Host: localhost:5000
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 719
{
"businessID": 524398752,
"hierarchyNodeKey": "7412523",
"dbaName": "Jane's Sandwiches",
"merchantNumber": "987654321",
"emailAddress": "[email protected]",
"webSite": "https:/www.janessandwiches.com",
"phones": [
{
"phoneTypeCodeID": 1,
"areaCode": "415",
"phoneNumber": "5551234",
"extension": "101"
}
],
"acceptsPaperStatements": true,
"acceptsPaperTaxForms": false,
"companyTypeId": 2,
"isChainMerchant": false,
"seasonalSchedule": {
"january": true,
"february": false,
"march": true,
"april": true,
"may": true,
"june": false,
"july": true,
"august": true,
"september": false,
"october": true,
"november": true,
"december": false
},
"salesInformation": {
"salesInformationID": 1001,
"businessID": 2002,
"assignedUser": 3003,
"referralPartner": "John Doe",
"compensationType": 2
}
}{
"_links": {
"self": {
"href": "/api/demographics/v1.0/merchants/987654321"
}
},
"businessID": 524398752,
"hierarchyNodeKey": "7412523",
"dbaName": "Jane's Sandwiches",
"merchantNumber": "987654321",
"emailAddress": "[email protected]",
"webSite": "https:/www.janessandwiches.com",
"phones": [
{
"phoneTypeCodeID": 1,
"areaCode": "415",
"phoneNumber": "5551234",
"extension": "101"
}
],
"acceptsPaperStatements": true,
"acceptsPaperTaxForms": false,
"companyTypeId": 2,
"isChainMerchant": false,
"seasonalSchedule": {
"january": true,
"february": false,
"march": true,
"april": true,
"may": true,
"june": false,
"july": true,
"august": true,
"september": false,
"october": true,
"november": true,
"december": false
},
"salesInformation": {
"salesInformationID": 1001,
"businessID": 2002,
"assignedUser": 3003,
"referralPartner": "John Doe",
"compensationType": 2
}
}This endpoint is used to delete a merchant record. The operation includes multiple validation steps to ensure the request is valid and secure. It validates the provided merchantNumber and checks if the merchant is locked. If the merchant is locked and changes are not allowed, the request is rejected. It stages changes before processing the deletion, ensuring that the operation adheres to business rules. It also handles the deletion process securely by updating the merchant's lifecycle status and safely queuing changes.
MerchantNumber used for deleting record.
Correlation Id for the request
Deletes a merchant successfully.
No content
Accepted: Changes are staged and will be processed asynchronously.
Bad Request: MerchantNumber is null/empty or operation is invalid due to locked status response.
Unauthorized: User does not have the required role or access.
Forbidden: The user does not have the necessary permissions to access this resource.
Not Found: Merchant not found.
Internal Server Error: This could be due to system errors. Please contact support for assistance.
DELETE /api/demographics/v1/Merchants/{merchantNumber} HTTP/1.1
Host: localhost:5000
Accept: */*
No content
This endpoint retreives the primary address, which is the merchant’s physical location. The accuracy of the address provded is verified via a secure access using the "MID" authorization policy. Response includes fields such as StateCode, Zip and CountryCode, etc with other information.
MerchantNumber used to get physical address.
Correlation Id for the request
Returns a merchant's physical address successfully.
Bad Request: If merchant number is null/empty.
Unauthorized: User does not have the required role or access.
Forbidden: The user does not have the necessary permissions to access this resource.
Not Found: Business Physical address not found for MerchantNumber provided.
Internal Server Error: This could be due to system errors. Please contact support for assistance
GET /api/demographics/v1/MerchantPhysicalAddresses/{merchantNumber} HTTP/1.1
Host: localhost:5000
Accept: */*
{
"stateCode": "CA",
"zip": "90001",
"countryCode": 1,
"line1": "123 Main Street",
"line2": "Apt 4B",
"line3": "Near statue",
"city": "Los Angeles"
}This endpoint updates the physical address of the record identified by the merchant number provided. The address details to be updated are extracted from the request body. The accuracy of the address provded is verified via a secure access using the "MID" authorization policy.
MerchantNumber used to update the physical address.
Correlation Id for the request
Represents the physical address of a business.
The state code where the business is located. The code is a two-letter abbreviation.
CAThe zip code of the business's physical address.
90001The country code representing the country where the business is located.
1The first line of the business's physical address (e.g., street address).
123 Main StreetThe second line of the business's physical address (optional, for apartment, suite, etc.).
Apt 4BThe third line of the business's physical address (optional).
Near statueThe city where the business is located.
Los AngelesUpdates a merchant's physical address successfully.
Accepted: Request change is accepted.
Bad Request: If merchant number is null/empty or physicalAddress is null or If data is invalid.
Unauthorized: User does not have the required role or access.
Forbidden: The user does not have the necessary permissions to access this resource.
Not Found: If merchant or its physical address not found.
Conflict: Request change is rejected because there is another one.
Internal Server Error: This could be due to system errors. Please contact support for assistance
PUT /api/demographics/v1/MerchantPhysicalAddresses/{merchantNumber} HTTP/1.1
Host: localhost:5000
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 134
{
"stateCode": "CA",
"zip": "90001",
"countryCode": 1,
"line1": "123 Main Street",
"line2": "Apt 4B",
"line3": "Near statue",
"city": "Los Angeles"
}{
"stateCode": "CA",
"zip": "90001",
"countryCode": 1,
"line1": "123 Main Street",
"line2": "Apt 4B",
"line3": "Near statue",
"city": "Los Angeles"
}This endpoint retrieves the merchant's mailing address using the provided merchant number. The merchant number must be valid and exist in the system for the request to succeed. It is secured with the "MID" authorization policy and requires the "getaddress" entitlement for access. The response includes the mailing address details such as StateCode, Zip, and CountryCode etc.
MerchantNumber used to get mailing address.
Correlation Id for the request
Returns a merchant's mailing address successfully.
Bad Request: If merchantNumber is null/empty or mailingAddress is null or If data is invalid.
Unauthorized: User does not have the required role or access.
Forbidden: The user does not have the necessary permissions to access this resource.
Not Found: If merchant or its mailing address not found.
Internal Server Error: This could be due to system errors. Please contact support for assistance.
GET /api/demographics/v1/MerchantMailingAddresses/{merchantNumber} HTTP/1.1
Host: localhost:5000
Accept: */*
{
"stateCode": "CA",
"zip": "90001",
"countryCode": 10,
"line1": "123 Main St",
"line2": "Apt 4B",
"line3": "Building C",
"city": "Los Angeles"
}This endpoint updates the mailing address of the record identified by the merchant number provided. The mailing address specifies the address for official correspondence, even if it matches the physical address. The address details to be updated are extracted from the request body.
MerchantNumber used to update the mailing address.
Correlation Id for the request
The state code of the mailing address (2 digits).
CAThe zip code of the mailing address.
90001The country code representing the country of the mailing address. (Any code between 1 and 840)
10The first line of the mailing address.
123 Main StThe second line of the mailing address (optional).
Apt 4BThe third line of the mailing address (optional).
Building CThe city of the mailing address.
Los AngelesUpdates a merchant's mailing address successfully.
Accepted: Request change was accepted.
Bad Request: If merchant number is null/empty or merchant mailing Address cannot be updated.
Unauthorized: User does not have the required role or access.
Forbidden: The user does not have the necessary permissions to access this resource.
Not Found: If merchant not found.
Conflict: Request change was rejected because there is another one.
Internal Server Error: This could be due to system errors. Please contact support for assistance.
PUT /api/demographics/v1/MerchantMailingAddresses/{merchantNumber} HTTP/1.1
Host: localhost:5000
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 130
{
"stateCode": "CA",
"zip": "90001",
"countryCode": 10,
"line1": "123 Main St",
"line2": "Apt 4B",
"line3": "Building C",
"city": "Los Angeles"
}{
"stateCode": "CA",
"zip": "90001",
"countryCode": 10,
"line1": "123 Main St",
"line2": "Apt 4B",
"line3": "Building C",
"city": "Los Angeles"
}Was this helpful?