Add a processing account to a merchant platform

View as MarkdownOpen in Claude

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

Bearer tokens

Use our Identity Service to generate a Bearer token to include in the header of your requests. To generate your Bearer token, complete the following steps:

  1. Include your API key in the x-api-key parameter in the header of a POST request.
  2. Send your request to https://identity.payroc.com/authorize.

Note: You need to generate a new Bearer token before the previous Bearer token expires.

Example request

$curl --location --request POST 'https://identity.payroc.com/authorize' --header 'x-api-key: <api key>'

Example response

If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.

1{
2 "access_token": "eyJhbGc....adQssw5c",
3 "expires_in": 3600,
4 "scope": "service_a service_b",
5 "token_type": "Bearer"
6}

Headers

To create the header of each POST request, you must include the following parameters:

  • Content-Type: Include application/json as the value for this parameter.
  • Authorization: Include your Bearer token in this parameter.
  • Idempotency-Key: Include a UUID v4 to make the request idempotent.
$curl
$-H "Content-Type: application/json"
$-H "Authorization: <Bearer token>"
$-H "Idempotency-Key: <UUID v4>"

Errors

If your request is unsuccessful, we return an error. For more information about errors, 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.
businessTypeenumRequired
Type of business.
categoryCodeintegerRequired
Merchant Category Code (MCC) for the type of business.
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.
contactslist of objectsOptional
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 request

POST
/v1/merchant-platforms/:merchantPlatformId/processing-accounts
1using Payroc;
2using System.Threading.Tasks;
3using Payroc.Boarding.MerchantPlatforms;
4using System.Collections.Generic;
5using System;
6
7namespace Usage;
8
9public class Example
10{
11 public async Task Do() {
12 var client = new BasePayrocClient();
13
14 await client.Boarding.MerchantPlatforms.CreateProcessingAccountAsync(
15 new CreateProcessingAccountMerchantPlatformsRequest {
16 MerchantPlatformId = "12345",
17 IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
18 Body = new CreateProcessingAccount {
19 DoingBusinessAs = "Pizza Doe",
20 Owners = new List<Owner>(){
21 new Owner {
22 FirstName = "Jane",
23 LastName = "Doe",
24 DateOfBirth = DateOnly.Parse("1964-03-22"),
25 Address = new Address {
26 Address1 = "1 Example Ave.",
27 City = "Chicago",
28 State = "Illinois",
29 Country = "US",
30 PostalCode = "60056",
31 Address2 = "Example Address Line 2",
32 Address3 = "Example Address Line 3"
33 },
34 Identifiers = new List<Identifier>(){
35 new Identifier {
36 Type = IdentifierType.NationalId,
37 Value = "000-00-4320"
38 },
39 }
40 ,
41 ContactMethods = new List<ContactMethod>(){
42 new ContactMethod(
43 new ContactMethodEmail {
44 Value = "[email protected]"
45 }
46 ),
47 }
48 ,
49 Relationship = new OwnerRelationship {
50 IsControlProng = true,
51 EquityPercentage = 51.5f,
52 Title = "CFO",
53 IsAuthorizedSignatory = false
54 },
55 MiddleName = "Helen"
56 },
57 }
58 ,
59 BusinessType = CreateProcessingAccountBusinessType.Restaurant,
60 CategoryCode = 5999,
61 MerchandiseOrServiceSold = "Pizza",
62 BusinessStartDate = DateOnly.Parse("2020-01-01"),
63 Timezone = Timezone.AmericaChicago,
64 Address = new Address {
65 Address1 = "1 Example Ave.",
66 Address2 = "Example Address Line 2",
67 Address3 = "Example Address Line 3",
68 City = "Chicago",
69 State = "Illinois",
70 Country = "US",
71 PostalCode = "60056"
72 },
73 ContactMethods = new List<ContactMethod>(){
74 new ContactMethod(
75 new ContactMethodEmail {
76 Value = "[email protected]"
77 }
78 ),
79 }
80 ,
81 Processing = new Processing {
82 TransactionAmounts = new ProcessingTransactionAmounts {
83 Average = 5000,
84 Highest = 10000
85 },
86 MonthlyAmounts = new ProcessingMonthlyAmounts {
87 Average = 50000,
88 Highest = 100000
89 },
90 VolumeBreakdown = new ProcessingVolumeBreakdown {
91 CardPresent = 77,
92 MailOrTelephone = 3,
93 Ecommerce = 20
94 },
95 IsSeasonal = true,
96 MonthsOfOperation = new List<ProcessingMonthsOfOperationItem>(){
97 ProcessingMonthsOfOperationItem.Jan,
98 ProcessingMonthsOfOperationItem.Feb,
99 }
100 ,
101 Ach = new ProcessingAch {
102 Refunds = new ProcessingAchRefunds {
103 WrittenRefundPolicy = true,
104 RefundPolicyUrl = "www.example.com/refund-poilcy-url"
105 },
106 EstimatedMonthlyTransactions = 3000,
107 Limits = new ProcessingAchLimits {
108 SingleTransaction = 10000,
109 DailyDeposit = 200000,
110 MonthlyDeposit = 6000000
111 },
112 Naics = "5812",
113 PreviouslyTerminatedForAch = false,
114 TransactionTypes = new List<ProcessingAchTransactionTypesItem>(){
115 ProcessingAchTransactionTypesItem.PrearrangedPayment,
116 ProcessingAchTransactionTypesItem.Other,
117 }
118 ,
119 TransactionTypesOther = "anotherTransactionType"
120 },
121 CardAcceptance = new ProcessingCardAcceptance {
122 DebitOnly = false,
123 HsaFsa = false,
124 CardsAccepted = new List<ProcessingCardAcceptanceCardsAcceptedItem>(){
125 ProcessingCardAcceptanceCardsAcceptedItem.Visa,
126 ProcessingCardAcceptanceCardsAcceptedItem.Mastercard,
127 }
128 ,
129 SpecialityCards = new ProcessingCardAcceptanceSpecialityCards {
130 AmericanExpressDirect = new ProcessingCardAcceptanceSpecialityCardsAmericanExpressDirect {
131 Enabled = true,
132 MerchantNumber = "abc1234567"
133 },
134 ElectronicBenefitsTransfer = new ProcessingCardAcceptanceSpecialityCardsElectronicBenefitsTransfer {
135 Enabled = true,
136 FnsNumber = "6789012"
137 },
138 Other = new ProcessingCardAcceptanceSpecialityCardsOther {
139 WexMerchantNumber = "abc1234567",
140 VoyagerMerchantId = "abc1234567",
141 FleetMerchantId = "abc1234567"
142 }
143 }
144 }
145 },
146 Funding = new CreateFunding {
147 AcceleratedFundingFee = 1999,
148 DailyDiscount = false,
149 FundingAccounts = new List<FundingAccount>(){
150 new FundingAccount {
151 Type = FundingAccountType.Checking,
152 Use = FundingAccountUse.CreditAndDebit,
153 NameOnAccount = "Jane Doe",
154 PaymentMethods = new List<PaymentMethodsItem>(){
155 new PaymentMethodsItem(
156 new PaymentMethodAch {
157 Value = new PaymentMethodAchValue {
158 RoutingNumber = "123456789",
159 AccountNumber = "1234567890"
160 }
161 }
162 ),
163 }
164 ,
165 Metadata = new Dictionary<string, string>(){
166 ["yourCustomField"] = "abc123",
167 }
168
169 },
170 }
171 ,
172 FundingSchedule = CommonFundingFundingSchedule.Nextday
173 },
174 Pricing = new Pricing(
175 new PricingTemplate {
176 PricingIntentId = "6123"
177 }
178 ),
179 Signature = new Signature(
180 new SignatureByDirectLink()
181 ),
182 Website = "www.example.com",
183 Contacts = new List<Contact>(){
184 new Contact {
185 Type = ContactType.Manager,
186 FirstName = "Jane",
187 LastName = "Doe",
188 Identifiers = new List<Identifier>(){
189 new Identifier {
190 Type = IdentifierType.NationalId,
191 Value = "000-00-4320"
192 },
193 }
194 ,
195 ContactMethods = new List<ContactMethod>(){
196 new ContactMethod(
197 new ContactMethodEmail {
198 Value = "[email protected]"
199 }
200 ),
201 }
202 ,
203 MiddleName = "Helen"
204 },
205 }
206 ,
207 Metadata = new Dictionary<string, string>(){
208 ["customerId"] = "2345",
209 }
210
211 }
212 }
213 );
214 }
215
216}

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.
businessTypeenumRequired
Type of business.
categoryCodeintegerRequired
Merchant Category Code (MCC) for the type of 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.
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.
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
1{
2 "doingBusinessAs": "Pizza Doe",
3 "owners": [
4 {
5 "ownerId": 4564,
6 "firstName": "Jane",
7 "lastName": "Doe",
8 "link": {
9 "rel": "owner",
10 "href": "https://api.payroc.com/v1/owners/4564",
11 "method": "get"
12 }
13 }
14 ],
15 "businessType": "restaurant",
16 "categoryCode": 5999,
17 "merchandiseOrServiceSold": "Pizza",
18 "timezone": "America/Chicago",
19 "address": {
20 "address1": "1 Example Ave.",
21 "address2": "Example Address Line 2",
22 "address3": "Example Address Line 3",
23 "city": "Chicago",
24 "state": "Illinois",
25 "country": "US",
26 "postalCode": "60056"
27 },
28 "contactMethods": [
29 {
30 "type": "email",
31 "value": "[email protected]"
32 }
33 ],
34 "processing": {
35 "transactionAmounts": {
36 "average": 5000,
37 "highest": 10000
38 },
39 "monthlyAmounts": {
40 "average": 50000,
41 "highest": 100000
42 },
43 "volumeBreakdown": {
44 "cardPresent": 77,
45 "mailOrTelephone": 3,
46 "ecommerce": 20
47 },
48 "isSeasonal": true,
49 "monthsOfOperation": [
50 "jan",
51 "feb"
52 ],
53 "ach": {
54 "refunds": {
55 "writtenRefundPolicy": true,
56 "refundPolicyUrl": "www.example.com/refund-poilcy-url"
57 },
58 "estimatedMonthlyTransactions": 3000,
59 "limits": {
60 "singleTransaction": 10000,
61 "dailyDeposit": 200000,
62 "monthlyDeposit": 6000000
63 },
64 "naics": "5812",
65 "previouslyTerminatedForAch": false,
66 "transactionTypes": [
67 "prearrangedPayment",
68 "other"
69 ],
70 "transactionTypesOther": "anotherTransactionType"
71 },
72 "cardAcceptance": {
73 "debitOnly": false,
74 "hsaFsa": false,
75 "cardsAccepted": [
76 "visa",
77 "mastercard"
78 ],
79 "specialityCards": {
80 "americanExpressDirect": {
81 "enabled": true,
82 "merchantNumber": "abc1234567"
83 },
84 "electronicBenefitsTransfer": {
85 "enabled": true,
86 "fnsNumber": "6789012"
87 },
88 "other": {
89 "wexMerchantNumber": "abc1234567",
90 "voyagerMerchantId": "abc1234567",
91 "fleetMerchantId": "abc1234567"
92 }
93 }
94 }
95 },
96 "funding": {
97 "acceleratedFundingFee": 1999,
98 "dailyDiscount": false,
99 "fundingAccounts": [
100 {
101 "fundingAccountId": 123,
102 "status": "pending",
103 "link": {
104 "rel": "fundingAccount",
105 "method": "get",
106 "href": "https://api.payroc.com/v1/funding-accounts/123"
107 }
108 }
109 ],
110 "fundingSchedule": "nextday",
111 "status": "enabled"
112 },
113 "pricing": {
114 "link": {
115 "rel": "pricing",
116 "href": "https://api.payroc.com/v1/processing-accounts/12345/pricing",
117 "method": "get"
118 }
119 },
120 "signature": {
121 "type": "requestedViaDirectLink",
122 "link": {
123 "rel": "agreement",
124 "method": "get",
125 "href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000"
126 }
127 },
128 "processingAccountId": "38765",
129 "createdDate": "2024-07-02T12:00:00.000Z",
130 "lastModifiedDate": "2024-07-02T12:00:00.000Z",
131 "status": "entered",
132 "website": "www.example.com",
133 "businessStartDate": "2020-01-01",
134 "contacts": [
135 {
136 "contactId": 1543,
137 "firstName": "Jane",
138 "lastName": "Doe",
139 "link": {
140 "rel": "contact",
141 "href": "https://api.payroc.com/v1/contacts/1543",
142 "method": "get"
143 }
144 }
145 ],
146 "metadata": {
147 "customerId": "2345"
148 }
149}

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
1using Payroc;
2using System.Threading.Tasks;
3using Payroc.Boarding.ProcessingAccounts;
4
5namespace Usage;
6
7public class Example
8{
9 public async Task Do() {
10 var client = new BasePayrocClient();
11
12 await client.Boarding.ProcessingAccounts.CreateReminderAsync(
13 new CreateReminderProcessingAccountsRequest {
14 ProcessingAccountId = "38765",
15 IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
16 Body = new CreateReminderProcessingAccountsRequestBody(
17 new PricingAgreementReminder()
18 )
19 }
20 );
21 }
22
23}

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
1{
2 "type": "pricingAgreement",
3 "reminderId": "1234567"
4}