List merchant platforms

Browse API reference

GET/merchant-platformslistMerchantPlatforms

Use this method to return a paginated list of merchant platforms that are linked to your ISV account.

Note: If you want to view the details of a specific merchant platform and you have its merchantPlatformId, use our Retrieve Merchant Platform method.

Our gateway returns the following information about each merchant platform in the list:

Legal information, including its legal name and address.
Contact information, including the email address for the business.
Processing account information, including the processingAccountId and status of each processing account that's linked to the merchant platform.

For each merchant platform, we also return its merchantPlatformId and its linked processingAccountIds, which you can use to perform follow-on actions.

Parameters

Name	In	Type	Description
`before`	query	`string`	Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter.
`after`	query	`string`	Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter.
`limit`	query	`integer`	Limit the maximum number of results that we return for each page.

Responses

Successful request. Returns a list of merchant platforms associated with the ISV's account.

200 OK · application/json

{
  "count": 2,
  "data": [
    {
      "business": {
        "addresses": [
          {
            "address1": "1 Example Ave.",
            "address2": "Example Address Line 2",
            "address3": "Example Address Line 3",
            "city": "Chicago",
            "country": "US",
            "postalCode": "60056",
            "state": "Illinois",
            "type": "legalAddress"
          }
        ],
        "contactMethods": [
          {
            "type": "email",
            "value": "example-corp@example.com"
          },
          {
            "type": "phone",
            "value": "123 456 7890"
          }
        ],
        "countryOfOperation": "US",
        "name": "Example Corp",
        "organizationType": "privateCorporation",
        "taxId": "xxxxx6789"
      },
      "createdDate": "2024-07-02T12:00:00.000+00:00",
      "lastModifiedDate": "2024-07-02T12:00:00.000+00:00",
      "merchantPlatformId": "12345",
      "processingAccounts": [
        {
          "addendums": [],
          "doingBusinessAs": "Pizza Doe",
          "link": {
            "href": "https://api.payroc.com/v1/processing-accounts/38765",
            "method": "get",
            "rel": "processingAccount"
          },
          "processingAccountId": "38765",
          "processor": "tsys",
          "signature": {
            "link": {
              "href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000",
              "method": "get",
              "rel": "agreement"
            },
            "type": "requestedViaDirectLink"
          },
          "status": "pending"
        }
      ]
    },
    {
      "business": {
        "addresses": [
          {
            "address1": "1 Example Ave.",
            "address2": "Example Address Line 2",
            "address3": "Example Address Line 3",
            "city": "Chicago",
            "country": "US",
            "postalCode": "60056",
            "state": "Illinois",
            "type": "legalAddress"
          }
        ],
        "contactMethods": [
          {
            "type": "email",
            "value": "example-corp@example.com"
          },
          {
            "type": "phone",
            "value": "123 456 7890"
          }
        ],
        "countryOfOperation": "US",
        "name": "Example Corp",
        "organizationType": "privateCorporation",
        "taxId": "xxxxx6789"
      },
      "createdDate": "2024-07-02T12:00:00.000+00:00",
      "lastModifiedDate": "2024-07-02T12:00:00.000+00:00",
      "merchantPlatformId": "12346",
      "processingAccounts": [
        {
          "addendums": [],
          "doingBusinessAs": "Doe Hot Dogs",
          "link": {
            "href": "https://api.payroc.com/v1/processing-accounts/38766",
            "method": "get",
            "rel": "processingAccount"
          },
          "processingAccountId": "38766",
          "processor": "tsys",
          "signature": {
            "link": {
              "href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000001",
              "method": "get",
              "rel": "agreement"
            },
            "type": "requestedViaDirectLink"
          },
          "status": "pending"
        }
      ]
    }
  ],
  "hasMore": true,
  "limit": 2,
  "links": [
    {
      "href": "https://api.payroc.com/v1/merchant-platforms?before=12345&limit=2",
      "method": "get",
      "rel": "previous"
    },
    {
      "href": "https://api.payroc.com/v1/merchant-platforms?after=12346&limit=2",
      "method": "get",
      "rel": "next"
    }
  ]
}

Response schema · 137 fields

countinteger
Number of results we returned on this page. Note: This might not be the total number of results that match your query.
hasMoreboolean
Indicates whether there is another page of results available.
limitinteger
Maximum number of results that we return for each page.
linksobject[]
Reference links to navigate to the previous page of results or to the next page of results.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
dataobject[]
Array of merchantPlatform objects.
- businessobjectrequired
  Object that contains information about the business.
  - addressesobject[]required
    Array of polymorphic objects that contain address information for the business.≥ 1 items
    legalAddressobject
    Type of address.
    typestringrequired
    Type of address.legalAddress
    address1stringrequired
    Address line 1.≤ 150 chars
    address2string
    Address line 2.≤ 150 chars
    address3string
    Address line 3.≤ 150 chars
    citystringrequired
    City.≤ 50 chars
    countrystringrequired
    Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
    postalCodestringrequired
    Zip code or postal code.≤ 10 chars
    statestringrequired
    Name of the state or state abbreviation.≤ 50 chars
  - contactMethodsobject[]required
    Array of polymorphic objects, which contain contact information. Note: You must provide an email address. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number≥ 1 items
    emailobject
    typestringrequired
    Type of contact method.email
    valuestringrequired
    Email address.≤ 50 chars
    phoneobject
    typestringrequired
    Type of contact method.phone
    valuestringrequired
    Phone number.≤ 15 chars
    mobileobject
    typestringrequired
    Type of contact method.mobile
    valuestringrequired
    Mobile number.≤ 15 chars
    faxobject
    typestringrequired
    Type of contact method.fax
    valuestringrequired
    Fax number.≤ 15 chars
  - countryOfOperationstring
    Two-digit code for the country that the business operates in. The format follows the ISO-3166 standard.US
  - namestringrequired
    Legal name of the business.≤ 100 chars
  - organizationTypestringrequired
    Type of organization.privateCorporationpublicCorporationnonProfitprivateLlcpublicLlcprivatePartnershippublicPartnershipsoleProprietor
  - taxIdstringrequired
    Tax ID of the business.≤ 20 chars
- createdDatestringdate-time
  Date that the merchant platform was created. We return this value in the ISO-8601 format.
- lastModifiedDatestringdate-time
  Date that the merchant platform was last modified. We return this value in the ISO-8601 format.
- linksobject[]
  Array of useful links related to your request.
  - hrefstringrequired
    URL of the target resource.
  - methodstringrequired
    HTTP method that you need to use with the target resource.
  - relstringrequired
    Indicates the relationship between the current resource and the target resource.
- merchantPlatformIdstring
  Unique identifier that we assigned to the merchant platform.
- metadataobject
  Object that you can send to include custom metadata in the request.
- processingAccountsobject[]required
  Array of processingAccount objects.
  - addendumsobject[]required
    The addendum types that were accepted and appended to the Merchant Processing Agreement for this processing account. Returns an empty array when no addendums were requested.
    option 1object
    Installment Payments, Loans, or Lease Questionnaire/Attestation for merchants that offer installment payments, loans, or leases.
    typestringrequired
    option 2object
    Money Services Business Questionnaire for merchants that offer money services, for example, traveler's checks.
    typestringrequired
    option 3object
    Telehealth Attestation for merchants that provide telehealth services.
    typestringrequired
    option 4object
    Firearms Due Diligence for merchants that sell firearms.
    typestringrequired
    option 5object
    Attestation of Compliance and Questionnaire for pharmaceutical merchants that accept CNP transactions.
    typestringrequired
    option 6object
    CBD Attestation for merchants that sell any of the following products: CBD products Synthetic THC or Cannabis HHC Kratom Tianeptine Delta 8/9/10/0 THC products
    typestringrequired
    option 7object
    CNP Tobacco Merchant Questionnaire for merchants that sell tobacco products and accept CNP transactions.
    typestringrequired
    option 8object
    Donations Addendum for merchants that accept donations.
    typestringrequired
    option 9object
    Clover Merchant Processing Amendment for merchants that order Clover equipment.
    lineItemsobjectrequired
    Object that contains information about the Clover equipment and accessories that the merchant wants to order.
    cloverBarCodeScannerobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverCashDrawerobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverCompactobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverCompactTetherCableobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverFlex4thGenobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverFlexPocketobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverHandsFreeScannerobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverKds14object
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverKds24object
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverKitchenPrinterobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverKitchenPrinterThermalobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverMiniLte3rdGenobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverSoloPosSystemobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverStationDuoGen2PosSystemobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    cloverWeightScaleobject
    Object that contains information about the cost of each item and the number of items that the merchant wants to order.
    quantityintegerrequired
    Number of units.≥ 1
    totalPriceintegerrequired
    Total cost for all devices in this line item, in cents (USD).≥ 0
    typestringrequired
    option 10object
    Roc Giving Addendum for merchants that use Roc Giving.
    accountAdminContactobjectrequired
    Object that contains contact details for the Roc Giving account administrator.
    emailAddressstringrequired
    Email address of the Roc Giving account administrator.≤ 50 chars
    firstNamestringrequired
    First name of the Roc Giving account administrator.≤ 50 chars
    lastNamestringrequired
    Last name of the Roc Giving account administrator.≤ 50 chars
    phonestring
    Phone number of the Roc Giving account administrator.≤ 15 chars
    autoCloseTimestringrequired
    Time that the processing terminal closes the batch in HH:mm format using the 24-hour clock.≤ 5 chars
    donorSupportPercentagenumberrequired
    Percentage of the total donation amount that a donor can add to their donation to provide additional support to the organization.0–100
    planstring
    Roc Giving pricing plan for the processing account. The value is one of the following: basic Merchant has access to the features available with the basic Roc Giving plan. advanced Merchant has access to the additional features available with the advanced Roc Giving plan.basicadvanced
    typestringrequired
  - doingBusinessAsstringrequired
    Trading name of the business.
  - linkobject
    Object that contains HATEOAS links for the processing account.
    hrefstring
    Link to the resource.
    methodstring
    HTTP method you can use to retrieve the resource.
    relstring
    Relationship to the parent resource.
  - processingAccountIdstring
    Unique identifier that we assigned to the processing account.
  - processorstringrequired
    Processor that authorizes and settles transactions for the processing account. Note: We recommend that you include a value for the processor parameter and not rely on the default value.tsysfiserv
  - signatureobject
    Polymorphic object that contains information about how we captured the owner's signature. The value of the type parameter determines which variant you should use: requestedViaDirectLink Request signature using a link. requestedViaEmail Request signature by email.
    requestedViaDirectLinkobject
    Object that contains signature information if we captured the merchant’s signature by direct link.
    linkobject
    Object that contains links to the signed contract.
    hrefstringrequired
    URL of the target resource.
    methodstringrequired
    HTTP method that you need to use with the target resource.
    relstringrequired
    Indicates the relationship between the current resource and the target resource.
    typestringrequired
    Method used to capture the owner's signature.requestedViaDirectLink
    requestedViaEmailobject
    Object that contains signature information if we captured the merchant’s signature by email.
    typestringrequired
    Method used to capture the owner's signature.requestedViaEmail
  - statusstringrequired
    Status of the processing account. entered We have received information about the account, but we have not yet reviewed it. pending We have reviewed the information about the account, but we have not yet approved it. approved We have approved the account for processing transactions and funding. subjectTo We have approved the account, but we are waiting on further information. dormant Account is closed for a period. nonProcessing We have approved the account, but the merchant has not yet run a transaction. rejected We rejected the application for the processing account. terminated Processing account is closed. cancelled Merchant withdrew the application for the processing account. failed An error occurred while we were setting up the processing account. Note: You can subscribe to our processingAccount.status.changed event to get notifications when we change the status of a processing account. For more information about how to subscribe to events, go to Event Subscriptions.enteredpendingapprovedsubjectTodormantnonProcessingrejectedterminated+2 more

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

review-merchant-hierarchy