Retrieve merchant platform

Browse API reference

GET/merchant-platforms/{merchantPlatformId}getMerchantAccounts

Use this method to retrieve information about a merchant platform.

To retrieve a merchant platform, you need its merchantPlatformId. Our gateway returned the merchantPlatformId in the response of the Create Merchant Platform method.

Note: If you don't have the merchantPlatformId, use our List Merchant Platforms method to search for the merchant platform.

Our gateway returns the following information about the merchant platform:

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.

Parameters

Name	In	Type	Description
`merchantPlatformId`Required	path	`string`	Unique identifier of the merchant platform that we sent to you when you created the merchant platform.

Responses

Successful request. Returns the merchant platform.

200 OK · application/json

{
  "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": "jane.doe@example.com"
      }
    ],
    "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",
  "links": [],
  "merchantPlatformId": "12345",
  "metadata": {
    "customerId": "2345"
  },
  "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": "approved"
    }
  ]
}

Response schema · 43 of 129 fields

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.+8 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
  - emailobject
    +2 more fields at deeper levels — see the full spec
  - phoneobject
    +2 more fields at deeper levels — see the full spec
  - mobileobject
    +2 more fields at deeper levels — see the full spec
  - faxobject
    +2 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.
  - option 1object
    Installment Payments, Loans, or Lease Questionnaire/Attestation for merchants that offer installment payments, loans, or leases.+1 more fields at deeper levels — see the full spec
  - option 2object
    Money Services Business Questionnaire for merchants that offer money services, for example, traveler's checks.+1 more fields at deeper levels — see the full spec
  - option 3object
    Telehealth Attestation for merchants that provide telehealth services.+1 more fields at deeper levels — see the full spec
  - option 4object
    Firearms Due Diligence for merchants that sell firearms.+1 more fields at deeper levels — see the full spec
  - option 5object
    Attestation of Compliance and Questionnaire for pharmaceutical merchants that accept CNP transactions.+1 more fields at deeper levels — see the full spec
  - 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+1 more fields at deeper levels — see the full spec
  - option 7object
    CNP Tobacco Merchant Questionnaire for merchants that sell tobacco products and accept CNP transactions.+1 more fields at deeper levels — see the full spec
  - option 8object
    Donations Addendum for merchants that accept donations.+1 more fields at deeper levels — see the full spec
  - option 9object
    Clover Merchant Processing Amendment for merchants that order Clover equipment.+47 more fields at deeper levels — see the full spec
  - option 10object
    Roc Giving Addendum for merchants that use Roc Giving.+9 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.
  - 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.+5 more fields at deeper levels — see the full spec
  - requestedViaEmailobject
    Object that contains signature information if we captured the merchant’s signature by email.+1 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

Invalid request

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "Expected time, got '' for start_time",
      "parameter": "start_time"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

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

Resource not found

404 Not Found · application/problem+json

{
  "detail": "Resource not found",
  "resource": "(The Type of the Resource)",
  "status": 404,
  "title": "Not found",
  "type": "https://docs.payroc.com/api/errors#not-found"
}

Response schema · 5 fields

detailstringrequired
Explanation of the problem
resourcestring
Resource that was not found
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