Payroc Web API (1)

Download OpenAPI specification:Download

Overview

Payroc's APIs are RESTful integration points for our partners to submit new merchant applications and query settlement data for existing merchants.

Authentication

Partners will be provided credentials which can be used to request a set of tokens from the /auth endpoint. The response will contain two different tokens, an access token and a refresh token. The tokens are JWTs. More information about JWTs can be found at jwt.io.

The tokens are encoded with an expiration timestamp when issued - access tokens expire two hours after being issued while refresh tokens expire twenty-four hours after being issued. The access token can be used to make requests to the Boarding API or Settlement API endpoints. The refresh token can only be used to request a new access token via the /access-token endpoint.

Error Codes

The Payroc RESTful APIs use HTTP-based and use conventional HTTP status codes. Successful requests will return a 2XX status code while failed requests will return a 4XX or 5XX status code. Most handled error responses will be in the following format:

{
    "responseStatus": {
        "errorCode": "string",
        "message": "string",
        "errors": [
            {
                "errorCode": "string",
                "fieldName": "string",
                "message": "string",
                "meta": {
                    "PropertyName": "string"
                }
            }
        ]
    }
}

Generally 4XX status codes indicate an issue with the request and can be retried once corrected. While 5XX status codes indicate an issue on the server that needs to be resolved before the request can be processed successfully. Below are some of the possible errors and their meaning:

HTTP Status Code Error Code Message Meaning
401 Unauthorized Invalid UserName or Password The user does not exist or the password provided is incorrect.
401 TokenException Token has expired Either the access token being used to request a resource has expired or the refresh token being used to request a new access token has expired.
401 AuthenticationException This account has been locked The username and password provided are correct but the account has been locked either manually or due to too many incorrect login attempts.
403 UnauthorizedAccessException Could not execute service 'Authenticate', The following restrictions were not met: '\n -[Secure, HttpPost, HttpOptions, OneWay, Soap11, Soap12, Xml, Jsv, ProtoBuf, Csv, Html, Wire, MsgPack, FormatOther, AnyEndpoint] Authentication was attempted using incorrect parameters, an incorrect protocol (wrong HTTP verb) or an insecure connection
403 UnauthorizedAccessException Please authenticate using bearer token or with flag 'UseTokenCookie' set to true. Basic Authentication was used to attempt access to a resource requiring token based authentication
403 UnauthorizedAccessException Attempted to perform an unauthorized operation. The user does not have permission to use the feature or resource being accessed.
429 429 Too many boarding request The merchant boarding end point is throttled.
400 NotEmpty 'XXX' should not be empty. The specified field is missing from the request body.
400 NotNull 'XXX' must not be empty. The specified field is missing from the request body.
400 Predicate Invalid State in XXX Address The two letter state abbreviation provided is not a valid US state.
400 Predicate Invalid Zip in XXX Address The zip code provided did not pass validation.
400 Email 'Email' is not a valid email address. The email address provided did not pass validation.
400 Predicate Ownership must total to less than or equal to 100% The sum of the individual ownership percentages provided for each owner exceeded 100%
400 Predicate No more than one primary contact may be specified. More than one of the owners was marked as the primary owner. Only one primary contact can be specified.
400 Length XXX must be less than Y characters The specified field (XXX) is longer than the allowed length (Y)
400 Predicate Invalid Phone number The phone number provided did not pass validation.
400 Predicate Invalid SSN The SSN provided did not pass validation (expected 9 numeric characters)
400 GreaterThanOrEqual 'XXX' must be greater than or equal to 'Y'. The specified field (XXX) must be greater than or equal to the specified value (Y)
400 DuplicateMerchantLocationException Duplicate Request - Merchant at specified locations already exists. (Production only) The merchant location specified already exists in the IPS system.
400 Predicate Invalid Account Number The bank account number provided did not pass validation.
400 Predicate Invalid Routing Number The bank routing number provided did not pass validation.
400 Predicate Merchant ID not found The MID provided was not found
400 Predicate Ibx Merchant not found The MID provided was either not found or is not an IBX merchant
400 Predicate Credential type must be 'API' or 'Merchant' The gateway credential type provided was not valid.
400 FailedTinCheckException Federal Tax ID failed TIN Check. Value checked: XXX Merchants must have a valid TIN in order to board. The provided Federal Tax ID failed validation.
400 IllegalRequestParameterException EnableGatewayEmails flag is not allowed unless gateway boarding is handled by IPS. The request being sent contains a non-null value in EnableGatewayEmails but this feature is not enabled for your account.
400 InvalidLocationException XXX address is an invalid location. Value checked: XXX. A more detailed reason maybe provided here. The request being sent contains an address that does not meet the specified requirements. An example would be trying to specify a PO Box as the DBA address.

Rate limit

Due to the complexity involved in boarding merchants, we enforce a maximum rate of 1 boarding request every 5 seconds. Currently there are no rate limits on the other endpoints.

Authentication

An access token is required to access resources on the server. Either your API credentials or a valid refresh token can be used to create an access token. To create your initial access token and refresh token - use the /auth endpoint. To retrieve a new access token using a valid refresh token - use the /access-token endpoint.

Create Access Token

Credentials can be transmitted in the request body or using a basic authentication header.

Using the request body:

POST https://api.integritypays.com/v1/auth HTTP/1.1
cache-control: no-cache
Accept: application/json
accept-encoding: gzip, deflate
content-length: 45
Connection: keep-alive

{
    "username":"myUserName",
    "password":"password"
}

Using the basic authentication header:

POST https://api.integritypays.com/v1/auth HTTP/1.1
cache-control: no-cache
Accept: application/json
Authorization: Basic bHd5bGllOnBhc3N3b3Jk
accept-encoding: gzip, deflate
content-length: 0
Connection: keep-alive

The access token can be found in the bearerToken property of the response object.

Example response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Vary: Accept
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Authorization,Content-Type
Content-Length: 902

{
    "userId":"2",
    "sessionId":"DPaIIIUrPjUeW8aAU4yu",
    "userName":"myUserName",
    "displayName":"myDisplayName",
    "bearerToken":"<JWT>",
    "refreshToken":"<JWT>",
    "responseStatus":{}
}

Optionally, the access token can also be returned and used as a browser cookie by enabling the useTokenCookie flag in the auth request. The cookie is referenced by ‘ss-tok’ key and is marked secure and HttpOnly. This enables the application to use the browser cookie to authenticate with the server. Token based authentication is required for all endpoints except the authentication endpoints.

Authorizations:
header Parameters
Accept
required
string
Value: "application/json"

Accept Header

Request Body schema: application/json
provider
string
state
string
oauth_token
string
oauth_verifier
string
userName
string
password
string
rememberMe
boolean
continue
string
nonce
string
uri
string
response
string
qop
string
nc
string
cnonce
string
useTokenCookie
boolean
accessToken
string
accessTokenSecret
string
meta
object (Dictionary<String,String>)

Dictionary<String,String>

Responses

200

Success

post /auth
https://api.integritypays.com/v1/auth

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "provider": "string",
  • "state": "string",
  • "oauth_token": "string",
  • "oauth_verifier": "string",
  • "userName": "string",
  • "password": "string",
  • "rememberMe": true,
  • "continue": "string",
  • "nonce": "string",
  • "uri": "string",
  • "response": "string",
  • "qop": "string",
  • "nc": "string",
  • "cnonce": "string",
  • "useTokenCookie": true,
  • "accessToken": "string",
  • "accessTokenSecret": "string",
  • "meta":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "userId": "string",
  • "sessionId": "string",
  • "userName": "string",
  • "displayName": "string",
  • "referrerUrl": "string",
  • "bearerToken": "string",
  • "refreshToken": "string",
  • "responseStatus":
    {
    },
  • "meta":
    {
    }
}

Refresh Access Token

A valid refresh token can be used to retrieve a new access token.

Using the request body:

POST  https://api.integritypays.com/v1/access-token HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache

{
  "refreshToken":"<JWT>"
}

The access token can be found in the accessToken property of the response object.

Example response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Vary: Accept
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Authorization,Content-Type
Content-Length: 631

{
    "accessToken": "<JWT>"
}
header Parameters
Accept
required
string
Value: "application/json"

Accept Header

Request Body schema: application/json
refreshToken
string

Responses

200

Success

post /access-token
https://api.integritypays.com/v1/access-token

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "accessToken": "string",
  • "responseStatus":
    {
    }
}

Boarding

Submit Merchant Application

Use this endpoint to board new merchants. A Merchant ID (i.e. MID) will be assigned upon successful boarding. A valid bearer token must be provided to access this endpoint.

Authorizations:
header Parameters
Accept
required
string
Value: "application/json"

Accept Header

Request Body schema: application/json
bankAccount
object (BankAccount)

BankAccount

dbaAddress
required
object (Address)

Address

doingBusinessAs
required
string
enableGatewayEmails
boolean
fedTaxId
required
string
legalBusinessAddress
required
object (Address)

Address

legalBusinessName
required
string
ownerContacts
required
Array of objects (Contact)

Responses

200

Success

post /boarding
https://api.integritypays.com/v1/boarding

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "bankAccount":
    {
    },
  • "dbaAddress":
    {
    },
  • "doingBusinessAs": "string",
  • "enableGatewayEmails": true,
  • "fedTaxId": "string",
  • "legalBusinessAddress":
    {
    },
  • "legalBusinessName": "string",
  • "ownerContacts":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "links":
    [
    ],
  • "applicationUrl": "string",
  • "gatewayUsers":
    [
    ],
  • "merchant":
    {
    },
  • "responseStatus":
    {
    },
  • "terminalConfig":
    {
    }
}

Get Merchant Application Status

Use this endpoint to check the status of a boarded merchants. The MID is required. A valid bearer token must be provided to access this endpoint.

Authorizations:
path Parameters
MID
required
string
header Parameters
Accept
required
string
Value: "application/json"

Accept Header

Responses

200

Success

get /boarding/{MID}/status
https://api.integritypays.com/v1/boarding/{MID}/status

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "links":
    [
    ],
  • "applicationStatus": "string",
  • "applicationUrl": "string",
  • "processingDetails":
    [
    ],
  • "processingStatus": "string",
  • "responseStatus":
    {
    },
  • "settlementDetails":
    [
    ],
  • "settlementStatus": "string"
}

Settlement

Get Settlement Report

Use this endpoint to get settlement batch data by date range

Authorizations:
path Parameters
MID
required
string
query Parameters
StartDate
required
string <date-time>
EndDate
required
string <date-time>
header Parameters
Accept
required
string
Value: "application/json"

Accept Header

Responses

200

Success

get /settlement/{MID}
https://api.integritypays.com/v1/settlement/{MID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "batches":
    [
    ],
  • "chargebacksReceived":
    [
    ],
  • "dbaName": "string",
  • "mid": "string"
}

Get Batch Details

Use this endpoint to get settlement report data by batch id

Authorizations:
path Parameters
MID
required
string
BatchId
required
integer <int32>
header Parameters
Accept
required
string
Value: "application/json"

Accept Header

Responses

200

Success

get /settlement/{MID}/batch/{BatchId}
https://api.integritypays.com/v1/settlement/{MID}/batch/{BatchId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "batchDetails":
    [
    ],
  • "chargebackDetails":
    [
    ]
}