Skip to content
payrocdevelopers

Create merchant platform

Browse API reference

POST/merchant-platformscreateMerchant

Use this method to board a merchant with Payroc.

Note: This method is part of our Boarding solution. To help you understand how this method works with other Boarding methods, go to Board a Merchant.

In the request, include the following information:

  • Legal information, including its legal name and address.
  • Contact information, including the email address for the business.
  • Processing account information, including the pricing model, owners, and contacts for the processing account.

When you send a successful request, we review the merchant's information. After we complete our review and approve the merchant, we assign:

  • merchantPlatformId - Unique identifier for the merchant platform.
  • processingAccountId - Unique identifier for each processing account linked to the merchant platform.

You need to keep these to perform follow-on actions, for example, you need the processingAccountId to order terminals for the processing account.

Parameters

NameInTypeDescription
Idempotency-KeyRequiredheaderstring

Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. For more information about the idempotency key, go to Idempotency.

Request body

application/json
Field Edit request inputs →
  • 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
  • metadataobject
    Object that you can send to include custom data in the request.
  • processingAccountsobject[]required
    Array of processingAccounts objects.≥ 1 items
    • addendumsobject[]
      Array of polymorphic addendumEntry objects that indicate the additional forms that we should send with the Merchant Processing Agreement (MPA). The value of the type parameter determines which variant you should use: installmentPaymentsV1 Send this form if the merchant offers installment payments, loans, or leases. moneyServicesV1 Send this form if the merchant offers money services, for example, traveler's checks. telehealthV1 Send this form if the merchant provides telehealth services. firearmsV1 Send this form if the merchant sells firearms. pharmacyCnpComplianceV1 Send this form if the merchant is a pharmacy that accepts card-not-present (CNP) transactions. cbdV1 Send this form if the merchant sells any of the following products: CBD products Synthetic THC or Cannabis HHC Kratom Tianeptine Delta 8/9/10/0 THC products tobaccoCnpV1 Send this form if the merchant sells tobacco products and accepts CNP transactions. donationsV1 Send this form if the merchant accepts donations. cloverMerchantProcessingAmendmentV1 Send this form if the merchant requires Clover equipment. rocGivingV1 Send this form if the merchant uses Roc Giving.
      • 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
    • addressobjectrequired
      Polymorphic object that contains address information for the processing account.
      • addressobject
        Object that contains information about the address.+7 more fields at deeper levels — see the full spec
    • businessStartDatestringdaterequired
      Date that the business was established. The format of the value is YYYY-MM-DD.
    • businessTypestring
      Type of business.retailrestaurantinternetmotolodgingnotForProfit
    • categoryCodeintegerint32
      Merchant Category Code (MCC) for the type of business.≤ 4 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
        +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
    • contactsobject[]
      Array of contact objects.
      • contactMethodsobject[]required
        Array of polymorphic objects, which contain contact information. Note: If you are adding information about an owner, you must provide at least an email address. If you are adding information about a contact, you must provide at least a contact number. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number1–4 items+12 more fields at deeper levels — see the full spec
      • firstNamestringrequired
        Contact's first name.≤ 50 chars
      • identifiersobject[]
        Array of identifier objects.≥ 1 items+2 more fields at deeper levels — see the full spec
      • lastNamestringrequired
        Contact's last name.≤ 50 chars
      • middleNamestring
        Contact's middle name.≤ 50 chars
      • typestringrequired
        Type of contact.managerrepresentativeothers
    • doingBusinessAsstringrequired
      Trading name of the business.≤ 100 chars
    • fundingobjectrequired
      Object that contains information about the funding schedule of the processing account.
      • acceleratedFundingFeeinteger
        Monthly fee in cents for accelerated funding. The value is in the currency's lowest denomination, for example, cents. We apply this fee if the value for fundingSchedule is sameday or nextday.
      • dailyDiscountboolean
        Indicates if we collect fees from the merchant's account each day.
      • fundingSchedulestring
        Indicates when funds are sent to the funding account. If you send a value of sameDay or nextDay, provide a value for acceleratedFundingFee. Note: If you send a value of sameday, funding includes all transactions the merchant ran before the ACH cut-off time.standardnextdaysameday
      • fundingAccountsobject[]
        Array of fundingAccounts objects.1–2 items+10 more fields at deeper levels — see the full spec
    • merchandiseOrServiceSoldstringrequired
      Description of the services or merchandise sold by the business.≤ 125 chars
    • metadataobject
      Object that you can send to include custom data in the request. For more information about how to use metadata, go to Metadata.
    • ownersobject[]required
      Collection of individuals that are responsible for a processing account. When you create a processing account, you must indicate at least one owner as either of the following: Control prong An individual who has a significant equity stake in the business and can make decisions for the processing account. You can add only one control prong to a processing account. Authorized signatory An individual who doesn't have an equity stake in the business but can make decisions for the processing account.≥ 1 items
      • addressobjectrequired
        Object that contains information about the address.+7 more fields at deeper levels — see the full spec
      • contactMethodsobject[]required
        Array of polymorphic objects, which contain contact information. Note: If you are adding information about an owner, you must provide at least an email address. If you are adding information about a contact, you must provide at least a contact number. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number1–4 items+12 more fields at deeper levels — see the full spec
      • dateOfBirthstringdaterequired
        Owner's date of birth. The format of this value is YYYY-MM-DD.
      • firstNamestringrequired
        Owner's first name.≤ 50 chars
      • identifiersobject[]required
        Array of IDs.≥ 1 items+2 more fields at deeper levels — see the full spec
      • lastNamestringrequired
        Owner's last name.≤ 50 chars
      • middleNamestring
        Owner's middle name.≤ 50 chars
      • relationshipobjectrequired
        Object that contains information about the owner's relationship to the business.+4 more fields at deeper levels — see the full spec
    • pricingobjectrequired
      Polymorphic object that contains pricing information for the processing account. The value of the type parameter determines which variant you should use: intent Use a pricing agreement template. agreement Create a new pricing agreement.
      • intentobject
        +2 more fields at deeper levels — see the full spec
      • agreementobject
        Polymorphic object that contains pricing agreement information for the processing account.+294 more fields at deeper levels — see the full spec
    • processingobjectrequired
      Object that contains information about how we process transactions for the account.
      • achobject
        Object that contains information about Automated Clearing House (ACH) transactions.+12 more fields at deeper levels — see the full spec
      • cardAcceptanceobject
        Object that contains information about the types of cards that the processing account accepts.+14 more fields at deeper levels — see the full spec
      • isSeasonalboolean
        Indicates if the processing account runs transactions on a seasonal basis. For example, if the processing account runs transactions during only the winter months, send a value of true.
      • monthlyAmountsobjectrequired
        Object that contains information about the monthly processing amounts for the processing account.+2 more fields at deeper levels — see the full spec
      • monthsOfOperationstring[]
        Months of the year that the processing account runs transactions.≤ 12 items
      • transactionAmountsobjectrequired
        Object that contains information about transaction amounts for the processing account.+2 more fields at deeper levels — see the full spec
      • volumeBreakdownobjectrequired
        Object that contains information about the types of transactions ran by the processing account. The percentages for transaction types must total 100%.+3 more fields at deeper levels — see the full spec
    • processorstring
      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
    • signatureobjectrequired
      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.+1 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
    • timezonestringrequired
      Time zone for the processing account.≤ 28 charsPacific/MidwayPacific/HonoluluAmerica/AnchorageAmerica/Los_AngelesAmerica/DenverAmerica/PhoenixAmerica/ChicagoAmerica/Indiana/Indianapolis+1 more
    • websitestring
      Website address of the business.≤ 128 chars

Responses

Successful request. We created the merchant platform.

201 Created · 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",
  "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"
    }
  ]
}
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

Used in workflows

create-merchant-platform

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer