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:

Example request

POST
/v1/merchant-platforms/:merchantPlatformId/processing-accounts
1curl -X POST https://api.payroc.com/v1/merchant-platforms/12345/processing-accounts \
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        "address2": "Example Address Line 2",
19        "address3": "Example Address Line 3"
20      },
21      "identifiers": [
22        {
23          "type": "nationalId",
24          "value": "000-00-4320"
25        }
26      ],
27      "contactMethods": [
28        {
29          "type": "email",
30          "value": "[email protected]"
31        }
32      ],
33      "relationship": {
34        "isControlProng": true,
35        "equityPercentage": 51.5,
36        "title": "CFO",
37        "isAuthorizedSignatory": false
38      },
39      "middleName": "Helen"
40    }
41  ],
42  "businessType": "restaurant",
43  "categoryCode": 5999,
44  "merchandiseOrServiceSold": "Pizza",
45  "businessStartDate": "2020-01-01",
46  "timezone": "America/Chicago",
47  "address": {
48    "address1": "1 Example Ave.",
49    "address2": "Example Address Line 2",
50    "address3": "Example Address Line 3",
51    "city": "Chicago",
52    "state": "Illinois",
53    "country": "US",
54    "postalCode": "60056"
55  },
56  "contactMethods": [
57    {
58      "type": "email",
59      "value": "[email protected]"
60    }
61  ],
62  "processing": {
63    "transactionAmounts": {
64      "average": 5000,
65      "highest": 10000
66    },
67    "monthlyAmounts": {
68      "average": 50000,
69      "highest": 100000
70    },
71    "volumeBreakdown": {
72      "cardPresentKeyed": 47,
73      "cardPresentSwiped": 30,
74      "mailOrTelephone": 3,
75      "ecommerce": 20
76    },
77    "isSeasonal": true,
78    "monthsOfOperation": [
79      "jan",
80      "feb"
81    ],
82    "ach": {
83      "refunds": {
84        "writtenRefundPolicy": true,
85        "refundPolicyUrl": "www.example.com/refund-poilcy-url"
86      },
87      "estimatedMonthlyTransactions": 3000,
88      "limits": {
89        "singleTransaction": 10000,
90        "dailyDeposit": 200000,
91        "monthlyDeposit": 6000000
92      },
93      "naics": "5812",
94      "previouslyTerminatedForAch": false,
95      "transactionTypes": [
96        "prearrangedPayment",
97        "other"
98      ],
99      "transactionTypesOther": "anotherTransactionType"
100    },
101    "cardAcceptance": {
102      "debitOnly": false,
103      "hsaFsa": false,
104      "cardsAccepted": [
105        "visa",
106        "mastercard"
107      ],
108      "specialityCards": {
109        "americanExpressDirect": {
110          "enabled": true,
111          "merchantNumber": "abc1234567"
112        },
113        "electronicBenefitsTransfer": {
114          "enabled": true,
115          "fnsNumber": "6789012"
116        },
117        "other": {
118          "wexMerchantNumber": "abc1234567",
119          "voyagerMerchantId": "abc1234567",
120          "fleetMerchantId": "abc1234567"
121        }
122      }
123    }
124  },
125  "funding": {
126    "acceleratedFundingFee": 1999,
127    "dailyDiscount": false,
128    "fundingAccounts": [
129      {
130        "type": "checking",
131        "use": "creditAndDebit",
132        "nameOnAccount": "Jane Doe",
133        "paymentMethods": [
134          {
135            "type": "ach",
136            "value": {
137              "routingNumber": "123456789",
138              "accountNumber": "1234567890"
139            }
140          }
141        ],
142        "metadata": {
143          "yourCustomField": "abc123"
144        }
145      }
146    ],
147    "fundingSchedule": "nextday"
148  },
149  "pricing": {
150    "type": "intent",
151    "pricingIntentId": 6123
152  },
153  "signature": {
154    "type": "requestedViaDirectLink"
155  },
156  "website": "www.example.com",
157  "contacts": [
158    {
159      "type": "manager",
160      "firstName": "Jane",
161      "lastName": "Doe",
162      "identifiers": [
163        {
164          "type": "nationalId",
165          "value": "000-00-4320"
166        }
167      ],
168      "contactMethods": [
169        {
170          "type": "email",
171          "value": "[email protected]"
172        }
173      ],
174      "middleName": "Helen"
175    }
176  ],
177  "metadata": {
178    "customerId": "2345"
179  }
180}'

Response fields

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

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:

Example request

POST
/v1/processing-accounts/:processingAccountId/reminders
1curl -X POST https://api.payroc.com/v1/processing-accounts/38765/reminders \
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:

Example response

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