Board merchantsBoarding

Create a merchant platform

View as MarkdownOpen in Claude

A merchant platform contains all the details of a merchant’s business. When you create a merchant platform, you provide the legal information about the business, which includes the unique tax ID, the legal business name, and the type of organization.

We recommend that you also add all processing accounts that the merchant’s business requires. For each processing account, include the following details:

  • 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 assigna 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: If the merchant’s business expands, you can add more processing accounts.

Integration steps

Step 1. Create a merchant platform
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 merchant platform

To create a merchant platform, send a POST request to our merchant platform endpoint.

Request parameters

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

Request

businessobjectRequired
Object that contains information about the business.
processingAccountslist of objectsRequired
Array of processingAccounts objects.
metadatamap from strings to stringsOptional
Object that you can send to include custom data in the request.

Example request

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

Response fields

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

Response

businessobjectRequired
Object that contains information about the business.
processingAccountslist of objectsRequiredRead-only
Array of processingAccount objects.
merchantPlatformIdstringOptionalRead-only
Unique identifier that we assigned to the merchant platform.
createdDatedatetimeOptionalRead-only
Date that the merchant platform was created. We return this value in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
lastModifiedDatedatetimeOptionalRead-only
Date that the merchant platform was last modified. We return this value in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
metadatamap from strings to stringsOptional
Object that you can send to include custom metadata in the request.

Example response

Response
1{
2  "business": {
3    "name": "Example Corp",
4    "taxId": "xxxxx6789",
5    "organizationType": "privateCorporation",
6    "addresses": [
7      {
8        "type": "legalAddress",
9        "address1": "1 Example Ave.",
10        "address2": "Example Address Line 2",
11        "address3": "Example Address Line 3",
12        "city": "Chicago",
13        "state": "Illinois",
14        "country": "US",
15        "postalCode": "60056"
16      }
17    ],
18    "contactMethods": [
19      {
20        "type": "email",
21        "value": "[email protected]"
22      }
23    ],
24    "countryOfOperation": "US"
25  },
26  "processingAccounts": [
27    {
28      "doingBusinessAs": "Pizza Doe",
29      "status": "pending",
30      "processingAccountId": "38765",
31      "link": {
32        "rel": "processingAccount",
33        "href": "https://api.payroc.com/v1/processing-accounts/38765",
34        "method": "get"
35      },
36      "signature": {
37        "type": "requestedViaDirectLink",
38        "link": {
39          "rel": "agreement",
40          "method": "get",
41          "href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000"
42        }
43      }
44    }
45  ],
46  "merchantPlatformId": "12345",
47  "createdDate": "2024-07-02T12:00:00.000Z",
48  "lastModifiedDate": "2024-07-02T12:00:00.000Z"
49}

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.

Note: 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            clientOptions: new ClientOptions {
12                Environment = PayrocEnvironment.Production
13            }
14        );
15
16        await client.Boarding.ProcessingAccounts.CreateReminderAsync(
17            new CreateReminderProcessingAccountsRequest {
18                ProcessingAccountId = "38765",
19                IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
20                Body = new CreateReminderProcessingAccountsRequestBody(
21                    new PricingAgreementReminder()
22                )
23            }
24        );
25    }
26
27}
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
1{
2  "type": "pricingAgreement",
3  "reminderId": "1234567"
4}