IntegrateBoarding

Add a processing account to a merchant platform

Important: You must create a merchant platform before you can add additional processing accounts.

Each merchant platform includes one or more processing accounts that run transactions for the business. To create a processing account, you must provide the following types of information:

  • 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: You can add more than one processing account in the same request.

Integration steps

Step 1. Create a processing account
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 processing account

Send a POST request with the merchantPlatformId to our Merchant Platform endpoint:

Request parameters

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

Request

doingBusinessAsstringRequired<=100 characters
Trading name of the business.
ownerslist of objectsRequired
Collection of individuals that are responsible for a processing account. When you create a processing account, you must indicate at least one owner as either of the following: - Control prong - An individual who has a significant equity stake in the business and can make decisions for the processing account. You can add only one control prong to a processing account. - Authorized signatory - An individual who doesn't have an equity stake in the business but can make decisions for the processing account.
businessTypeenumRequired
Type of business.
categoryCodeintegerRequired
Category code for the type of business.
merchandiseOrServiceSoldstringRequired<=125 characters
Description of the services or merchandise sold by the business.
businessStartDatestringRequiredformat: "date"
Date that the business was established. The format of the value is **YYYY-MM-DD**.
timezoneenumRequired
The timezone for the processing account
addressobjectRequired
contactMethodslist of objectsRequired
Array of contactMethod objects. One contact method must be an email address.
processingobjectRequired
fundingobjectRequired
pricingobjectRequired
Object that contains pricing information.
signatureenumRequired
Method used to capture the owner's signature. **Note:** If you request the owner’s signature by email and they don’t respond, use our Reminders endpoint to create a reminder and to send another email.
Allowed values:
processingAccountIdintegerOptional
Unique identifier of the processing account.
websitestringOptional<=128 characters
Website address of the business.
contactslist of objectsOptional
Array of contact objects.
metadatamap from strings to stringsOptional
Object that you can send to include custom data in the request.

Example request

POST
/v1/merchant-platforms/:merchantPlatformId/processing-accounts
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  "doingBusinessAs": "Pizza Doe",
7  "owners": [
8    {
9      "firstName": "Jane",
10      "lastName": "Doe",
11      "dateOfBirth": "1964-03-22",
12      "address": {
13        "address1": "1 Example Ave.",
14        "city": "Chicago",
15        "state": "Illinois",
16        "country": "US",
17        "postalCode": "60056"
18      },
19      "identifiers": [
20        {
21          "type": "nationalId",
22          "value": "xxxxx4320"
23        }
24      ],
25      "contactMethods": [
26        {
27          "type": "email",
28          "value": "[email protected]"
29        }
30      ],
31      "relationship": {
32        "isControlProng": true
33      }
34    }
35  ],
36  "businessType": "retail",
37  "categoryCode": 5999,
38  "merchandiseOrServiceSold": "Pizza",
39  "businessStartDate": "2020-01-01",
40  "timezone": "Pacific/Midway",
41  "address": {
42    "address1": "1 Example Ave.",
43    "city": "Chicago",
44    "state": "Illinois",
45    "country": "US",
46    "postalCode": "60056"
47  },
48  "contactMethods": [
49    {
50      "type": "email",
51      "value": "[email protected]"
52    }
53  ],
54  "processing": {
55    "transactionAmounts": {
56      "average": 5000,
57      "highest": 10000
58    },
59    "monthlyAmounts": {
60      "average": 50000,
61      "highest": 100000
62    },
63    "volumeBreakdown": {
64      "cardPresentKeyed": 47,
65      "cardPresentSwiped": 30,
66      "mailOrTelephone": 3,
67      "ecommerce": 20
68    }
69  },
70  "funding": {},
71  "pricing": {
72    "type": "intent",
73    "pricingIntentId": 6123
74  },
75  "signature": "requestedViaEmail"
76}'

Response fields

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

Response

doingBusinessAsstringRequired<=100 characters
Trading name of the business.
ownerslist of objectsRequired
Object that contains information about the owners of the business.
businessTypeenumRequired
Type of business.
categoryCodeintegerRequired
Category code for the type of business.
merchandiseOrServiceSoldstringRequired<=125 characters
Description of the services or merchandise sold by the business.
timezoneenumRequired
The timezone for the processing account
addressobjectRequired
contactMethodslist of objectsRequired
Array of contactMethods objects for the processing account. Atleast one contactMethod must be an email address.
processingobjectRequired
fundingobjectRequired
Object that contains funding information.
pricingobjectRequired
Object that contains pricing information.
signatureobjectRequired
Object containing the method we used to capture the owner's signature.
processingAccountIdstringOptional
Unique identifier of the processing account.
createdDatestringOptionalformat: "date-time"
Date and time that we received your request to create the processing account in our system.
lastModifiedDatestringOptionalformat: "date-time"
Date and time that the processing account was last modified.
statusenumOptional
Status of the processing account. - `entered` - We have received information about the account, but we have not yet reviewed it. - `pending` - We have reviewed the information about the account, but we have not yet approved it. - `approved` - We have approved the account for processing transactions and funding. - `subjectTo` - We have approved the account, but we are waiting on further information. - `dormant` - Account is closed for a period. - `nonProcessing` - We have approved the account, but the merchant has not yet run a transaction. - `rejected` - We rejected the application for the processing account. - `terminated` - Processing account is closed. - `cancelled` - Merchant withdrew the application for the processing account.
websitestringOptional<=128 characters
Website address of the business.
businessStartDatestringOptionalformat: "date"
Date that the business was established. The format of the value is **YYYY-MM-DD**.
contactslist of objectsOptional
Array of contact objects.
metadatamap from strings to stringsOptional
Object that you can send to include custom data in the request.

Example response

Response
1{
2  "doingBusinessAs": "Pizza Doe",
3  "owners": [
4    {
5      "ownerId": 4564,
6      "firstName": "Jane",
7      "lastName": "Doe",
8      "link": {
9        "rel": "owner",
10        "href": "https://api.payroc.com/v1/owners/4564",
11        "method": "get"
12      }
13    }
14  ],
15  "businessType": "restaurant",
16  "categoryCode": 5999,
17  "merchandiseOrServiceSold": "Pizza",
18  "timezone": "America/Chicago",
19  "address": {
20    "address1": "1 Example Ave.",
21    "address2": "Example Address Line 2",
22    "address3": "Example Address Line 3",
23    "city": "Chicago",
24    "state": "Illinois",
25    "country": "US",
26    "postalCode": "60056"
27  },
28  "contactMethods": [
29    {
30      "type": "email",
31      "value": "[email protected]"
32    }
33  ],
34  "processing": {
35    "transactionAmounts": {
36      "average": 5000,
37      "highest": 10000
38    },
39    "monthlyAmounts": {
40      "average": 50000,
41      "highest": 100000
42    },
43    "volumeBreakdown": {
44      "cardPresentKeyed": 47,
45      "cardPresentSwiped": 30,
46      "mailOrTelephone": 3,
47      "ecommerce": 20
48    },
49    "isSeasonal": true,
50    "monthsOfOperation": [
51      "jan",
52      "feb"
53    ],
54    "ach": {
55      "refunds": {
56        "writtenRefundPolicy": true,
57        "refundPolicyUrl": "www.example.com/refund-poilcy-url"
58      },
59      "estimatedMonthlyTransactions": 3000,
60      "limits": {
61        "singleTransaction": 10000,
62        "dailyDeposit": 200000,
63        "monthlyDeposit": 6000000
64      },
65      "naics": "5812",
66      "previouslyTerminatedForAch": false,
67      "transactionTypes": [
68        "prearrangedPayment",
69        "other"
70      ],
71      "transactionTypesOther": "anotherTransactionType"
72    },
73    "cardAcceptance": {
74      "debitOnly": false,
75      "hsaFsa": false,
76      "cardsAccepted": [
77        "visa",
78        "mastercard"
79      ],
80      "specialityCards": {
81        "americanExpressDirect": {
82          "enabled": true,
83          "merchantNumber": "abc1234567"
84        },
85        "electronicBenefitsTransfer": {
86          "enabled": true,
87          "fnsNumber": "6789012"
88        },
89        "other": {
90          "wexMerchantNumber": "abc1234567",
91          "voyagerMerchantId": "abc1234567",
92          "fleetMerchantId": "abc1234567"
93        }
94      }
95    }
96  },
97  "funding": {
98    "acceleratedFundingFee": 1999,
99    "dailyDiscount": false,
100    "fundingAccounts": [
101      {
102        "fundingAccountId": 123,
103        "status": "pending",
104        "link": {
105          "rel": "fundingAccount",
106          "method": "get",
107          "href": "https://api.payroc.com/v1/funding-accounts/123"
108        }
109      }
110    ],
111    "fundingSchedule": "nextday",
112    "status": "enabled"
113  },
114  "pricing": {
115    "link": {
116      "rel": "pricing",
117      "href": "https://api.payroc.com/v1/processing-accounts/12345/pricing",
118      "method": "get"
119    }
120  },
121  "signature": {
122    "type": "requestedViaDirectLink",
123    "link": {
124      "rel": "agreement",
125      "href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000",
126      "method": "get"
127    }
128  },
129  "processingAccountId": "38765",
130  "createdDate": "2024-07-02T12:00:00.000Z",
131  "lastModifiedDate": "2024-07-02T12:00:00.000Z",
132  "status": "entered",
133  "website": "www.example.com",
134  "businessStartDate": "2020-01-01",
135  "contacts": [
136    {
137      "contactId": 1543,
138      "firstName": "Jane",
139      "lastName": "Doe",
140      "link": {
141        "rel": "contact",
142        "href": "https://api.payroc.com/v1/contacts/1543",
143        "method": "get"
144      }
145    }
146  ],
147  "metadata": {
148    "customerId": "2345"
149  }
150}

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.

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

Pricing Agreement ReminderobjectRequired

Example request

POST
/v1/processing-accounts/:processingAccountId/reminders
1curl -X POST https://api.payroc.com/v1/processing-accounts/ \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "type": "pricingAgreement"
6}'

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

Pricing Agreement ReminderobjectRequired

Example response

Response
1{
2  "reminderId": "1234567",
3  "type": "pricingAgreement"
4}