Board merchantsBoarding

Add a processing account to a merchant platform

View as Markdown

Important: You must create a merchant platform before you can add additional processing accounts.

Each merchant platform includes one or more processing accounts that run transactions for the business. To create a processing account, you must provide the following types of information:

  • Business details including the Merchant Category Code (MCC), Doing Business As (DBA) name, and address of the business.
  • Owners’ details including their names, addresses, and contact details. You must assign a control prong who is responsible for their account.
  • Processing details including estimated average transaction amounts and monthly processing amounts.
  • Pricing and funding details including pricing agreements and funding accounts for the processing account.

Note: You can add more than one processing account in the same request.

Integration steps

Step 1. Create a processing account
Step 2. (Optional) Create a reminder

Before you begin

Authenticate your requests before making API calls. If your request fails, see Errors.

Step 1. Create a processing account

Send a POST request with the merchantPlatformId to our Merchant Platform endpoint:

Request parameters

To create the body of your request, use the following parameters:

Request

doingBusinessAsstringRequired<=100 characters
Trading name of the business.
ownerslist of objectsRequired
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.
merchandiseOrServiceSoldstringRequired<=125 characters
Description of the services or merchandise sold by the business.
businessStartDatedateRequired
Date that the business was established. The format of the value is **YYYY-MM-DD**.
timezoneenumRequired
Time zone for the processing account.
addressobjectRequired
Polymorphic object that contains address information for the processing account.
contactMethodslist of objectsRequired
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.
processingobjectRequired
Object that contains information about how we process transactions for the account.
fundingobjectRequired
Object that contains information about the funding schedule of the processing account.
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.
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.
websitestringOptional<=128 characters
Website address of the business.
businessTypeenumOptional
Type of business.
categoryCodeintegerOptional
Merchant Category Code (MCC) for the type of business.
processorenumOptionalDefaults to tsys
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.
contactslist of objectsOptional
Array of contact objects.
addendumslist of objectsOptional
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.
metadatamap from strings to stringsOptional
Object that you can send to include custom data in the request. For more information about how to use metadata, go to [Metadata](https://docs.payroc.com/api/metadata).

Example request

POST
/v1/merchant-platforms/:merchantPlatformId/processing-accounts
curl -X POST https://api.payroc.com/v1/merchant-platforms/12345/processing-accounts \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "doingBusinessAs": "Pizza Doe",
  "owners": [
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1964-03-22",
      "address": {
        "address1": "1 Example Ave.",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3"
      },
      "identifiers": [
        {
          "type": "nationalId",
          "value": "000-00-4320"
        }
      ],
      "contactMethods": [
        {
          "type": "email",
          "value": "[email protected]"
        }
      ],
      "relationship": {
        "isControlProng": true,
        "equityPercentage": 51.5,
        "title": "CFO",
        "isAuthorizedSignatory": false
      },
      "middleName": "Helen"
    }
  ],
  "merchandiseOrServiceSold": "Pizza",
  "businessStartDate": "2020-01-01",
  "timezone": "America/Chicago",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "country": "US",
    "postalCode": "60056",
    "state": "Illinois"
  },
  "contactMethods": [
    {
      "type": "email",
      "value": "[email protected]"
    }
  ],
  "processing": {
    "transactionAmounts": {
      "average": 5000,
      "highest": 10000
    },
    "monthlyAmounts": {
      "average": 50000,
      "highest": 100000
    },
    "volumeBreakdown": {
      "cardPresent": 77,
      "mailOrTelephone": 3,
      "ecommerce": 20
    },
    "isSeasonal": true,
    "monthsOfOperation": [
      "jan",
      "feb"
    ],
    "ach": {
      "refunds": {
        "writtenRefundPolicy": true,
        "refundPolicyUrl": "http://www.example.com/refunds"
      },
      "estimatedMonthlyTransactions": 3000,
      "limits": {
        "singleTransaction": 10000,
        "dailyDeposit": 200000,
        "monthlyDeposit": 6000000
      },
      "naics": "5812",
      "previouslyTerminatedForAch": false,
      "transactionTypes": [
        "prearrangedPayment",
        "other"
      ],
      "transactionTypesOther": "recurringBilling"
    },
    "cardAcceptance": {
      "debitOnly": false,
      "hsaFsa": false,
      "cardsAccepted": [
        "visa",
        "mastercard"
      ],
      "specialityCards": {
        "americanExpressDirect": {
          "enabled": true,
          "merchantNumber": "abc1234567"
        },
        "electronicBenefitsTransfer": {
          "enabled": true,
          "fnsNumber": "6789012"
        },
        "other": {
          "wexMerchantNumber": "abc1234567",
          "voyagerMerchantId": "abc1234567",
          "fleetMerchantId": "abc1234567"
        }
      }
    }
  },
  "funding": {
    "fundingSchedule": "nextday",
    "acceleratedFundingFee": 1999,
    "dailyDiscount": false,
    "fundingAccounts": [
      {
        "type": "checking",
        "use": "creditAndDebit",
        "nameOnAccount": "Jane Doe",
        "paymentMethods": [
          {
            "type": "ach",
            "value": {
              "routingNumber": "123456789",
              "accountNumber": "1234567890"
            }
          }
        ],
        "metadata": {
          "yourCustomField": "abc123"
        }
      }
    ]
  },
  "pricing": {
    "type": "intent",
    "pricingIntentId": "6123"
  },
  "signature": {
    "type": "requestedViaDirectLink"
  },
  "website": "www.example.com",
  "businessType": "restaurant",
  "categoryCode": 5999,
  "processor": "tsys",
  "contacts": [
    {
      "type": "manager",
      "firstName": "Jane",
      "lastName": "Doe",
      "contactMethods": [
        {
          "type": "email",
          "value": "[email protected]"
        }
      ],
      "middleName": "Helen",
      "identifiers": [
        {
          "type": "nationalId",
          "value": "000-00-4320"
        }
      ]
    }
  ],
  "metadata": {
    "customerId": "2345"
  }
}'
Try it

Response fields

If your request is successful, our gateway creates the processing account. The response contains the following fields:

Response

doingBusinessAsstringRequired<=100 characters
Trading name of the business.
ownerslist of objectsRequiredRead-only
Object that contains information about the owners of the business.
merchandiseOrServiceSoldstringRequired<=125 characters
Description of the services or merchandise sold by the business.
timezoneenumRequired
Time zone for the processing account.
addressobjectRequired
Polymorphic object that contains address information for the processing account.
contactMethodslist of objectsRequired
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
processingobjectRequired
Object that contains information about how we process transactions for the account.
fundingobjectRequired
Object that contains funding information for the processing account, including funding schedules, funding fees, and details of funding accounts.
pricingobjectRequired
Object that HATEOAS links to the pricing information that we apply to the processing account.
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.
addendumslist of objectsRequiredRead-only
Array of polymorphic addendumEntry objects. Each object indicates the additional form that we sent to the merchant with the Merchant Processing Agreement (MPA). The value of the type parameter determines which variant you should use.
processingAccountIdstringOptionalRead-only
Unique identifier of the processing account.
createdDatedatetimeOptionalRead-only
Date and time that we received your request to create the processing account in our system.
lastModifiedDatedatetimeOptionalRead-only
Date and time that the processing account was last modified.
statusenumOptionalRead-only
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. **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](https://docs.payroc.com/guides/board-merchants/event-subscriptions).
websitestringOptional<=128 characters
Website address of the business.
businessTypeenumOptional
Type of business.
categoryCodeintegerOptional
Merchant Category Code (MCC) for the type of business.
processorenumOptionalDefaults to tsys
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.
businessStartDatedateOptional
Date that the business was established. The format of the value is **YYYY-MM-DD**.
contactslist of objectsOptionalRead-only
Array of contact objects.
metadatamap from strings to stringsOptional
Object that you can send to include custom data in the request. For more information about how to use metadata, go to [Metadata](https://docs.payroc.com/api/metadata).

Example response

Response
{
  "doingBusinessAs": "Pizza Doe",
  "owners": [
    {
      "ownerId": 4564,
      "firstName": "Jane",
      "lastName": "Doe",
      "link": {
        "rel": "owner",
        "href": "https://api.payroc.com/v1/owners/4564",
        "method": "get"
      }
    }
  ],
  "merchandiseOrServiceSold": "Pizza",
  "timezone": "America/Chicago",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "country": "US",
    "postalCode": "60056",
    "state": "Illinois"
  },
  "contactMethods": [
    {
      "type": "email",
      "value": "[email protected]"
    }
  ],
  "processing": {
    "transactionAmounts": {
      "average": 5000,
      "highest": 10000
    },
    "monthlyAmounts": {
      "average": 50000,
      "highest": 100000
    },
    "volumeBreakdown": {
      "cardPresent": 77,
      "mailOrTelephone": 3,
      "ecommerce": 20
    },
    "isSeasonal": true,
    "monthsOfOperation": [
      "jan",
      "feb"
    ],
    "ach": {
      "refunds": {
        "writtenRefundPolicy": true,
        "refundPolicyUrl": "http://www.example.com/refunds"
      },
      "estimatedMonthlyTransactions": 3000,
      "limits": {
        "singleTransaction": 10000,
        "dailyDeposit": 200000,
        "monthlyDeposit": 6000000
      },
      "naics": "5812",
      "previouslyTerminatedForAch": false,
      "transactionTypes": [
        "prearrangedPayment",
        "other"
      ],
      "transactionTypesOther": "recurringBilling"
    },
    "cardAcceptance": {
      "debitOnly": false,
      "hsaFsa": false,
      "cardsAccepted": [
        "visa",
        "mastercard"
      ],
      "specialityCards": {
        "americanExpressDirect": {
          "enabled": true,
          "merchantNumber": "abc1234567"
        },
        "electronicBenefitsTransfer": {
          "enabled": true,
          "fnsNumber": "6789012"
        },
        "other": {
          "wexMerchantNumber": "abc1234567",
          "voyagerMerchantId": "abc1234567",
          "fleetMerchantId": "abc1234567"
        }
      }
    }
  },
  "funding": {
    "acceleratedFundingFee": 1999,
    "dailyDiscount": false,
    "fundingAccounts": [
      {
        "fundingAccountId": 123,
        "status": "pending",
        "link": {
          "rel": "fundingAccount",
          "method": "get",
          "href": "https://api.payroc.com/v1/funding-accounts/123"
        }
      }
    ],
    "fundingSchedule": "nextday",
    "status": "enabled"
  },
  "pricing": {
    "link": {
      "rel": "pricing",
      "href": "https://api.payroc.com/v1/processing-accounts/12345/pricing",
      "method": "get"
    }
  },
  "signature": {
    "type": "requestedViaDirectLink",
    "link": {
      "rel": "agreement",
      "method": "get",
      "href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000"
    }
  },
  "addendums": [],
  "processingAccountId": "38765",
  "createdDate": "2024-07-02T12:00:00.000+00:00",
  "lastModifiedDate": "2024-07-02T12:00:00.000+00:00",
  "status": "entered",
  "website": "www.example.com",
  "businessType": "restaurant",
  "categoryCode": 5999,
  "processor": "tsys",
  "businessStartDate": "2020-01-01",
  "contacts": [
    {
      "contactId": 1543,
      "firstName": "Jane",
      "lastName": "Doe",
      "link": {
        "rel": "contact",
        "href": "https://api.payroc.com/v1/contacts/1543",
        "method": "get"
      }
    }
  ],
  "metadata": {
    "customerId": "2345"
  }
}

Step 2. (Optional) Create a reminder

If you requested the merchant’s signature by email and they don’t respond, use our Reminders endpoint to send another email.

Important: You can use the Reminders endpoint only if you request the merchant’s signature by email. If you generate a link to the pricing agreement, you can’t use the Reminders endpoint.

Request parameters

To create the body of your request, use the following parameters:

Request

pricingAgreementobjectRequired
Object that contains information about the pricing agreement reminder.

Example request

POST
/v1/processing-accounts/:processingAccountId/reminders
curl -X POST https://api.payroc.com/v1/processing-accounts/38765/reminders \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "type": "pricingAgreement"
}'
Try it

Response fields

If your request is successful, our gateway creates the reminder and sends the email to the merchant. The response contains the following fields:

Response

pricingAgreementobjectRequired
Object that contains information about the pricing agreement reminder.

Example response

Response
{
  "type": "pricingAgreement",
  "reminderId": "1234567"
}