API CALL SYNTAX
URL
Structure:
https://{subdomain}.{domain}.{tld}/{endpoint}
subdomain
,domain
, andtld
will vary per partition. For Payrix Pro:subdomain
isapi
for production andtest-api
for sandboxdomain
ispayrix
tld
iscom
Endpoints are always plural (
entities
, notentity
)To send a call to a specific ID, append
/{id}
to the url
Query String
Structure:
{url}?{query string}
To add an additional query string, append
&{query string}
to the urlEach query sting type has its own syntax below
Expand
By default, when a resource points to another resource, the id of the parent resource will be included in the child resource. To return the full object you can use expand.
You can also use expand to return resources that point to the resource being queried
Structure:
expand[{resource}][]
When expanding a parent resource, always set
resource
to the name of the field where the resource is referenced (e.g.entries?expand[onentity][]
)When expanding a child resource, use the name of the resource
If there is only one possible child resource, use singular (e.g
entities?expand[merchant][]
) and a nested object will be returnedIf there are multiple possible child resources, use the plural (e.g.
merchants?expand[members][]
) and a nested array of objects will be returnedIf there are no actual child resources, nothing will be expanded in the response
Expanded resources themselves can be expanded
If the expanded resource is an object, follow the standard expansion rules and add the resource name path (e.g.
entities?expand[merchant][members][]
)If the expanded resource is an array, you will have to add a set of empty brackets before continuing down the resource name path (e.g.
entities?expand[orgEntities][][org][login][]
)
Page
By default, the API returns the first 30 records queried (page). To find more records, you will have to query additional pages
When using scripts to go through multiple pages, ID-based pagination should be used
Structure:
page[{key}]={value}
Valid keys are
limit
will be the max records returned per page (maximum is 100)number
will be the page of records returned
You can add pagination to expanded child resource arrays by adding the resource name path (e.g.
merchants?expand[txns][]&page[txns][limit]=100
)
Search
You can filter the results of the request by adding a Search header and setting the value to the search
Structure:
Search: {search}
To add an additional search, append
&{search}
to the value of the search headerSearches will compare the value of the key in the resource to the
key
andvalue
of the search and return results based on theoperator
Valid operators are
equals
Structure:
{key}[equals]={value}
Checks for truthy matches
null
,0
, and an empty string are considered equal matches
exact
Structure:
{key}[exact]={value}
Checks for exact matches
null
,0
, and an empty string are not considered exact matches
greater
Structure:
{key}[greater]={value}
Checks for IDs, dates, numbers, and number strings that are greater than
value
null
,0
, and”0”
are considered0
and everything else is greater than0
less
Structure:
{key}[less]={value}
Checks for IDs, dates, numbers, and number strings that are less than
value
in
Structure:
{key}[in]={value},{value}
Checks for truthy matches for multiple
value
sFollows
equals
search rulesvalue
s should be separated by commas without any spaced (when searching multiple values)
like
Structure:
{key}[like]={value}%25
Checks for partial string matches
Follows
equals
search rules but strings are not case sensitive%25
should be used as the wild card (when searching substrings)
By default, the query will return resources that match all the searches (
and
), to return results that match any of the searches (or
), pre-appendor[]
to the search (e.g.or[][created][greater]=2019-01-01&or[][created][less]=2018-01-01
)To search through child or parent resources, add to the resource name path (e.g.
merchant[status][equals]=2&merchant[members][ssn][greater]=0
)
Advanced Search Syntax
API search queries are expressed as arrays in URL query format. In our API and
statements and or
statements are always evaluated based on the outer containers for inner conditions. In order to accomplish a query with a predicate such as (A=1 and B=2 and C=3) or (D=4 and E=5)
set an outer container of or
and then have inner conditions for each. Here is how you would construct the example above as an API search query:
search: or[0][and][0][A][equals]=1&or[0][and][1][B][equals]=2&or[0][and][2][C][equals]=3&or[1][and][0][D][equals]=4&or[1][and][1][E][equals]=5
Here is a JSON representation of the search query array for reference:
{
"or": [
{
"and": {
"A": {
"equals": 1
},
"B": {
"equals": 2
},
"C": {
"equals": 3
}
}
},
{
"and": {
"D": {
"equals": 4
},
"E": {
"equals": 5
}
}
}
]
}
Sort
By default, we return the resources with the newest id
first. You can modify the sorting by adding search to the sort request to the value of the search header
Structure:
{key}[sort]={direction}
Sort follows the same rules as all other search operators for child or parent resources
Valid directions are
desc
will return the newestvalue
of thekey
firstasc
will return the oldestvalue
of thekey
first
Totals
You can return totals of the API call by adding a Totals header
Structure:
Totals: {operator}[]={key}
To add an additional search, append
&{operator}[]={key}
to the value of the totals headerTotals will be returned in
response.details.totals.{operator}.{key}
Totals will include the totals for the request and not just what is returned on the page
Valid operators are
sum
Returns the sum of the values of the
key
Can only be run on IDs, dates, numbers, and number strings
count
Returns the count of the non zero values of the
key
null
is considered0
min
Returns the minimum value of the values of the
key
Can only be run on IDs, dates, numbers, and number strings
null
is not considered0
max
Returns the maximum value of the values of the
key
Can only be run on IDs, dates, numbers, and number strings
null
is not considered0