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.

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:

Include your API key in the x-api-key parameter in the header of a POST request.
Send your request to https://identity.payroc.com/authorize.

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.

{
"access_token": "eyJhbGc....adQssw5c",
"expires_in": 3600,
"scope": "service_a service_b",
"token_type": "Bearer"
}

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:
Test endpoint: https://api.uat.payroc.com/v1/merchant-platforms/{merchantPlatformId}/processing-accounts
Production endpoint: https://api.payroc.com/v1/merchant-platforms/{merchantPlatformId}/processing-accounts

Request parameters

Path parameters

Header parameters

Body parameters

Example request

Request

curl --request post \
	--url https://api.payroc.com/v1/merchant-platforms/12345/processing-accounts \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"doingBusinessAs":"Pizza Doe","owners":[{"firstName":"Jane","middleName":"Helen","lastName":"Doe","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"000-00-4320"}],"contactMethods":[{"type":"email","value":"[email protected]"}],"relationship":{"equityPercentage":51.5,"title":"CFO","isControlProng":true,"isAuthorizedSignatory":false}}],"website":"www.example.com","businessType":"restaurant","categoryCode":5999,"merchandiseOrServiceSold":"Pizza","businessStartDate":"2020-01-01","timezone":"America/Chicago","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"contactMethods":[{"type":"email","value":"[email protected]"}],"processing":{"transactionAmounts":{"average":5000,"highest":10000},"monthlyAmounts":{"average":50000,"highest":100000},"volumeBreakdown":{"cardPresentKeyed":47,"cardPresentSwiped":30,"mailOrTelephone":3,"ecommerce":20},"isSeasonal":true,"monthsOfOperation":["jan","feb"],"ach":{"naics":"5812","previouslyTerminatedForAch":false,"refunds":{"writtenRefundPolicy":true,"refundPolicyUrl":"www.example.com/refund-poilcy-url"},"estimatedMonthlyTransactions":3000,"limits":{"singleTransaction":10000,"dailyDeposit":200000,"monthlyDeposit":6000000},"transactionTypes":["prearrangedPayment","other"],"transactionTypesOther":"anotherTransactionType"},"cardAcceptance":{"debitOnly":false,"cardsAccepted":["visa","mastercard"],"specialityCards":{"americanExpressDirect":{"enabled":true,"merchantNumber":"abc1234567"},"electronicBenefitsTransfer":{"enabled":true,"fnsNumber":"6789012"},"other":{"wexMerchantNumber":"abc1234567","voyagerMerchantId":"abc1234567","fleetMerchantId":"abc1234567"}}}},"funding":{"fundingSchedule":"nextday","acceleratedFundingFee":1999,"dailyDiscount":false,"fundingAccounts":[{"type":"checking","use":"creditAndDebit","nameOnAccount":"Jane Doe","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"yourCustomField":"abc123"}}]},"pricing":{"type":"intent","pricingIntentId":6123},"signature":"requestedViaDirectLink","contacts":[{"type":"manager","firstName":"Jane","middleName":"Helen","lastName":"Doe","identifiers":[{"type":"nationalId","value":"000-00-4320"}],"contactMethods":[{"type":"email","value":"[email protected]"}]}],"metadata":{"customerId":"2345"}}'

Response fields

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

Response Schema

Status Code 201

Successful request. We created the processing account.

Response headers

Response body

Example response

Response

application/json

{
  "processingAccountId": "38765",
  "createdDate": "2020-09-08T12:00:00.000Z",
  "lastModifiedDate": "2020-09-08T12:00:00.000Z",
  "status": "entered",
  "doingBusinessAs": "Pizza Doe",
  "owners": [
    {
      "ownerId": 4564,
      "firstName": "Jane",
      "lastName": "Doe",
      "link": {
        "rel": "owner",
        "href": "https://api.payroc.com/v1/owners/4564",
        "method": "get"
      }
    }
  ],
  "website": "www.example.com",
  "businessType": "restaurant",
  "categoryCode": 5999,
  "merchandiseOrServiceSold": "Pizza",
  "businessStartDate": "2020-01-01",
  "timezone": "America/Chicago",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "contactMethods": [
    {
      "type": "email",
      "value": "[email protected]"
    }
  ],
  "processing": {
    "transactionAmounts": {
      "average": 5000,
      "highest": 10000
    },
    "monthlyAmounts": {
      "average": 50000,
      "highest": 100000
    },
    "volumeBreakdown": {
      "cardPresentKeyed": 47,
      "cardPresentSwiped": 30,
      "mailOrTelephone": 3,
      "ecommerce": 20
    },
    "isSeasonal": true,
    "monthsOfOperation": [
      "jan",
      "feb"
    ],
    "ach": {
      "naics": "5812",
      "previouslyTerminatedForAch": false,
      "refunds": {
        "writtenRefundPolicy": true,
        "refundPolicyUrl": "www.example.com/refund-poilcy-url"
      },
      "estimatedMonthlyTransactions": 3000,
      "limits": {
        "singleTransaction": 10000,
        "dailyDeposit": 200000,
        "monthlyDeposit": 6000000
      },
      "transactionTypes": [
        "prearrangedPayment",
        "other"
      ],
      "transactionTypesOther": "anotherTransactionType"
    },
    "cardAcceptance": {
      "debitOnly": false,
      "cardsAccepted": [
        "visa",
        "mastercard"
      ],
      "specialityCards": {
        "americanExpressDirect": {
          "enabled": true,
          "merchantNumber": "abc1234567"
        },
        "electronicBenefitsTransfer": {
          "enabled": true,
          "fnsNumber": "6789012"
        },
        "other": {
          "wexMerchantNumber": "abc1234567",
          "voyagerMerchantId": "abc1234567",
          "fleetMerchantId": "abc1234567"
        }
      }
    }
  },
  "funding": {
    "status": "enabled",
    "fundingSchedule": "nextday",
    "acceleratedFundingFee": 1999,
    "dailyDiscount": false,
    "fundingAccounts": [
      {
        "fundingAccountId": 123,
        "status": "pending",
        "link": {
          "rel": "fundingAccount",
          "method": "get",
          "href": "https://api.payroc.com/v1/funding-account/123"
        }
      }
    ]
  },
  "pricing": {
    "link": {
      "rel": "pricing",
      "href": "https://api.payroc.com/v1/processing-account/12345/pricing",
      "method": "get"
    }
  },
  "contacts": [
    {
      "contactId": 1543,
      "firstName": "Jane",
      "lastName": "Doe",
      "link": {
        "rel": "contact",
        "href": "https://api.payroc.com/v1/contacts/1543",
        "method": "get"
      }
    }
  ],
  "signature": {
    "type": "requestedViaDirectLink",
    "link": {
      "rel": "agreement",
      "href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000",
      "method": "get"
    }
  },
  "metadata": {
    "customerId": "2345"
  }
}

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.

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.

Test endpoint: https://api.uat.payroc.com/v1/processing-accounts/{processingAccountId}/reminders
Production endpoint: https://api.payroc.com/v1/processing-accounts/{processingAccountId}/reminders

Request parameters

Path parameters

Body parameters

Example request

Request

curl --request post \
	--url https://api.payroc.com/v1/processing-accounts/38765/reminders \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"type":"pricingAgreement"}'

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 Schema

Status Code 201

Successful request. We sent the email to the merchant.

Response body

Example response

Response

application/json

{
  "reminderId": "1234567",
  "type": "pricingAgreement"
}

Add a processing account to a merchant platform

Example request

Example response

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Response headers

Response body

Path parameters

Body parameters

Response Schema

Status Code 201

Response body