API CALL SYNTAX

URL

Structure: https://{subdomain}.{domain}.{tld}/{endpoint}
subdomain, domain, and tld will vary per partition. For Payrix Pro:
- subdomain is api for production and test-api for sandbox
- domain is payrix
- tld is com
Endpoints are always plural (entities, not entity)
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 url
Each 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 returned
- If there are multiple possible child resources, use the plural (e.g. merchants?expand[members][]) and a nested array of objects will be returned
- If 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 header
Searches will compare the value of the key in the resource to the key and value of the search and return results based on the operator
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 considered 0 and everything else is greater than 0
- 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 values
  - Follows equals search rules
  - values 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-append or[] 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:

JS

{
  "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 newest value of the key first
- asc will return the oldest value of the key 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 header
Totals 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 considered 0
- 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 considered 0
- 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 considered 0