GithubSupport CenterStatus pageBecome a Partner

Merchant

get
Query parameters
PageSizeinteger · int32 · min: 1 · max: 2147483647Required
PageNumberinteger · int32 · min: 1 · max: 2147483647Required
Header parameters
exchangeIdstringOptional

Correlation Id for the request

Responses
200
Success
application/json
get
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"
  }
}

Creates a new Merchant

post

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.

Header parameters
exchangeIdstringOptional

Correlation Id for the request

Body
businessIDinteger · int32Optional

The unique identifier for the business.

Example: 524398752
hierarchyNodeKeystringRequired

The key representing the hierarchy node to which the business belongs.

Example: 7412523
dbaNamestringRequired

The Doing-Business-As (DBA) name of the merchant.

Example: Jane's Sandwiches
merchantNumberstring | nullableOptional

The merchant's unique identification number.

Example: 987654321
emailAddressstring | nullableOptional

The email address of the business.

Example: [email protected]
webSitestring | nullableOptional

The website of the business.

Example: https:/www.janessandwiches.com
acceptsPaperStatementsboolean | nullableOptional

Indicates whether the business accepts paper statements.

Example: true
acceptsPaperTaxFormsboolean | nullableOptional

Indicates whether the business accepts paper tax forms.

Example: false
companyTypeIdinteger · int32 · min: 1 · max: 2147483647Required

The identifier representing the type of the company.

Example: 2
isChainMerchantbooleanOptional

Indicates whether the business is part of a chain of merchants.

Example: false
Responses
201
Created a merchant successfully.
application/json
post
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
  }
}

Get Merchant

get
Path parameters
merchantNumberstringRequired

Merchant number.

Header parameters
exchangeIdstringOptional

Correlation Id for the request

Responses
200
Returns a single merchant successfully.
application/json
get
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
  }
}

Updates a Merchant details

put

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

Path parameters
merchantNumberstringRequired

MerchantNumber used to update.

Header parameters
exchangeIdstringOptional

Correlation Id for the request

Body
businessIDinteger · int32Optional

The unique identifier for the business.

Example: 524398752
hierarchyNodeKeystringRequired

The key representing the hierarchy node to which the business belongs.

Example: 7412523
dbaNamestringRequired

The Doing-Business-As (DBA) name of the merchant.

Example: Jane's Sandwiches
merchantNumberstring | nullableOptional

The merchant's unique identification number.

Example: 987654321
emailAddressstring | nullableOptional

The email address of the business.

Example: [email protected]
webSitestring | nullableOptional

The website of the business.

Example: https:/www.janessandwiches.com
acceptsPaperStatementsboolean | nullableOptional

Indicates whether the business accepts paper statements.

Example: true
acceptsPaperTaxFormsboolean | nullableOptional

Indicates whether the business accepts paper tax forms.

Example: false
companyTypeIdinteger · int32 · min: 1 · max: 2147483647Required

The identifier representing the type of the company.

Example: 2
isChainMerchantbooleanOptional

Indicates whether the business is part of a chain of merchants.

Example: false
Responses
200
Updates a merchant successfully.
application/json
put
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
  }
}

Deletes a Merchant record

delete

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.

Path parameters
merchantNumberstringRequired

MerchantNumber used for deleting record.

Header parameters
exchangeIdstringOptional

Correlation Id for the request

Responses
200
Deletes a merchant successfully.
delete
DELETE /api/demographics/v1/Merchants/{merchantNumber} HTTP/1.1
Host: localhost:5000
Accept: */*

No content

Retrieves the Physical Address

get

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.

Path parameters
merchantNumberstringRequired

MerchantNumber used to get physical address.

Header parameters
exchangeIdstringOptional

Correlation Id for the request

Responses
200
Returns a merchant's physical address successfully.
application/json
get
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"
}

Updates the Physical Address.

put

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.

Path parameters
merchantNumberstringRequired

MerchantNumber used to update the physical address.

Header parameters
exchangeIdstringOptional

Correlation Id for the request

Body

Represents the physical address of a business.

stateCodestring · min: 2 · max: 2Required

The state code where the business is located. The code is a two-letter abbreviation.

Example: CA
zipstringRequired

The zip code of the business's physical address.

Example: 90001
countryCodeinteger · int32 · min: 1 · max: 840Required

The country code representing the country where the business is located.

Example: 1
line1stringRequired

The first line of the business's physical address (e.g., street address).

Example: 123 Main Street
line2string | nullableOptional

The second line of the business's physical address (optional, for apartment, suite, etc.).

Example: Apt 4B
line3string | nullableOptional

The third line of the business's physical address (optional).

Example: Near statue
citystringRequired

The city where the business is located.

Example: Los Angeles
Responses
200
Updates a merchant's physical address successfully.
application/json
put
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"
}

Retrieves the Mailing Address

get

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.

Path parameters
merchantNumberstringRequired

MerchantNumber used to get mailing address.

Header parameters
exchangeIdstringOptional

Correlation Id for the request

Responses
200
Returns a merchant's mailing address successfully.
application/json
get
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"
}

Updates the Mailing Address.

put

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.

Path parameters
merchantNumberstringRequired

MerchantNumber used to update the mailing address.

Header parameters
exchangeIdstringOptional

Correlation Id for the request

Body
stateCodestring · min: 2 · max: 2Required

The state code of the mailing address (2 digits).

Example: CA
zipstringRequired

The zip code of the mailing address.

Example: 90001
countryCodeinteger · int32 · min: 1 · max: 840Required

The country code representing the country of the mailing address. (Any code between 1 and 840)

Example: 10
line1stringRequired

The first line of the mailing address.

Example: 123 Main St
line2string | nullableOptional

The second line of the mailing address (optional).

Example: Apt 4B
line3string | nullableOptional

The third line of the mailing address (optional).

Example: Building C
citystringRequired

The city of the mailing address.

Example: Los Angeles
Responses
200
Updates a merchant's mailing address successfully.
application/json
put
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"
}
PreviousDocumentsNextReferences

Was this helpful?