Sample project with basic authentication

To test endpoints in the API, Pismo recommends you use a REST client, such as Postman. To help you with testing, Pismo provides a Postman collection and environment for a sample project. A collection is a group of API requests that can be arranged in folders inside Postman and saved to a file for future use. Postman also enables you to create an environment for use with a collection. A collection that is loaded in Postman can read from and write to variables in a loaded environment. An environment can also be saved to a file for future use.

Click the link below to download a ZIP file containing the files for the sample project.

Credit Card collection - Demonstrates how to set up and manage a credit card account.

The ZIP file contains a collection file and an environment file in JSON format. A sample Organization (Org) already exists for the project.

📘
Make sure you read the Core objects section before working with the Sample project.

Import the collection into Postman

Unzip credit.zip. You should have the following files.
- Pismo - Credit program.postman_collection.json - A Postman collection for the Credit Card program.
- Sandbox.postman_environment.json - A Postman environment file for the Pismo Sandbox.
Open Postman and go to Import > Upload Files.
Select Sandbox.postman_environment.json and click Ok. This loads the Sandbox environment into My Workspace. In the upper right corner of My Workspace, there's a dropdown menu that enables you to choose the active environment from a list of loaded environments. Loading the Sandbox environment adds it as an option in this menu.
Select "Sandbox" from the dropdown menu.
Now, you're ready to import the credit card collection. Go to Import > Upload Files and select Pismo - Credit program.postman_collection.json. The endpoints for setting up a credit card program should appear in My Workspace.

Test the endpoints

Most endpoints require values that are returned by other endpoints. The collection is set up so that if you call the endpoints in a set order, the necessary values are automatically saved to the Sandbox environment and retrieved from that environment when needed. For example, when you run the endpoint that creates an account, the account ID is saved to the variable accounts.created.accountId in the Sandbox environment. If you then run a request that requires an account ID, it can retrieve it from this variable.

The Quick reference section lists the requests you should run in the order you need to run them. This enables you to test most of the endpoints in the Credit Card collection.

Quick reference

To test the endpoints in the Credit Card collection, execute the following requests in order.

Platform > Server Authentication
Platform > Programs > List Programs
Platform > Programs > Get program due dates
Platform > Acquisitions > Create an account application
Enduser > Server Login with Account
Enduser > Accounts > personalData > Register a new phone
Enduser > Cards > plastic > Create plastic card
Enduser > Cards > plastic > Get card PCI info
Enduser > Payments > Make a transfer > Make a Cash-In transfer
Enduser > Payments > Create payment request
Enduser > Payments > Pay a payment request

🚧
If you get the following error when you try to send a request, it probably means that you forgot to set the environment to "Sandbox".
Could not send request
Error: getaddrinfo ENOTFOUND {{baseurl}}

The following sections explain these endpoints in detail.

Getting an access token

Most of the endpoints require an access token. So, before you do anything else, you need to get a token by running the Platform > Server authentication endpoint.

Note that this is a POST request, and the URL of the request is {{baseUrl}}/passport/v2/s2s/access-token. {{baseUrl}} tells Postman to replace this part of the URL with the value stored in baseUrl in the Sandbox environment.

Click the Body tab to see how values for server_key and secret_key are loaded from environment variables. You need to have these values to get an access token. In production, you acquire these via the Pismo Console. See Authenticating requests for more information.
Click the Tests tab to see how the collection stores the values returned for tenant and accessToken in other environment variables. (The tenant is the same as the Org ID.)
Click Send. You should get a response similar to the following.

{
    "server_key": "2ffaec587e095409c82826c3a5aa584ee588097e",
    "tenant": "TN-f878e4a1-2879-48ba-be16-821e73ac98db",
    "program_ids": [],
    "roles": [
        "account-server",
        "onboarding-server"
    ],
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJQYXNzcG9ydCIsInN1YiI6IkFVVEgtZTU0ZmE1ODAtYWZkMS00OTQ4LTg4ZjEtY2RmZjk1Y2I5YjYyIiwiZXhwIjoxNjQwMDk3MTE2LCJpYXQiOjE2NDAwOTY1MTYsInVpZCI6IlROLWY4NzhlNGExLTI4NzktNDhiYS1iZTE2LTgyMWU3M2FjOThkYjoyZmZhZWM1ODdlMDk1NDA5YzgyODI2YzNhNWFhNTg0ZWU1ODgwOTdlIiwidGt2ZXIiOiIyIn0.BqRdJXYbt9weHDqUpn3JNCReO97MzzcQAmdJr8I1XQpcRCi6di9mWp5wXcMpxDsUaN2_JbONIqNWVLBRRVgi9Q",
    "refresh": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJQYXNzcG9ydCIsInN1YiI6IkFVVEgtZTU0ZmE1ODAtYWZkMS00OTQ4LTg4ZjEtY2RmZjk1Y2I5YjYyIiwiZXhwIjoxNjQwMDk3MTE2LCJpYXQiOjE2NDAwOTY1MTYsInVpZCI6IlROLWY4NzhlNGExLTI4NzktNDhiYS1iZTE2LTgyMWU3M2FjOThkYjoyZmZhZWM1ODdlMDk1NDA5YzgyODI2YzNhNWFhNTg0ZWU1ODgwOTdlIiwidGt2ZXIiOiIyIn0.BqRdJXYbt9weHDqUpn3JNCReO97MzzcQAmdJr8I1XQpcRCi6di9mWp5wXcMpxDsUaN2_JbONIqNWVLBRRVgi9Q"
}

🚧
The access token that you get when you run Server authentication expires after a fairly short time. If you get the error message "Unauthorized" when running an endpoint, you need to re-run Server authentication to get a new token.

Setting the program ID

For some of the endpoints, you need the program ID. To get that, run the Platform > Programs > List Programs endpoint. The returned list contains the info for a number of different programs. When you run the endpoint, it stores the ID for one of the Mastercard credit programs in an environment variable. The endpoints that need this value are set up to retrieve it from there.

Testing non-account-specific endpoints

You're now ready to test endpoints that don't need to access accounts. Try running the Platform > ExchangeRates > Get exchange rates endpoint. It should execute successfully and return the information for one exchange rate, which is already set up for your Org.

Go ahead and test the endpoints that follow Get exchange rates, up to and including Platform > Programs > Get program channels.

Creating an account

You've already saved the ID for a credit card program in the environment. Now you're ready to create an account for that program. But before you can do this, you need a program due date. This is the day of the month that the statements for the account will come due. Each program has one or more program due dates that you can assign to new accounts.

Run Platform > Programs > Get program due dates to get a list of due dates. The collection stores one of the dates in the environment for future use.
Run Platform > Acquisitions > Create an account application. This creates a credit card account, and the collection stores the account ID in the environment.

Getting an access token for a specific account

The rest of the endpoints in the collection target the account that you just created. But before you can successfully execute them, you need to get a second access token. This token is specific to that account and gives you permission to access it.

Run Enduser > Events > Server Login with Account. This returns an account-specific access token and stores it in the environment.

Testing account-specific endpoints

Now that you have an account-specific access token, the remaining endpoints should work. The only catch is that some of them need to be executed in the correct order. For example, before you can run Enduser > Cards > Plastic > Get card info, you need to create a card by running Enduser > Cards > Plastic > Create plastic card. Keeping that in mind, you can go ahead and test the remaining endpoints.