Working with API's

This section details the general principles and common operations when interacting with the PCE API.

CRUD

Our API supports standard operations for creating, updating, and retrieving entities:

Create Resource: Use HTTP POST. A successful creation returns 201 Created with the resourceurl in the url header (e.g., url: /v1/{entity}/{id}).
Update Resource: Use HTTP POST. A successful update returns 204 No Content
- Include only the fields you wish to change.
- To delete a non-mandatory field, pass its value as null.
- To remove an associated object, use the dedicated delink API endpoint.
Retrieve Resource: Use HTTP GET to fetch an entity by its system-assigned ID or by externalId (your reference Id passed in Create resource request)
- The full set of attributes is returned
- Audit fields like createdOn, createdBy, lastUpdatedOn, and lastUpdatedBy are always included.
- Any associations are returned as objects containing only their URLs; you must make additional GET calls to retrieve their details.
Delete Resource: Use HTTP DELETEto delete an entity by its system-assigned ID or by externalId
Some resources support additional APIs like stop payment, void card payment. They will be covered in the respective documentation sections.

The PCE Resource API do not support bulk updates. You can work on only one object per request.

External ID

Each entity supports an externalId parameter to allow you to store unique identifier from your system on a PCE Object. All PCE resources support CRUD and List functions via externalId parameter.

Meta Data

Each entity supports a free-form metaData map. You can use this parameter to attach a key-value pair and store additional, structured information on an object.

You can specify up to 50 key-value pairs.

For example, you can store your partner id as a unique identifier.

Do not store sensitive information (e.g. account numbers, card details or other pii information) in metadata parameter.

PCE will never use metaData for any kind of verification, authorisation or processing.

Pagination and Listing

All top level resources have support to bulk fetch objects through the "list" API. It uses HTTP POST. For e.g., you can list customers, list transactions, list accounts. These list API's share a common structure and accept, at a minimum below parameters:

Parameter	Description
`criteria.filter`	Allows you to filter the data based on multiple criteria supported by each resource; most importantly, based on audit fields like `createdOn`, `lastUpdateOn`. The response displays entity records that meet the defined filter criteria in the request. The request contains three important parameters - `key`, `operator`, `value` `key`: Key for a resource can be any attribute for the resource. `operator`: Supported Values to the filter the data include: `eq`: exact value passed. `ne`: not matching the value passed. `lt`: value less than the filtered value for the stated field. Applicable to fields with type: date, timestamp, big Decimal, integer, long. `gt`: value greater than the filtered value for the stated field. Applicable to fields with type: date, timestamp, big Decimal, integer, long. `lte`: value less than the filtered value for the stated field. Applicable to fields with type date, timestamp, big Decimal, integer, long `gte`: value greater than the filtered value for the stated field. Applicable to fields with type date, timestamp, big Decimal, integer, long. `in`: value equal to one of the strings passed in the stated field. `like`: result should be consistent with the value passed. For field type string, it allows partial search along with full search. `values`: User is required to provide the filtered value(s) for the field. In case of multiple values, each value should be separated by a comma (,)
`limit`	Specifies a limit on the number of objects to return, ranging between 1 and 100. `Optional` Note: If `pageNumber`is passed, it take precedence on list response over `limit` field.
`sortOptions`	Define the sorting parameters by passing `sortBy`: Field name to sort on. `sortOrder`: to specify sorting direction -`ASC` or `DESC`. Note: `Optional` Defaults to `DESC` sort on `lastUpdatedOn` if no sort criteria are provided.
`offset`	A resource ID of the last record returned in the previous call. Requires sorting by `ID`field. `Optional`
`pageNumber`	Specifies which “page” of results to return. This is recommended for application list pagination. `Optional` Default: 1
`pageSize`	Number of records per page. This is recommended for application list pagination. `Optional`Default: 1000.
`getTotalCount`	Set as `true` to return the `totalCount` of records matching the filter criteria. `Optional` Default: `false`

List Response Format

Parameter	Description
`totalCount`	Returns the total count of records matching the filter criteria
`returnedCount`	Returns the count of records returned in the available set. `returnedCount` will always be less than or equal to `totalCount`
`offset`	`ID` of the last record returned in the previous call.
`hasMore`	Specifies whether or not there are more records available after this set. If `false`, this data set comprises the end of the list.
`pageNumber`	Returns the pageNumber of the set.
`resources`	An array of data containing actual response records, paginated by request parameters

Note: All the list APIs have a data lag of 30 minutes from the time of creation.