IntegrateBoarding

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

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 objectsRequired
Array of processingAccount objects.
merchantPlatformIdstringOptional
Unique identifier that we assigned to the merchant platform.
createdDatedatetimeOptional
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.
lastModifiedDatedatetimeOptional
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

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}