Payrix API Syntax & 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 API.

Payrix Sandbox Server

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

Payrix Production Server

https://api.payrix.com/

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

Note: The base URL’s subdomain (api), primary domain (payrix), and top level domain (.com) will change from Facilitator to Facilitator.

HTTP Methods

Headers

Authentication

Endpoints

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

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

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

You can view all available endpoints on the Payrix 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.

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:

GET https://api-test.payrix.com/entities/p1_ent_12a3bcd45e67f89gh012345
Accept: application/json
Content-Type: application/json
Authorization: 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

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

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

Multi-Query Structure

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

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

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:

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:

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

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

• 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.

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

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

• 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:

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

{
  "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.

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

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

• 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

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

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

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