IntegrateBoarding

Create a merchant platform

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

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 of the merchant platform.
createdDatestringOptionalformat: "date-time"
Date that the merchant platform was created.
lastModifiedDatestringOptionalformat: "date-time"
Date that the merchant platform was last modified.
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      "processingAccountId": "38765",
29      "doingBusinessAs": "Pizza Doe",
30      "status": "pending",
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          "href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000",
41          "method": "get"
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

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}