Create merchant platform

POST

/merchant-platforms

POST

/v1/merchant-platforms

1 using Payroc;
2 using System.Threading.Tasks;
3 using Payroc.Boarding.MerchantPlatforms;
4 using System.Collections.Generic;
5 using System;
6 
7 namespace Usage;
8 
9 public class Example
10 {
11     public async Task Do() {
12         var client = new PayrocClient();
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 }

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 }

Use this method to board a merchant with Payroc.

Note: This method is part of our Boarding solution. To help you understand how this method works with other Boarding methods, go to Board a Merchant.

In the request, include the following information:

Legal information, including its legal name and address.
Contact information, including the email address for the business.
Processing account information, including the pricing model, owners, and contacts for the processing account.

When you send a successful request, we review the merchant’s information. After we complete our review and approve the merchant, we assign:

merchantPlatformId - Unique identifier for the merchant platform.
processingAccountId - Unique identifier for each processing account linked to the merchant platform.

You need to keep these to perform follow-on actions, for example, you need the processingAccountId to order terminals for the processing account.

Use this method to board a merchant with Payroc. **Note**: This method is part of our Boarding solution. To help you understand how this method works with other Boarding methods, go to [Board a Merchant](https://docs.payroc.com/guides/board-merchants/boarding). In the request, include the following information: - Legal information, including its legal name and address. - Contact information, including the email address for the business. - Processing account information, including the pricing model, owners, and contacts for the processing account. When you send a successful request, we review the merchant's information. After we complete our review and approve the merchant, we assign: - **merchantPlatformId** - Unique identifier for the merchant platform. - **processingAccountId** - Unique identifier for each processing account linked to the merchant platform. You need to keep these to perform follow-on actions, for example, you need the processingAccountId to [order terminals](https://docs.payroc.com/api/schema/boarding/processing-accounts/create-terminal-order) for the processing account.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

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.

Response headers

locationstring

URI reference to the resource.

Response

Successful request. We created the merchant platform.

businessobject

Object that contains information about the business.

processingAccountslist of objectsRead-only

Array of processingAccount objects.

merchantPlatformIdstringRead-only

Unique identifier that we assigned to the merchant platform.

createdDatedatetimeRead-only

Date that the merchant platform was created. We return this value in the ISO-8601 format.

lastModifiedDatedatetimeRead-only

Date that the merchant platform was last modified. We return this value in the ISO-8601 format.

metadatamap from strings to strings

Object that you can send to include custom metadata in the request.

linkslist of objectsRead-only

Array of useful links related to your request.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

406

Not Acceptable Error

409

Conflict Error

500

Internal Server Error

Authentication

Headers

Request

Response headers

Response

Errors