Financial accounts associated with entities

List funding accounts

GET /funding-accounts

Retrieve a list of all funding accounts associated with the ISV.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of all funding accounts.

Response body

Request

curl --request get \
	--url https://api.payroc.com/v1/funding-accounts

Response

application/json

{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-accounts?before=123&limit=2"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-accounts?after=124&limit=2"
    }
  ],
  "data": [
    {
      "fundingAccountId": 123,
      "createdDate": "2020-09-08T12:00:00.000Z",
      "lastModifiedDate": "2020-09-08T12:00:00.000Z",
      "status": "approved",
      "type": "checking",
      "use": "credit",
      "nameOnAccount": "Joe Bloggs",
      "paymentMethods": [
        {
          "type": "ach",
          "value": {
            "routingNumber": "*****6789",
            "accountNumber": "******7890"
          }
        }
      ],
      "metadata": {
        "internalRef": "2345"
      },
      "links": [
        {
          "rel": "parent",
          "href": "https://api.payroc.com/v1/merchants/1234",
          "method": "get"
        }
      ]
    },
    {
      "fundingAccountId": 124,
      "createdDate": "2021-01-08T12:00:00.000Z",
      "lastModifiedDate": "2021-01-08T12:00:00.000Z",
      "status": "pending",
      "type": "checking",
      "use": "debit",
      "nameOnAccount": "Joe Bloggs",
      "paymentMethods": [
        {
          "type": "ach",
          "value": {
            "routingNumber": "*****8725",
            "accountNumber": "******3491"
          }
        }
      ],
      "metadata": {
        "internalRef": "2346"
      },
      "links": [
        {
          "rel": "parent",
          "href": "https://api.payroc.com/v1/funding-recipient/2",
          "method": "get"
        }
      ]
    }
  ]
}

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

Retrieve funding account

GET /funding-accounts/{fundingId}

Retrieve a specific funding account.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested funding account.

Response body

Request

curl --request get \
	--url https://api.payroc.com/v1/funding-accounts/89

Response

application/json

{
  "fundingAccountId": 123,
  "createdDate": "2020-09-08T12:00:00.000Z",
  "lastModifiedDate": "2020-09-08T12:00:00.000Z",
  "status": "pending",
  "type": "checking",
  "use": "credit",
  "nameOnAccount": "Joe Bloggs",
  "paymentMethods": [
    {
      "type": "ach",
      "value": {
        "routingNumber": "*****6789",
        "accountNumber": "******7890"
      }
    }
  ],
  "metadata": {
    "internalRef": "2345"
  },
  "links": [
    {
      "rel": "parent",
      "href": "https://api.payroc.com/v1/merchants/1234",
      "method": "get"
    }
  ]
}

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

Update funding account

PUT /funding-accounts/{fundingId}

Update a funding account.

Path parameters

Body parameters

Response Schema

Status Code 204

Successful request. We updated the funding account.

Request

curl --request put \
	--url https://api.payroc.com/v1/funding-accounts/89 \
	--header 'Content-Type: application/json' \
	--data '{"type":"checking","use":"credit","nameOnAccount":"Joe Bloggs","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"internalRef":"2345"}}'

Errors

Error	Description
Bad Request	One or more validation errors occurred
KYC check failed	KYC check failed
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Not acceptable	Requested representation not supported
Api error	Unable to process your request.

Delete funding account

DELETE /funding-accounts/{fundingId}

Delete a funding account.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the funding account.

Request

curl --request delete \
	--url https://api.payroc.com/v1/funding-accounts/89

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

Funding activity

Activity associated with a payfac account

Retrieve funding balance

GET /funding-balance

Retrieve the balance of funds that are available for each merchant.

Query parameters

Response Schema

Status Code 200

Successful request. Returns the balance available for each merchant.

Response body

Request

curl --request get \
	--url https://api.payroc.com/v1/funding-balance

Response

application/json

{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-balance?before=65&limit=2"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-balance?after=66&limit=2"
    }
  ],
  "data": [
    {
      "merchantId": "65",
      "funds": 120000,
      "pending": 50050,
      "available": 69950,
      "currency": "USD"
    },
    {
      "merchantId": "66",
      "funds": 50000,
      "pending": 0,
      "available": 50000,
      "currency": "USD"
    }
  ]
}

Errors

Error	Description
Bad request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not acceptable	Requested representation not supported
Api error	Unable to process your request.

List funding activity

GET /funding-activity

Retrieve funding activity for a specific date range.

Query parameters

Response Schema

Status Code 200

Successful request. Returns all available funding activity for the date range.

Response body

Request

curl --request get \
	--url 'https://api.payroc.com/v1/funding-activity?dateFrom=2022-10-01&dateTo=2022-10-01'

Response

application/json

{
  "limit": 10,
  "count": 10,
  "hasMore": true,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-activity?before=11&limit=10&datefrom=2021-01-01&dateto=2021-01-30"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-activity?after=20&limit=10&datefrom=2021-01-01&dateto=2021-01-30"
    }
  ],
  "data": [
    {
      "id": "11",
      "date": "2021-01-01T17:00:00.000Z",
      "merchant": "Joes Hot dogs",
      "description": "sales",
      "type": "credit",
      "amount": 20000,
      "currency": "USD"
    },
    {
      "id": "12",
      "date": "2021-01-01T19:32:00.000Z",
      "merchant": "Joes Hot dogs",
      "description": "sales",
      "type": "credit",
      "amount": 50000,
      "currency": "USD"
    },
    {
      "id": "13",
      "date": "2021-01-01T17:00:00.000Z",
      "merchant": "Joes Hot dogs",
      "recipient": "Joes Hot dogs",
      "description": "payment",
      "type": "debit",
      "amount": 10000,
      "currency": "USD"
    },
    {
      "id": "14",
      "date": "2021-01-01T17:00:00.000Z",
      "merchant": "Joes Hot dogs",
      "recipient": "Payroc",
      "description": "Interchange Fees",
      "type": "debit",
      "amount": 500,
      "currency": "USD"
    },
    {
      "id": "15",
      "date": "2021-01-03T09:10:00.000Z",
      "merchant": "Joes Hot dogs",
      "description": "sales",
      "type": "credit",
      "amount": 30000,
      "currency": "USD"
    },
    {
      "id": "16",
      "date": "2021-01-10T17:00:00.000Z",
      "merchant": "Janes shoe laces LTD",
      "description": "adjustment",
      "type": "credit",
      "amount": 500,
      "currency": "USD"
    },
    {
      "id": "17",
      "date": "2021-01-10T17:00:00.000Z",
      "merchant": "Janes shoe laces LTD",
      "recipient": "Payroc",
      "description": "Interchange Fees",
      "type": "debit",
      "amount": 500,
      "currency": "USD"
    },
    {
      "id": "18",
      "date": "2021-01-15T17:00:00.000Z",
      "merchant": "Joes Hot dogs",
      "recipient": "Payroc",
      "description": "Charge back",
      "type": "debit",
      "amount": 1000,
      "currency": "USD"
    },
    {
      "id": "19",
      "date": "2021-01-17T17:00:00.000Z",
      "merchant": "Janes shoe laces LTD",
      "description": "sales",
      "type": "credit",
      "amount": 50000,
      "currency": "USD"
    },
    {
      "id": "20",
      "date": "2021-01-26T17:00:00.000Z",
      "merchant": "Joes Hot dogs",
      "recipient": "Mr Payfac corp",
      "description": "payment",
      "type": "debit",
      "amount": 5000,
      "currency": "USD"
    }
  ]
}

Errors

Error	Description
Bad request	One or more validation errors occurred.
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not acceptable	Requested representation not supported
Api error	Unable to process your request.

Funding instructions

Instructions on how to split fund between recipients

Create Funding Instruction

POST /funding-instructions

Create funding instructions to tell us how to divide funds between your funding recipients.

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We accepted the instructions.

Response headers

Response body

Request

curl --request post \
	--url https://api.payroc.com/v1/funding-instructions \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: abc123' \
	--data '{"merchants":[{"merchantId":"123456","recipients":[{"fundingAccountId":5432425374,"paymentMethod":"ACH","amount":{"value":12350,"currency":"USD"},"metadata":{"customerId":"2345"}}]}],"metadata":{"internalInstructionRef":"abcdef"}}'

Response

application/json

{
  "instructionId": 123,
  "createdDate": "2021-09-05T13:15:00.000Z",
  "lastModifiedDate": null,
  "status": "accepted",
  "merchants": [
    {
      "merchantId": "99999",
      "recipients": [
        {
          "status": "accepted",
          "fundingAccountId": 67890,
          "paymentMethod": "ACH",
          "amount": {
            "value": 12350,
            "currency": "USD"
          },
          "metadata": {
            "customerId": "2345"
          },
          "link": {
            "rel": "fundingAccount",
            "method": "get",
            "href": "https://api.payroc.com/v1/funding-accounts/67890"
          }
        }
      ],
      "link": {
        "rel": "merchant",
        "method": "get",
        "href": "https://api.payroc.com/v1/merchants/99999"
      }
    }
  ],
  "metadata": {
    "instructionRef": "abcd"
  }
}

Errors

Error	Description
Bad Request	One or more validation errors occurred
Insufficient funds	You do not have enough funds to complete the request.
Idempotency key missing	Idempotency key must be supplied
Funding accounts restricted	Funding accounts restricted.
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not acceptable	Requested representation not supported
Idempotency key in use	Idempotency key in use
Api error	Unable to process your request.

List funding instructions

GET /funding-instructions

Retrieve a list of funding instructions for a specific date range.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of funding instructions.

Response body

Request

curl --request get \
	--url 'https://api.payroc.com/v1/funding-instructions?dateFrom=2022-10-01&dateTo=2022-10-01'

Response

application/json

{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-instructions?before=65&limit=2&datefrom=2021-01-01&dateto=2021-01-30"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-instructions?after=66&limit=2&datefrom=2021-01-01&dateto=2021-01-30"
    }
  ],
  "data": [
    {
      "instructionId": 65,
      "createdDate": "2021-09-05T13:15:00.000Z",
      "lastModifiedDate": "2021-09-06T18:00:00.000Z",
      "status": "completed",
      "merchants": [
        {
          "merchantId": "99999",
          "recipients": [
            {
              "status": "funded",
              "fundingAccountId": 67890,
              "paymentMethod": "ACH",
              "amount": {
                "value": 12350,
                "currency": "USD"
              },
              "metadata": {
                "customerId": "2345"
              },
              "link": {
                "rel": "fundingAccount",
                "method": "get",
                "href": "https://api.payroc.com/v1/funding-accounts/67890"
              }
            },
            {
              "status": "rejected",
              "fundingAccountId": 67889,
              "paymentMethod": "ACH",
              "amount": {
                "value": 9000,
                "currency": "USD"
              },
              "metadata": {
                "customerId": "2345"
              },
              "link": {
                "rel": "fundingAccount",
                "method": "get",
                "href": "https://api.payroc.com/v1/funding-accounts/67889"
              }
            }
          ],
          "link": {
            "rel": "merchant",
            "method": "get",
            "href": "https://api.payroc.com/v1/merchants/99999"
          }
        }
      ],
      "metadata": {
        "instrcutionRef": "abcd"
      },
      "link": {
        "rel": "fundingInstruction",
        "method": "get",
        "href": "https://api.payroc.com/v1/funding-instructions/65"
      }
    },
    {
      "instructionId": 66,
      "createdDate": "2021-09-06T13:15:00.000Z",
      "lastModifiedDate": null,
      "status": "accepted",
      "merchants": [
        {
          "merchantId": "12345",
          "recipients": [
            {
              "status": "accepted",
              "fundingAccountId": 54784,
              "paymentMethod": "ACH",
              "amount": {
                "value": 5000,
                "currency": "USD"
              },
              "metadata": {
                "customerId": "5412"
              },
              "link": {
                "rel": "fundingAccount",
                "method": "get",
                "href": "https://api.payroc.com/v1/funding-accounts/54784"
              }
            }
          ],
          "link": {
            "rel": "merchant",
            "method": "get",
            "href": "https://api.payroc.com/v1/merchants/12345"
          }
        },
        {
          "merchantId": 12346,
          "recipients": [
            {
              "status": "accepted",
              "fundingAccountId": 54784,
              "paymentMethod": "ACH",
              "amount": {
                "value": 1000,
                "currency": "USD"
              },
              "metadata": {
                "customerId": "5412"
              },
              "link": {
                "rel": "fundingAccount",
                "method": "get",
                "href": "https://api.payroc.com/v1/funding-accounts/54784"
              }
            }
          ],
          "link": {
            "rel": "merchant",
            "method": "get",
            "href": "https://api.payroc.com/v1/merchants/12346"
          }
        }
      ],
      "metadata": {
        "instrcutionRef": "efgh"
      },
      "link": {
        "rel": "fundingInstruction",
        "method": "get",
        "href": "https://api.payroc.com/v1/funding-instructions/66"
      }
    }
  ]
}

Errors

Error	Description
Bad request	One or more validation errors occurred.
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not acceptable	Requested representation not supported
Api error	Unable to process your request.

Retrieve funding instruction

GET /funding-instructions/{instructionId}

Retrieve a specific funding instruction.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested funding instruction.

Response body

Request

curl --request get \
	--url https://api.payroc.com/v1/funding-instructions/89

Response

application/json

{
  "instructionId": 12345,
  "createdDate": "2021-09-05T13:15:00.000Z",
  "lastModifiedDate": "2021-09-06T18:00:00.000Z",
  "status": "accepted",
  "merchants": [
    {
      "merchantId": "123456",
      "recipients": [
        {
          "fundingAccountId": 5432425374,
          "paymentMethod": "ACH",
          "amount": {
            "value": 12350,
            "currency": "USD"
          },
          "status": "accepted",
          "metadata": {
            "customerId": "2345"
          },
          "link": {
            "rel": "fundingAccount",
            "method": "get",
            "href": "https://api.payroc.com/v1/funding-accounts/5432425374"
          }
        }
      ],
      "link": {
        "rel": "merchant",
        "method": "get",
        "href": "https://api.payroc.com/v1/merchants/123456"
      }
    }
  ],
  "metadata": {
    "internalInstructionRef": "abcdef"
  }
}

Errors

Error	Description
Bad request	One or more validation errors occurred.
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Not acceptable	Requested representation not supported
Api error	Unable to process your request.

Update Funding Instruction

PUT /funding-instructions/{instructionId}

Update an existing funding instruction.

Path parameters

Body parameters

Response Schema

Status Code 204

Successful request. We updated the funding instruction.

Request

curl --request put \
	--url https://api.payroc.com/v1/funding-instructions/89 \
	--header 'Content-Type: application/json' \
	--data '{"merchants":[{"merchantId":"123456","recipients":[{"fundingAccountId":5432425374,"paymentMethod":"ACH","amount":{"value":12350,"currency":"USD"},"metadata":{"customerId":"2345"}}]}],"metadata":{"internalInstructionRef":"abcdef"}}'

Errors

Error	Description
Bad Request	One or more validation errors occurred
Insufficient funds	You do not have enough funds to complete the request.
Cannot be modified	Resource cannot be modified.
Bad request	One or more validation errors occurred.
Funding accounts restricted	Funding accounts restricted.
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

Delete Funding Instruction

DELETE /funding-instructions/{instructionId}

Delete an existing funding instruction.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the funding instruction.

Request

curl --request delete \
	--url https://api.payroc.com/v1/funding-instructions/89

Errors

Error	Description
Cannot be modified	Resource cannot be modified.
Bad request	One or more validation errors occurred.
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

Funding recipient

Entities that can receive funding but not take payments

Create funding recipient

POST /funding-recipients

Create a funding recipient.

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the funding recipient.

Response headers

Response body

Request

curl --request post \
	--url https://api.payroc.com/v1/funding-recipients \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: abc123' \
	--data '{"recipientType":"solepr","taxId":"123456789","charityId":"abc123","doingBusinessAs":"abc123","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"contactMethods":[{"type":"phone","value":"abc123"}],"metadata":{"customerId":"2345"},"persons":[{"firstName":"David","lastName":"Simpson","dateOfBirth":"1964-03-22T00:00:00.000Z","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"987-65-4320"}],"contactMethods":[{"type":"phone","value":"617 715 1234"},{"type":"mobile","value":"856 457 8745"},{"type":"email","value":"[email protected]"}],"relationship":{"equityPercentage":35.4,"position":"primary","title":"abc123"}}],"fundingAccounts":[{"type":"checking","use":"credit","nameOnAccount":"Joe Bloggs","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"internalRef":"2345"}}]}'

Response

application/json

{
  "recipientId": 1,
  "status": "approved",
  "createdDate": "2020-09-08T12:00:00.000Z",
  "lastModifiedDate": "2020-09-08T12:00:00.000Z",
  "recipientType": "solepr",
  "taxId": "123456789",
  "charityId": "abc123",
  "doingBuinessAs": "abc123",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "abc123",
    "address3": "abc123",
    "city": "Example city",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "contactMethods": [
    {
      "type": "phone",
      "value": "abc123"
    }
  ],
  "metadata": {
    "customerId": "2345"
  },
  "persons": [
    {
      "personId": 1,
      "link": {
        "rel": "person",
        "href": "https://api.payroc.com/v1/persons/1",
        "method": "get"
      }
    }
  ],
  "fundingAccounts": [
    {
      "fundingAccountId": 1,
      "status": "approved",
      "link": {
        "rel": "fundingAccount",
        "herf": "https://api.payroc.com/v1/funding-accounts/1",
        "method": "get"
      }
    },
    {
      "fundingAccountId": 2,
      "status": "rejected",
      "link": {
        "rel": "fundingAccount",
        "herf": "https://api.payroc.com/v1/funding-accounts/2",
        "method": "get"
      }
    }
  ]
}

Errors

Error	Description
Idempotency key missing	Idempotency key must be supplied
Bad Request	One or more validation errors occurred
KYC check failed	KYC check failed
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not acceptable	Requested representation not supported
Idempotency key in use	Idempotency key in use
Api error	Unable to process your request.

List funding recipients

GET /funding-recipients

Retrieve a list of all funding recipients associated with the ISV.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of all funding recipients.

Response body

Request

curl --request get \
	--url https://api.payroc.com/v1/funding-recipients

Response

application/json

{
  "limit": 10,
  "count": 1,
  "hasMore": false,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-recipients?before=12345&limit=10"
    }
  ],
  "data": [
    {
      "recipientId": 12345,
      "status": "approved",
      "createdDate": "2020-09-08T12:00:00.000Z",
      "lastModifiedDate": "2020-09-08T12:00:00.000Z",
      "recipientType": "solepr",
      "taxId": "123456789",
      "doingBuinessAs": "Example llc",
      "address": {
        "address1": "1 Example Ave.",
        "city": "Example city",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      },
      "contactMethods": [
        {
          "type": "phone",
          "value": "123 456 7890"
        }
      ],
      "metadata": {
        "customerId": 12345
      },
      "persons": [
        {
          "personId": 1,
          "link": {
            "rel": "person",
            "method": "get",
            "href": "https://api.payroc.com/v1/persons/1"
          }
        }
      ],
      "fundingAccounts": [
        {
          "fundingAccountId": 1,
          "status": "approved",
          "link": {
            "rel": "fundingAccount",
            "method": "get",
            "href": "https://api.payroc.com/v1/funding-accounts/1"
          }
        },
        {
          "fundingAccountId": 2,
          "status": "hold",
          "link": {
            "rel": "fundingAccount",
            "method": "get",
            "href": "https://api.payroc.com/v1/funding-accounts/2"
          }
        }
      ]
    }
  ]
}

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Api error	Unable to process your request.

Retrieve a funding recipient

GET /funding-recipients/{recipientId}

Retrieve a specific funding recipient.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested funding recipient.

Response body

Request

curl --request get \
	--url https://api.payroc.com/v1/funding-recipients/89

Response

application/json

{
  "recipientId": 12345,
  "status": "approved",
  "createdDate": "2020-09-08T12:00:00.000Z",
  "lastModifiedDate": "2020-09-08T12:00:00.000Z",
  "recipientType": "solepr",
  "taxId": "123456789",
  "doingBuinessAs": "Example llc",
  "address": {
    "address1": "1 Example Ave.",
    "city": "Example city",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "contactMethods": [
    {
      "type": "phone",
      "value": "123 456 7890"
    }
  ],
  "metadata": {
    "customerId": 12345
  },
  "persons": [
    {
      "personId": 1,
      "link": {
        "rel": "person",
        "method": "get",
        "href": "https://api.payroc.com/v1/persons/1"
      }
    }
  ],
  "fundingAccounts": [
    {
      "fundingAccountId": 1,
      "status": "approved",
      "link": {
        "rel": "fundingAccount",
        "method": "get",
        "href": "https://api.payroc.com/v1/funding-accounts/1"
      }
    },
    {
      "fundingAccountId": 2,
      "status": "hold",
      "link": {
        "rel": "fundingAccount",
        "method": "get",
        "href": "https://api.payroc.com/v1/funding-accounts/2"
      }
    }
  ]
}

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

Update funding recipient

PUT /funding-recipients/{recipientId}

Update a funding recipient. If you make significant changes, we may need to approve the funding recipient again.

Path parameters

Body parameters

Response Schema

Status Code 204

Successful request. We updated the funding recipient.

Request

curl --request put \
	--url https://api.payroc.com/v1/funding-recipients/89 \
	--header 'Content-Type: application/json' \
	--data '{"recipientType":"solepr","taxId":"123456789","charityId":"abc123","doingBuinessAs":"abc123","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"contactMethods":[{"type":"phone","value":"abc123"}],"metadata":{"customerId":"2345"}}'

Errors

Error	Description
Bad Request	One or more validation errors occurred
KYC check failed	KYC check failed
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Not acceptable	Requested representation not supported
Api error	Unable to process your request.

Delete funding recipient

DELETE /funding-recipients/{recipientId}

Delete a funding recipient. This includes funding accounts and persons linked to the funding recipient.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the funding recipient.

Request

curl --request delete \
	--url https://api.payroc.com/v1/funding-recipients/89

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

List Funding Accounts

GET /funding-recipients/{recipientId}/funding-accounts

Retrieve all funding accounts associated with the funding recipient.

Path parameters

Response Schema

Status Code 200

Successful request. Returns a list of all funding accounts associated with the funding recipient.

Response body

array of funding account objects

Request

curl --request get \
	--url https://api.payroc.com/v1/funding-recipients/89/funding-accounts

Response

application/json

[
  {
    "fundingAccountId": 123,
    "createdDate": "2020-09-08T12:00:00.000Z",
    "lastModifiedDate": "2020-09-08T12:00:00.000Z",
    "status": "approved",
    "type": "checking",
    "use": "credit",
    "nameOnAccount": "Joe Bloggs",
    "paymentMethods": [
      {
        "type": "ach",
        "value": {
          "routingNumber": "*****6789",
          "accountNumber": "******7890"
        }
      }
    ],
    "metadata": {
      "internalRef": "2345"
    },
    "links": [
      {
        "rel": "parent",
        "href": "https://api.payroc.com/v1/funding-recipient/2",
        "method": "get"
      }
    ]
  },
  {
    "fundingAccountId": 124,
    "createdDate": "2021-01-08T12:00:00.000Z",
    "lastModifiedDate": "2021-01-08T12:00:00.000Z",
    "status": "pending",
    "type": "checking",
    "use": "debit",
    "nameOnAccount": "Joe Bloggs",
    "paymentMethods": [
      {
        "type": "ach",
        "value": {
          "routingNumber": "*****8725",
          "accountNumber": "******3491"
        }
      }
    ],
    "metadata": {
      "internalRef": "2346"
    },
    "links": [
      {
        "rel": "parent",
        "href": "https://api.payroc.com/v1/funding-recipient/2",
        "method": "get"
      }
    ]
  }
]

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

Create Funding Account

POST /funding-recipients/{recipientId}/funding-accounts

Create a new funding account, and add it to the funding recipient.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the funding account and added it to the funding recipient.

Response headers

Response body

Request

curl --request post \
	--url https://api.payroc.com/v1/funding-recipients/89/funding-accounts \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: abc123' \
	--data '{"type":"checking","use":"credit","nameOnAccount":"Joe Bloggs","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"internalRef":"2345"}}'

Response

application/json

{
  "fundingAccountId": 123,
  "createdDate": "2020-09-08T12:00:00.000Z",
  "lastModifiedDate": "2020-09-08T12:00:00.000Z",
  "status": "approved",
  "type": "checking",
  "use": "credit",
  "nameOnAccount": "Joe Bloggs",
  "paymentMethods": [
    {
      "type": "ach",
      "value": {
        "routingNumber": "*****6789",
        "accountNumber": "******7890"
      }
    }
  ],
  "metadata": {
    "internalRef": "2345"
  },
  "links": [
    {
      "rel": "parent",
      "href": "https://api.payroc.com/v1/funding-recipient/2",
      "method": "get"
    }
  ]
}

Errors

Error	Description
Idempotency key missing	Idempotency key must be supplied
Bad Request	One or more validation errors occurred
KYC check failed	KYC check failed
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Not acceptable	Requested representation not supported
Idempotency key in use	Idempotency key in use
Api error	Unable to process your request.

List Persons

GET /funding-recipients/{recipientId}/persons

Retrieve all persons associated with the funding recipient.

Path parameters

Response Schema

Status Code 200

Successful request. Returns a list of all persons associated with the funding recipient.

Response body

array of person objects

Request

curl --request get \
	--url https://api.payroc.com/v1/funding-recipients/89/persons

Response

application/json

{
  "personId": 1543,
  "firstName": "David",
  "lastName": "Simpson",
  "dateOfBirth": "1964-03-22T00:00:00.000Z",
  "address": {
    "address1": "1 Example Ave.",
    "city": "Example city",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "identifiers": [
    {
      "type": "nationalId",
      "value": "987-65-4320"
    }
  ],
  "contactMethods": [
    {
      "type": "email",
      "value": "[email protected]"
    },
    {
      "type": "phone",
      "value": "123 456 7890"
    },
    {
      "type": "mobile",
      "value": "098 765 4321"
    }
  ],
  "relationship": {
    "equityPercentage": 35.4,
    "position": "primary",
    "title": "string",
    "isControllingPerson": true
  }
}

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

Create Person

POST /funding-recipients/{recipientId}/persons

Create a new person, and add it to the funding recipient.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the person and added it to the funding recipient.

Response headers

Response body

Request

curl --request post \
	--url https://api.payroc.com/v1/funding-recipients/89/persons \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: abc123' \
	--data '{"firstName":"David","lastName":"Simpson","dateOfBirth":"1964-03-22T00:00:00.000Z","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"987-65-4320"}],"contactMethods":[{"type":"phone","value":"617 715 1234"},{"type":"mobile","value":"856 457 8745"},{"type":"email","value":"[email protected]"}],"relationship":{"equityPercentage":35.4,"position":"primary","title":"abc123"}}'

Response

application/json

{
  "personId": 1543,
  "firstName": "David",
  "lastName": "Simpson",
  "dateOfBirth": "1964-03-22T00:00:00.000Z",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "abc123",
    "address3": "abc123",
    "city": "Example city",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "identifiers": [
    {
      "type": "nationalId",
      "value": "987-65-4320"
    }
  ],
  "contactMethods": [
    {
      "type": "phone",
      "value": "617 715 1234"
    },
    {
      "type": "mobile",
      "value": "856 457 8745"
    },
    {
      "type": "email",
      "value": "[email protected]"
    }
  ],
  "relationship": {
    "equityPercentage": 35.4,
    "position": "primary",
    "title": "abc123"
  }
}

Errors

Error	Description
Idempotency key missing	Idempotency key must be supplied
Bad Request	One or more validation errors occurred
KYC check failed	KYC check failed
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Not acceptable	Requested representation not supported
Idempotency key in use	Idempotency key in use
Api error	Unable to process your request.

Persons

Individuals who own or are part of a business

Retrieve person

GET /persons/{personId}

Retrieve a specific person.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested person.

Response body

Request

curl --request get \
	--url https://api.payroc.com/v1/persons/89

Response

application/json

{
  "personId": 1543,
  "firstName": "David",
  "lastName": "Simpson",
  "dateOfBirth": "1964-03-22T00:00:00.000Z",
  "address": {
    "address1": "1 Example Ave.",
    "city": "Example city",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "identifiers": [
    {
      "type": "nationalId",
      "value": "987-65-4320"
    }
  ],
  "contactMethods": [
    {
      "type": "email",
      "value": "[email protected]"
    },
    {
      "type": "phone",
      "value": "123 456 7890"
    },
    {
      "type": "mobile",
      "value": "098 765 4321"
    }
  ],
  "relationship": {
    "equityPercentage": 35.4,
    "position": "primary",
    "title": "string",
    "isControllingPerson": true
  }
}

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

Update person

PUT /persons/{personId}

Update a specific person.

Path parameters

Body parameters

Response Schema

Status Code 204

Successful request. We updated the person.

Request

curl --request put \
	--url https://api.payroc.com/v1/persons/89 \
	--header 'Content-Type: application/json' \
	--data '{"firstName":"David","lastName":"Simpson","dateOfBirth":"1964-03-22T00:00:00.000Z","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"987-65-4320"}],"contactMethods":[{"type":"phone","value":"617 715 1234"},{"type":"mobile","value":"856 457 8745"},{"type":"email","value":"[email protected]"}],"relationship":{"equityPercentage":35.4,"position":"primary","title":"abc123"}}'

Errors

Error	Description
Bad Request	One or more validation errors occurred
KYC check failed	KYC check failed
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Not acceptable	Requested representation not supported
Api error	Unable to process your request.

Delete person

DELETE /persons/{personId}

Delete a person.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the person.

Request

curl --request delete \
	--url https://api.payroc.com/v1/persons/89

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

Pricing intents

Create and manage pricing intents

List pricing intents

GET /pricing-intents

Retrieve a list of pricing intents.

Query parameters

Response Schema

Status Code 200

Successful response. Returns a list of pricing intents.

Response body

Request

curl --request get \
	--url https://api.payroc.com/v1/pricing-intents

Response

application/json

{
  "limit": 1,
  "count": 1,
  "hasMore": true,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/pricing-intents?before=5&limit=1"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/pricing-intents?after=5&limit=1"
    }
  ],
  "data": [
    {
      "id": 5,
      "createdDate": "2020-09-22T09:00:00.000Z",
      "lastUpdatedDate": "2020-09-22T09:00:00.000Z",
      "status": "active",
      "key": "string",
      "metadata": {
        "internalReference": "2345"
      },
      "country": "US",
      "base": {
        "addressVerification": 5,
        "annualFee": {
          "billInMonth": "december",
          "amount": 100
        },
        "regulatoryAssistanceProgram": 15,
        "pciNonCompliance": 1999,
        "payrocAdvantage": 10,
        "portalAccess": 10,
        "platinumSecurity": {
          "billingFrequency": "monthly",
          "amount": 100
        },
        "maintenance": 500,
        "minimum": 100,
        "voiceAuthorization": 95,
        "chargeback": 2500,
        "retrieval": 1500
      },
      "processor": {
        "card": {
          "planType": "interchangePlus",
          "fees": {
            "mastercard": {
              "volume": 1.25,
              "transaction": 5
            },
            "visa": {
              "volume": 3.99,
              "transaction": 15
            },
            "discover": {
              "volume": 1.25,
              "transaction": 4
            },
            "amex": {
              "volume": 1.25,
              "transaction": 10
            }
          }
        }
      },
      "gateway": {
        "attributes": {
          "gatewayName": "worldnet"
        },
        "fees": {
          "monthly": "1000,",
          "setup": "25000,",
          "perTransaction": 0,
          "vaultMonthly": "0,",
          "vaultPerTransaction": 0
        }
      }
    }
  ]
}

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Api error	Unable to process your request.

Create pricing intent

POST /pricing-intents

Create a new pricing intent.

Header parameters

Body parameters

Response Schema

Status Code 201

Successful response. We created the pricing intent and it is waiting for approval.

Response headers

Response body

Request

curl --request post \
	--url https://api.payroc.com/v1/pricing-intents \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: abc123' \
	--data '{"key":"abc123","metadata":{"internalReference":"2345"},"country":"US","base":{"addressVerification":5,"annualFee":{"billInMonth":"december","amount":100},"regulatoryAssistanceProgram":15,"pciNonCompliance":1999,"payrocAdvantage":10,"portalAccess":10,"platinumSecurity":{"billingFrequency":"monthly","amount":100},"maintenance":500,"minimum":100,"voiceAuthorization":95,"chargeback":2500,"retrieval":1500},"processor":{"card":{"planType":"interchangePlus","fees":{"mastercard":{"volume":1.25,"transaction":0},"visa":{"volume":1.25,"transaction":0},"discover":{"volume":1.25,"transaction":0},"amex":{"volume":1.25,"transaction":0}}}},"gateway":{"attributes":{"gatewayName":"worldnet"},"fees":{"monthly":0,"setup":0,"perTransaction":0,"vaultMonthly":0,"vaultPerTransaction":0}}}'

Response

application/json

{
  "id": 5,
  "createdDate": "2020-09-22T09:00:00.000Z",
  "lastUpdatedDate": "2020-09-22T09:00:00.000Z",
  "status": "active",
  "key": "myInterchangePlus",
  "metadata": {
    "internalReference": "2345"
  },
  "country": "US",
  "base": {
    "addressVerification": 5,
    "annualFee": {
      "billInMonth": "december",
      "amount": 100
    },
    "regulatoryAssistanceProgram": 15,
    "pciNonCompliance": 1999,
    "payrocAdvantage": 10,
    "portalAccess": 10,
    "platinumSecurity": {
      "billingFrequency": "monthly",
      "amount": 100
    },
    "maintenance": 500,
    "minimum": 100,
    "voiceAuthorization": 95,
    "chargeback": 2500,
    "retrieval": 1500
  },
  "processor": {
    "card": {
      "planType": "interchangePlus",
      "fees": {
        "mastercard": {
          "volume": 1.25,
          "transaction": 5
        },
        "visa": {
          "volume": 3.99,
          "transaction": 15
        },
        "discover": {
          "volume": 1.25,
          "transaction": 4
        },
        "amex": {
          "volume": 1.25,
          "transaction": 10
        }
      }
    }
  },
  "gateway": {
    "attributes": {
      "gatewayName": "worldnet"
    },
    "fees": {
      "monthly": "1000,",
      "setup": "25000,",
      "perTransaction": 0,
      "vaultMonthly": "0,",
      "vaultPerTransaction": 0
    }
  }
}

Errors

Error	Description
Bad Request	One or more validation errors occurred
Idempotency key missing	Idempotency key must be supplied
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not acceptable	Requested representation not supported
Idempotency key in use	Idempotency key in use
Api error	Unable to process your request.

Retrieve pricing intent

GET /pricing-intents/{pricingIntentId}

Retrieve a specific pricing intent.

Path parameters

Response Schema

Status Code 200

Successful response. Returns the requested pricing intent.

Response body

Request

curl --request get \
	--url https://api.payroc.com/v1/pricing-intents/abc123

Response

application/json

{
  "id": 5,
  "createdDate": "2020-09-22T09:00:00.000Z",
  "lastUpdatedDate": "2020-09-22T09:00:00.000Z",
  "status": "active",
  "key": "myInterchangePlus",
  "metadata": {
    "internalReference": "2345"
  },
  "country": "US",
  "base": {
    "addressVerification": 5,
    "annualFee": {
      "billInMonth": "december",
      "amount": 100
    },
    "regulatoryAssistanceProgram": 15,
    "pciNonCompliance": 1999,
    "payrocAdvantage": 10,
    "portalAccess": 10,
    "platinumSecurity": {
      "billingFrequency": "monthly",
      "amount": 100
    },
    "maintenance": 500,
    "minimum": 100,
    "voiceAuthorization": 95,
    "chargeback": 2500,
    "retrieval": 1500
  },
  "processor": {
    "card": {
      "planType": "interchangePlus",
      "fees": {
        "mastercard": {
          "volume": 1.25,
          "transaction": 5
        },
        "visa": {
          "volume": 3.99,
          "transaction": 15
        },
        "discover": {
          "volume": 1.25,
          "transaction": 4
        },
        "amex": {
          "volume": 1.25,
          "transaction": 10
        }
      }
    }
  },
  "gateway": {
    "attributes": {
      "gatewayName": "worldnet"
    },
    "fees": {
      "monthly": "1000,",
      "setup": "25000,",
      "perTransaction": 0,
      "vaultMonthly": "0,",
      "vaultPerTransaction": 0
    }
  }
}

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Api error	Unable to process your request.

Update pricing intent

PUT /pricing-intents/{pricingIntentId}

Update a pricing intent.

Path parameters

Body parameters

Response Schema

Status Code 204

Resource successfully updated

Request

curl --request put \
	--url https://api.payroc.com/v1/pricing-intents/abc123 \
	--header 'Content-Type: application/json' \
	--data '{"key":"abc123","metadata":{"internalReference":"2345"},"country":"US","base":{"addressVerification":5,"annualFee":{"billInMonth":"december","amount":100},"regulatoryAssistanceProgram":15,"pciNonCompliance":1999,"payrocAdvantage":10,"portalAccess":10,"platinumSecurity":{"billingFrequency":"monthly","amount":100},"maintenance":500,"minimum":100,"voiceAuthorization":95,"chargeback":2500,"retrieval":1500},"processor":{"card":{"planType":"interchangePlus","fees":{"mastercard":{"volume":1.25,"transaction":0},"visa":{"volume":1.25,"transaction":0},"discover":{"volume":1.25,"transaction":0},"amex":{"volume":1.25,"transaction":0}}}},"gateway":{"attributes":{"gatewayName":"worldnet"},"fees":{"monthly":0,"setup":0,"perTransaction":0,"vaultMonthly":0,"vaultPerTransaction":0}}}'

Errors

Error	Description
Bad Request	One or more validation errors occurred
Not Authorized	Your identity could not be verified
Forbidden	You do not have the required permission
Not found	Resource could not be found
Not acceptable	Requested representation not supported
Api error	Unable to process your request.

Partially update pricing intent

PATCH /pricing-intents/{pricingIntentId}

Partially update an existing pricing intent.

Path parameters

Header parameters

Body parameters

array of objects

Response Schema

Status Code 200

Successful request. We have updated the pricing intent.

Response body

Request

curl --request patch \
	--url https://api.payroc.com/v1/pricing-intents/abc123 \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: abc123' \
	--data '[{"op":"add","path":"/a/b/c","value":["foo","bar"]},{"op":"remove","path":"/a/b/c"},{"op":"replace","path":"/a/b/c","value":42},{"op":"move","from":"/a/b/c","path":"/a/b/d"},{"op":"copy","from":"/a/b/d","path":"/a/b/e"},{"op":"test","path":"/a/b/c","value":"foo"}]'

Response

application/json

{
  "id": 5,
  "createdDate": "2020-09-22T09:00:00.000Z",
  "lastUpdatedDate": "2020-09-22T09:00:00.000Z",
  "status": "active",
  "key": "myInterchangePlus",
  "metadata": {
    "internalReference": "2345"
  },
  "country": "US",
  "base": {
    "addressVerification": 5,
    "annualFee": {
      "billInMonth": "december",
      "amount": 100
    },
    "regulatoryAssistanceProgram": 15,
    "pciNonCompliance": 1999,
    "payrocAdvantage": 10,
    "portalAccess": 10,
    "platinumSecurity": {
      "billingFrequency": "monthly",
      "amount": 100
    },
    "maintenance": 500,
    "minimum": 100,
    "voiceAuthorization": 95,
    "chargeback": 2500,
    "retrieval": 1500
  },
  "processor": {
    "card": {
      "planType": "interchangePlus",
      "fees": {
        "mastercard": {
          "volume": 1.25,
          "transaction": 5
        },
        "visa": {
          "volume": 3.99,
          "transaction": 15
        },
        "discover": {
          "volume": 1.25,
          "transaction":

Resources

Query parameters

Response Schema

Status Code 200

Response body

Errors

Path parameters

Response Schema

Status Code 200

Response body

Errors

Path parameters

Body parameters

Response Schema

Status Code 204

Errors

Path parameters

Response Schema

Status Code 204

Errors

Query parameters

Response Schema

Status Code 200

Response body

Errors

Query parameters

Response Schema

Status Code 200

Response body

Errors

Header parameters

Body parameters

Response Schema

Status Code 201

Response headers

Response body

Errors

Query parameters

Response Schema

Status Code 200

Response body

Errors

Path parameters

Response Schema

Status Code 200

Response body

Errors

Path parameters

Body parameters

Response Schema

Status Code 204

Errors

Path parameters

Response Schema

Status Code 204

Errors

Header parameters

Body parameters

Response Schema

Status Code 201

Response headers

Response body

Errors

Query parameters

Response Schema

Status Code 200

Response body

Errors

Path parameters

Response Schema

Status Code 200

Response body

Errors

Path parameters

Body parameters

Response Schema

Status Code 204

Errors

Path parameters

Response Schema