Resources

Funding accounts

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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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

ErrorDescription
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":