Payrix Pro API Syntax and Structure

The following content outlines the framework for building an API request. This includes specifying servers, providing values for placeholders, and understanding the overall structure for effective communication with the Payrix Pro API.

Payrix Pro Sandbox Server

CODE

https://test-api.payrix.com/

Payrix Pro Production Server

CODE

https://api.payrix.com/

To simplify, all following references to the base URL will use {server} as a placeholder variable for Payrix Pro Sandbox or Production server subdomains.

HTTP Methods

Available Methods	Description
`GET`	Retrieve resources for an endpoint all at once or by ID.
`PUT`	Update resources for an endpoint all at once or by ID.
`POST`	Add a new resource to an endpoint.
`DELETE`	Delete a specific resource from an endpoint.

Headers

Required Headers	Required Value(s)
`Accept`	`application/json, application/xml`
`Content-Type`	`application/json`

Authentication

Required Headers	Required Value	Description
`APIKEY`	`{yourAPIKey}`	This can be found on the Portal Settings page.
`login`	`{yourLoginID}`	User your login ID that begins with `t1_log_`.

Endpoints

All Payrix Pro server endpoints follow directly after the base URL and all endpoint titles are always pluralized (merchants, entities, etc.).

CODE

https://{server}.payrix.com/{endpoint}

Example: https://test-api.payrix.com/entities

You can view all available endpoints on the Payrix Pro platform server by visiting our API Documentation Portal.

Resource IDs

You can add /{id} after an endpoint, replacing the placeholder with that unique resource ID, to specify a certain resource when making the API request.

CODE

https://{server}.payrix.com/{endpoint}/{id}

Example: https://test-api.payrix.com/entities/p1_ent_12a3bcd45e67f89gh012345

Most API endpoint resources on the server will generate or be assigned a specific identifier (ID) after being created.

API Endpoint Request Example

In the below example, we’re retrieving information for the specific entity who’s ID we’ve provided:

Server URL & Required Headers

CODE

GET https://api-test.payrix.com/entities/p1_ent_12a3bcd45e67f89gh012345
Accept: application/json
Content-Type: application/json
APIKEY: 1a2b3c4d5e6f7g8h9i
login: t1_log_12a3bcd45e67f89gh0123450

API Query Structure

After structuring your base URL and endpoint, optionally adding a resource ID, you can also add further queries to the request.

Basic Single Query Structure

CODE

https://{server}.payrix.com/{endpoint}?{query_string}

Example: https://test-api.payrix.com/entities?status=active

Multi-Query Structure

CODE

https://{server}.payrix.com/{endpoint}?{query_string1}&{query_string2}

Example: https://test-api.payrix.com/entities?inactive=0&frozen=0

Query	Description	Examples
`{operator}`	Represents the operation or calculation to be performed.	`sum`, `count`, `min`, & `max`
`{key}`	Represents the attribute or field where the operation will be performed.	`amount`, `created` & `status`
`{value}`	Represents the specific value used in the operation or search. This could be IDs, statuses, dates, numbers, strings, or other specific data.	`2024-01-05`, `t1_mer_123...`, & `Approved`.
`{resource}`	Represents the name of the related server resource you want to expand or include, corresponding to a field, endpoint, or entity.	`merchants`, `txns` (transactions) & `members`.

Resource Nesting

Parent Resource

Represents the main or higher-level resource.
Typically contains information or parameters that reference other related resources.
When expanding a parent resource, you must specify the field where the related resource is referenced.

Child Resource

Represents the related resource that is connected to the parent resource.
Typically contains information related to the parent resource.
When expanding a child resource, you must use the name of the resource itself.

Example: An org (Parent Resource) is made up of members (Child Resource).

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:

CODE

https://{server}.payrix.com/{endpoint}?expand[{resource}][]

Example: https://test-api.payrix.com/entities?expand[merchant][]

When expanding a resource, you must specify the object field name of parent resources.
If there are no child resources, nothing will be expanded.
You can further expand an already-expanded resource

Page (Paginate)

You can navigate multiple pages using pagination.

By default, the API returns the first 30 records queried (page). To find more records, you will have to query additional pages:

CODE

https://{server}.payrix.com/{endpoint}?page[number]={#}&page[limit]={#}

Example: https://test-api.payrix.com/entities?page[number]=2&page[limit]=50

Valid Operators

Description

Notes

number

The number for the page of records returned.

limit

The maximum number of records returned per page

Maximum is 100.

You can add pagination to expanded child resources by specifying the resource path.

Search

You can compare key values against pre-defined criteria to return resources based on the operator.

CODE

https://{server}.payrix.com/{endpoint}?search={key}[{operator}]={value}

Example: https://test-api.payrix.com/entities?search=created[greater]=2022-01-01

Valid Operators	Query Structure	Description	Notes
`equals`	`{key}[equals]={value}`	Checks for truthy matches	`null`, `0`, and an empty string are considered equal matches
`exact`	`{key}[exact]={value}`	Checks for exact matches	`null`, `0`, and an empty string are not considered exact matches
`greater`	`{key}[greater]={value}`	Checks for IDs, dates, numbers, and number strings that are greater than the value.	`null`and`0` are considered `0` and everything else is greater than `0`
`less`	`{key}[less]={value}`	Checks for IDs, dates, numbers, and number strings that are less than the value.	`null`, `0`, and `”0”` are considered `0` and everything else is less than `0`.
`in`	`{key}[in]={value},{value}`	Checks for truthy matches for multiple values.	Follows `equals` search rules `value`s should be separated by commas without any spaced (when searching multiple values)
`like`	`{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)
`notlike`	`{key}[notlike]={value}%25x`	Checks for partial string matches	Follows `equals` search rules but strings are not case sensitive Use html url encoding to encode wildcard (`%25` -> `%`) `{key}[notlike]=%25value%25` will translate into SQL `{key} NOT LIKE "{decoded_value}"`
`diff`	`{key}[diff]={value}`	Checks for different matches.	`{key}[diff]=null` will translate into SQL `{key} NOT NULL` `{key}[diff]=value` will translate into SQL `{key} != "value"`
`notin`	`{key}[notin]={value},{value}`	Checks for negative matches of multiple values.	Follows `diff` search rules `values` should be separated by commas without any spaced (when searching multiple values)

You can filter the results of the request by adding a Search header and setting the value to the search
The default search query returns all searches using an and logic. Use or as an operator to perform an or logic search.
To search through child or parent resources, add them to the resource name path.

Advanced Search

You can perform a more advanced search using additional query conditions within outer containers[], as shown below:

CODE

https://{server}.payrix.com/{endpoint}?search=or[0][and][0][A][equals]=1&or[0]and[1][B][equals]=2

Example: https://test-api.payrix.com/entities?search=[0][and][0][A][equals]=1&or[0]and[1][B][equals]=2

Click here for a JSON representation of the Advanced Search Array URL.

JS

{
  "or": [
    {
      "and": {
        "A": {
          "equals": 1
        },
        "B": {
          "equals": 2
        },
        "C": {
          "equals": 3
        }
      }
    },
    {
      "and": {
        "D": {
          "equals": 4
        },
        "E": {
          "equals": 5
        }
      }
    }
  ]
}

Sort

You can sort returned resource records by newest (descending) or oldest (ascending) order, with descending being the default.

CODE

https://{server}.payrix.com/{endpoint}?{key}[sort]={operator}

Example: https://test-api.payrix.com/entities?created[sort]=desc

Valid Operators	Description
`desc`	Return the newest value of the `key` first.
`asc`	Returns the oldest value of the `key` first.

You can further modify the sorted response by adding search to the sort request to the value of the search header.

Totals

You can return totals of the API call by adding a Totals header

Totals will include the totals for the request and not just what is returned on the page

CODE

https://{server}.payrix.com/{endpoint}?totals={operator}[]={key}

Example: https://test-api.payrix.com/entities?totals=sum[]=amount

Valid Operators	Description	Note
`sum`	Returns the sum of the values of the `key`.	Can only be run on IDs, dates, numbers, and number strings `null` is considered `0`
`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`
`nodata`	Flag transaction to skip the model items retrieval data	Use it along with other totals operators when only the totals operation result is required. Skips the SQL query that retrieves

Totals will be returned under response.details.totals.{operator}.{key}