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