Board merchantsBoarding

Create a merchant platform

View as Markdown

An AI skill is available for this guide, get it on the Skills Marketplace (GitHub).

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 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: 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

Authenticate your requests before making API calls. If your request fails, 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

Example request

POST
/v1/merchant-platforms
1curl -X POST https://api.payroc.com/v1/merchant-platforms \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "business": {
7    "name": "Example Corp",
8    "taxId": "12-3456789",
9    "organizationType": "privateCorporation",
10    "addresses": [
11      {
12        "address1": "1 Example Ave.",
13        "address2": "Example Address Line 2",
14        "address3": "Example Address Line 3",
15        "city": "Chicago",
16        "country": "US",
17        "postalCode": "60056",
18        "state": "Illinois",
19        "type": "legalAddress"
20      }
21    ],
22    "contactMethods": [
23      {
24        "type": "email",
25        "value": "[email protected]"
26      }
27    ],
28    "countryOfOperation": "US"
29  },
30  "processingAccounts": [
31    {
32      "doingBusinessAs": "Pizza Doe",
33      "owners": [
34        {
35          "firstName": "Jane",
36          "lastName": "Doe",
37          "dateOfBirth": "1964-03-22",
38          "address": {
39            "address1": "1 Example Ave.",
40            "city": "Chicago",
41            "state": "Illinois",
42            "country": "US",
43            "postalCode": "60056",
44            "address2": "Example Address Line 2",
45            "address3": "Example Address Line 3"
46          },
47          "identifiers": [
48            {
49              "type": "nationalId",
50              "value": "000-00-4320"
51            }
52          ],
53          "contactMethods": [
54            {
55              "type": "email",
56              "value": "[email protected]"
57            }
58          ],
59          "relationship": {
60            "isControlProng": true,
61            "equityPercentage": 48.5,
62            "title": "CFO",
63            "isAuthorizedSignatory": false
64          },
65          "middleName": "Helen"
66        }
67      ],
68      "merchandiseOrServiceSold": "Pizza",
69      "businessStartDate": "2020-01-01",
70      "timezone": "America/Chicago",
71      "address": {
72        "address1": "1 Example Ave.",
73        "address2": "Example Address Line 2",
74        "address3": "Example Address Line 3",
75        "city": "Chicago",
76        "country": "US",
77        "postalCode": "60056",
78        "state": "Illinois"
79      },
80      "contactMethods": [
81        {
82          "type": "email",
83          "value": "[email protected]"
84        }
85      ],
86      "processing": {
87        "transactionAmounts": {
88          "average": 5000,
89          "highest": 10000
90        },
91        "monthlyAmounts": {
92          "average": 50000,
93          "highest": 100000
94        },
95        "volumeBreakdown": {
96          "cardPresent": 77,
97          "mailOrTelephone": 3,
98          "ecommerce": 20
99        },
100        "isSeasonal": true,
101        "monthsOfOperation": [
102          "jan",
103          "feb"
104        ],
105        "ach": {
106          "refunds": {
107            "writtenRefundPolicy": true,
108            "refundPolicyUrl": "www.example.com/refund-poilcy-url"
109          },
110          "estimatedMonthlyTransactions": 3000,
111          "limits": {
112            "singleTransaction": 10000,
113            "dailyDeposit": 200000,
114            "monthlyDeposit": 6000000
115          },
116          "naics": "5812",
117          "previouslyTerminatedForAch": false,
118          "transactionTypes": [
119            "prearrangedPayment",
120            "other"
121          ],
122          "transactionTypesOther": "anotherTransactionType"
123        },
124        "cardAcceptance": {
125          "debitOnly": false,
126          "hsaFsa": false,
127          "cardsAccepted": [
128            "visa",
129            "mastercard"
130          ],
131          "specialityCards": {
132            "americanExpressDirect": {
133              "enabled": true,
134              "merchantNumber": "abc1234567"
135            },
136            "electronicBenefitsTransfer": {
137              "enabled": true,
138              "fnsNumber": "6789012"
139            },
140            "other": {
141              "wexMerchantNumber": "abc1234567",
142              "voyagerMerchantId": "abc1234567",
143              "fleetMerchantId": "abc1234567"
144            }
145          }
146        }
147      },
148      "funding": {
149        "fundingSchedule": "nextday",
150        "acceleratedFundingFee": 1999,
151        "dailyDiscount": false,
152        "fundingAccounts": [
153          {
154            "type": "checking",
155            "use": "creditAndDebit",
156            "nameOnAccount": "Jane Doe",
157            "paymentMethods": [
158              {
159                "type": "ach",
160                "value": {
161                  "routingNumber": "123456789",
162                  "accountNumber": "1234567890"
163                }
164              }
165            ],
166            "metadata": {
167              "yourCustomField": "abc123"
168            }
169          }
170        ]
171      },
172      "pricing": {
173        "type": "intent",
174        "pricingIntentId": "6123"
175      },
176      "signature": {
177        "type": "requestedViaDirectLink"
178      },
179      "website": "www.example.com",
180      "businessType": "restaurant",
181      "categoryCode": 5999,
182      "processor": "tsys",
183      "contacts": [
184        {
185          "type": "manager",
186          "firstName": "Jane",
187          "lastName": "Doe",
188          "contactMethods": [
189            {
190              "type": "email",
191              "value": "[email protected]"
192            }
193          ],
194          "middleName": "Helen",
195          "identifiers": [
196            {
197              "type": "nationalId",
198              "value": "000-00-4320"
199            }
200          ]
201        }
202      ],
203      "metadata": {
204        "customerId": "2345"
205      }
206    }
207  ],
208  "metadata": {
209    "customerId": "2345"
210  }
211}'
Try it

Response fields

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

Response

Example response

Response
1{
2  "business": {
3    "name": "Example Corp",
4    "taxId": "xxxxx6789",
5    "organizationType": "privateCorporation",
6    "addresses": [
7      {
8        "address1": "1 Example Ave.",
9        "address2": "Example Address Line 2",
10        "address3": "Example Address Line 3",
11        "city": "Chicago",
12        "country": "US",
13        "postalCode": "60056",
14        "state": "Illinois",
15        "type": "legalAddress"
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      "processor": "tsys",
30      "status": "pending",
31      "addendums": [],
32      "processingAccountId": "38765",
33      "link": {
34        "rel": "processingAccount",
35        "href": "https://api.payroc.com/v1/processing-accounts/38765",
36        "method": "get"
37      },
38      "signature": {
39        "type": "requestedViaDirectLink",
40        "link": {
41          "rel": "agreement",
42          "method": "get",
43          "href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000"
44        }
45      }
46    }
47  ],
48  "merchantPlatformId": "12345",
49  "createdDate": "2024-07-02T12:00:00.000Z",
50  "lastModifiedDate": "2024-07-02T12:00:00.000Z"
51}

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
1curl -X POST https://api.payroc.com/v1/processing-accounts/38765/reminders \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "type": "pricingAgreement"
7}'
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}