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 · 31 of 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+9 more fields at deeper levels — see the full spec
  - 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+12 more fields at deeper levels — see the full spec
  - 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.+74 more fields at deeper levels — see the full spec
  - doingBusinessAsstringrequired
    Trading name of the business.
  - linkobject
    Object that contains HATEOAS links for the processing account.+3 more fields at deeper levels — see the full spec
  - 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.+8 more fields at deeper levels — see the full spec
  - 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