Introduction

Welcome to PT API. It is Prepaid Technologies' end-to-end platform that makes it simple to create digital banking and branded card experiences. This documentation includes comprehensive information for building financial products and integrating with PT API.

The PT API is RESTful, so it uses HTTP methods (POST, PUT, GET) to perform functions on objects. For example, to login with the client user, you send a POST request to the /login endpoint. Some requests include data in their message body, for example, to define the attributes of the object being created or updated, and the PT API requires that this data be in JSON format.

The fastest way to get your integration up and running is to use our Quick Start guide, which walks you through the essential integration steps. We've tried to make this documentation user-friendly, but if you have any questions, please head to our Discord Server. <TODO - setup the server>

API Protocols

The PT API uses GET and POST requests to communicate and HTTP response codes to indicate status and errors. All requests must include a Content-Type of application/json and the body must be valid JSON. All responses are in standard JSON.

API Design Guidelines

Allowed HTTP methods with PT APIs

1. GET
   The GET method is used to retrieve information from the given server using a given URI. Requests using GET should only retrieve data and should have no other effect on the data.

2. POST
   A POST request is used to send data to the server.

3. PUT
   Replaces all current representations of the target resource with the uploaded content.

4. DELETE
   Removes all current representations of the target resource given by a URI.

Standard PT API Query parameters

Paging

limit/offset parameter enables pagination for the client application. PT supports Offset Pagination implementation. Limit/Offset Paging would look like GET /cards?limit=20&offset=100. This query would return the 20 rows starting with the 100th row.
Example of pagination with 20 cards in each call:-

• A client makes a request for the most recent cards: GET /cards?limit=20

• On scroll/next page, client makes second request GET /cards?limit=20&offset=20

• On scroll/next page, client makes third request GET /cards?limit=20&offset=40

Filtering

Filtering consists of restricting the number of queried resources by specifying some attributes and their expected values. URL parameters are the easiest way to add basic filtering to REST APIs. If you have an /cards endpoint, you can filter via the property name such as:-

GET /cards?status=active

GET /cards?status=active&expDate=12242021

Sorting

Sorting the result of a query on a collection of resources. A sort parameter should contain the names of the attributes on which the sorting is performed, separated by a comma. To enable sorting, add a sort_by URL parameter that can take a field name as the value and the asc/desc functions to specify ascending or descending order respectively.
Example formats
GET /users?sort_by=asc(email) and GET /users?sort_by=desc(email)
GET /users?sort_by=desc(last_modified),asc(email)

Searching

A search is a sub-resource of a collection. Searching can allow fuzziness matching and provide flexible queries for API users. For example, we could search cardholders for those that have a first name as Joe and the age is greater than or equal to 20 and less than or equal to 30.

GET /cardholders?q=firstName:joe AND age:[20 TO 30]

PT APIs Status Codes

200 – OK
Everything is working

201 – CREATED
A new resource has been created

204 – NO CONTENT
The resource was successfully deleted, no response body

304 – NOT MODIFIED
The date returned is cached data (data has not changed)

400 – BAD REQUEST
The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g. „The JSON is not valid “.

401 – UNAUTHORIZED
The request requires user authentication. Find details in the Error codes table.

403 – FORBIDDEN
The server understood the request but is refusing it or the access is not allowed. Find details in the Error codes table.

404 – NOT FOUND
There is no resource behind the URI. Find details in the Error codes table.

500 – INTERNAL SERVER ERROR
This is a generic error response with no details. If an unhandled error occurs on the server-side then the stack trace will be logged and not returned as a response. Find details in the Error codes table.

Error Codes:

Glossary

About the Platform

PT API is built on the Prepaid Technologies Platform, which processes millions of dollars of payments annually and inherits all scalability, reliability, and security features of the Prepaid Technologies platform.

Digital Banking

Cardholders need a way to manage their accounts. This includes viewing balances, tracking spending, and accessing monthly statements. Digital banking is how we describe any user interface that provides these functions for cardholders.

PT API Components

Four components of PT API product are below :

• Developer Portal: A web tool for Developers and Businesses to explore the Prepaid Technologies offerings and subscribe to PT products.

• Product: It contains one or more APIs as well as a usage quota and the terms of use. Once a product is published, developers can subscribe to the product and begin to use the product's APIs.

• Feature: Feature is a business functionality to the end-user. Set of PT APIs need to be called in the correct order to implement a Feature in the client application.

• API: It stands for 'Application Programming Interface'. PT API enables our clients to create financial applications that access the features or data of Prepaid Technologies.

Developer Portal

Before using PT API to create financial products, enroll your business through our Developer Portal, and get Subscription details - Primary key and Secondary key.

Master Funds Account

Prepaid Technologies creates a master funds account for every business that enrolls in PT API. This account can be used to instantly fund cardholder accounts, enabling a wide variety of product use cases.

Parent-Client Hierarchy

To manage the card programs for clients using the Prepaid Technologies platform, a parent client hierarchy is created. There are two business models to support client requirements.

Business Model 1

It has 3 general levels as explained below:-

1. Group Level - This represents the complete client business or corporation. The client admin users will have direct access to this hierarchy level. In the PT system, this is identified with parentId.

2. Client Level - This represents the individual client business units. So a corporation can have multiple business units known as “Client”. In the PT system, this is identified with customerId.

3. Program Level - This represents financial products like gift cards, rewards, payroll, etc. So a business unit can have multiple enrollments to financial products known as “Program Type”. In the PT system, this is identified with rowed.

Open

Open

Business Model 2

It has 2 general levels as explained below:-

1. Client Level - This represents the individual client business units. So a corporation can have multiple business units known as “Client”. In the PT system, this is identified with customerId.

2. Program Level - This represents financial products like gift cards, rewards, payroll, etc. So a business unit can have multiple enrollments to financial products known as “Program Type”. In the PT system, this is identified with rowed.

PT API Object Model

Business - this object represents PT’s clients which are using the Prepaid Technologies platform and in a business relationship with PT.

User - this object represents a person from a business who uses the Prepaid Technologies platform to manage their cards, cardholders, and funds. This endpoint enables you to log in, log out, reset the user’s password on the Prepaid Technologies platform.

Standard Product

This product enables a client to build a stand-alone application or integrate features into their existing financial application. It provides the 4 basic and most used features from the Prepaid Technologies platform.

Advance Product

This product enables a client to build an advanced stand-alone application or integrate enhanced features into their existing financial application. It provides advanced features in addition to the standard product which includes the Service cards and cardholders feature. There will be a technical due diligence and approval process to get a subscription for the Advance product. Consumer for Advance Product needs to support an ongoing regular audit.