IntegrateBoarding

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

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 objectsRequired
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
contactMethodslist of objectsRequired
Array of contactMethods objects for the processing account. At least one contactMethod must be an email address.
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
Object that includes information about how we captured the owner's signature.
processingAccountIdstringOptional
Unique identifier of the processing account.
createdDatedatetimeOptional
Date and time that we received your request to create the processing account in our system.
lastModifiedDatedatetimeOptional
Date and time that the processing account was last modified.
statusenumOptional
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/integrate/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 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 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

Example request

POST
/v1/processing-accounts/:processingAccountId/reminders
1using Payroc.Boarding.ProcessingAccounts;
2using Payroc;
3
4var client = new PayrocClient("x-api-key");
5await client.Boarding.ProcessingAccounts.CreateReminderAsync(
6    new CreateReminderProcessingAccountsRequest
7    {
8        ProcessingAccountId = "38765",
9        IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
10        Body = new CreateReminderProcessingAccountsRequestBody(
11            new CreateReminderProcessingAccountsRequestBody.PricingAgreement(
12                new PricingAgreementReminder()
13            )
14        ),
15    }
16);

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

Example response

Response
1{
2  "reminderId": "1234567",
3  "type": "pricingAgreement"
4}