Postman Pismo cards collection walkthrough

Use the Postman Pismo cards collection to test a basic use case for creating and managing cards using the Pismo endpoints.

Before you begin:

• Work with your Pismo representative to set up your organization and at least one program configured that enables due dates (debit cards programs do not require due dates). Refer to Core objects for more information and getting started. You can also use Pismo Control Center to do a lot of this setup through a convenient UI.
• Ensure you have some basic data in your organization such as a program configured with due dates.
• Make sure you have the Pismo sandbox environment as the current environment and have updated the environment variables as detailed in the Postman collections guide.

📘

Some endpoints only work with programs that allow those configurations; for example, if the program does not allow cash-in transfers, the "Make a Cash-In transfer" request in this collection does not work with that program ID.

Step 1: Authenticate

All of the endpoints require an access token. So, before you do anything else, request a token by running the endpoint based on your authentication method, either Bearer token or OpenID. You can use OpenID for a sandbox environment but you do not have to since a Bearer token provides adequate security.

• Bearer token call Platform > Authenticate > Get basic authentication access token
• OpenID call Platform > Authenticate > Get OpenID access token

Sending this request automatically saves the access token as a local variable in the collection and this access token is then used in all the calls within the Platform folder. Access tokens expire in six minutes in the sandbox environment and can result in a 401 Unauthorized response message. If your token expires, send the request again to get a refreshed token.

Step 2: Retrieve program information and set program ID

Within the Postman Pismo cards collection, go to Platform > Programs > List Programs.
Running this call sets the program ID to the first ID returned from this request. That variable is stored in the collection variables for future use, so you can set it to your test program if you want. To try a credit card walkthrough, you must use a program with CREDITO type. To try a debit card walkthrough, you must use a program with DEBITO type. The program ID, along with a matching due date ID in the account application request, is required to create an account.

Step 3: Set due dates for the given program ID

1. Platform > Programs > Add program due date
   Sending this request creates a due date with this JSON in the request, setting a 15-day grace period:
   JSON

   {
     "active": true,
     "day": 15,
     "grace_period_days": 15
   }
   

2. Platform > Programs > Get program due dates
   Send this request to update the due dates variable because a due date is required to create an account.
3. (optional) Platform > Programs > Get program channels
   Sending this request shows you the channels for the given program ID. Channels, also known as acquisition channels, provide unique identifiers for the original sources of customers, such as a referring web page or mobile application. For example, the program may have a channel set to "type": "Mobile".

Step 4: Create an account application for a new card

1. Platform > Acquisitions > Create an account application
   Send this request to make a new account application, so that you generate an account ID. Following is the JSON request body sent when creating an account application that uses existing Postman environment variables generated from prior requests:
   JSON

   {
   "application": {
    "due_date": {{dueDates.credit.id}}, # this ID must match one in the Program ID
    "program_id": {{programs.credit.id}},
    "submit": true,
    "applicant": {
      "document_number": "{{randomDoc}}",
      "birth_date": "1980-01-31",
      "personal": {
        "name": "John Doe",
        "email": "{{$randomExampleEmail}}"
      }
    },
    "addresses": [
      {
        "address": "Nowhere St.",
        "number": "10",
        "country": "USA",
        "city": "Somewhere",
        "state": "SW",
        "zip_code": "01234",
        "mailing_address": true
      }
    ],
    "account": {
      "external_id": "{{$randomUUID}}",
      "granted_limit": 1000,
      "limit": 500
       }
     }
   }
   

Once you have stored this account ID as a variable in the Postman environment, you can create an account token, which is an access token encoded with a Pismo account ID. This type of token is required for calls in the account-specific folder of the collection. You get a 201 Created message and a response body from the platform.

Step 5: Authenticate with an account-specific token

Account specific > Authenticate with account > Get basic authentication access token or Get OpenID access token with accountID.
Send the request for a new token that includes the accountID. This variable (account.access.token) is saved separately from the earlier authentication token (access.token) and gets set for all endpoints in the Account specific folder in Postman.

For more information about which endpoints require account tokens, refer to Endpoints that require an account-specific token.

Step 6: Create a physical card with set card limits

1. Account specific > Cards > Physical > Create physical card
   Sending this request body creates a physical card for the account specified with the account token. For this request to work, you must have a program of type CREDITO. Refer to Program types and parameters for more information.
   JSON

   {
     "type": "PLASTIC",
     "name": "My Super Plastic Card",
     "metadata": {
       "my-custom": "data"
     }
   }
   

   You get a 201 Created message and a response body from the platform:
   JSON

   {
       "id": 353880755,
       "name": "PLASTIC",
       "status": "CREATED",
       "type": "PLASTIC",
       "transaction_limit": null,
       "embossing_custom_field": null,
       "metadata": {
           "rewards": "cashback"
       },
       "cvv_rotation_interval_hours": null,
       "printed_name": "John Doe",
       "contactless_enabled": true,
       "embossing_group": null,
       "abu_enabled": true,
       "template_id": "3fc22804-c761-4561-bac7-01cf445b4de2",
       "mode_type": "SINGLE",
       "validity_period_hours": null,
       "valid_until": null
    }
   

2. (optional)Account specific > Cards > Physical > Get card info
   You can get more information about the card by making a request using the card ID. This Get account cards endpoint provides information about the card such as the service code, which is used by different card networks to tell merchant terminals and acquiring networks about any usage restrictions on the card.
3. (optional)Account specific > Cards > Physical > Get card PCI info
   You can get more information about the PCI information for a card using the card ID. This Get card PCI information endpoint provides the name, issuing date, expiration date, card number, and CVV code as well as information about whether the password was updated.

Step 7: Activate the card

Account specific > Cards > Physical > Activate a physical card

After creating a physical card you must activate it to enable transactions. This required action for activation prevents unauthorized operations by persons other than the card holder, until its delivery. Send this request as a PUT /wallet/v1/customers/:customerId/accounts/:accountId/cards/:cardId/activate. No JSON body is sent with this request. In return you get this response:

{
  "message": "The card was successfully unblocked"
}

Now you have an activated physical card record in the sandbox. The remaining requests in the collection provide optional steps you can take.

(optional) Create a payments workflow

1. Account specific > Payments > Make a transfer > Make a Cash-In transfer
   Send this request to create a transfer of cash from an external fake account to the created account ID. By having this data, you can create a payment request and pay the pay the payment request in the sandbox environment. Send this JSON body with the request for a bank transfer:

   JSON

   {
   
    "tracking_id": "{{$randomUUID}}",
    "descriptor": "Another new cash-in transfer",
    "from": [
        {
            "custom_info": {
                "external_id": "{{$randomUUID}}",
   	        "type": "Bank transfer"
            },
            "amount": 500.0
        }
    ],
    "to": [
        {
            "account": {
                "id": {{accounts.created.accountId}}
            },
            "amount": 1500.0
            }
         ]
   }  
   

2. Account specific > Payments > Create payment request

   Make a payment request with this request body. It generates a token that you can use as an identifier for the payment request.

   JSON

   {
     "from": {
        "currency": "BRL",
        "account": {
            "id": 100000125
        }
     },
     "to": {
        "currency": "BRL",
        "account": {
            "id": {{accounts.created.accountId}}
         }
     },
     "amount": 25.5,
     "expiration": "2022-02-01T21:22:12.800Z",
     "encoding": "NONE",
     "metadata": {
         "message": "David's birthday present list"
       }
   }
   

3. Account specific > Payments > Pay a payment request
   Next, use the previously created token to pay that request with this request body, indicating the amount, the account to pay from, and an entry_mode :

   JSON

   {
    "tracking_id": "f902aba3-90e9-4cfc-ab02-27186bdfef34",
    "descriptor": "Making the payment for a payment request",
   "from": [{
   	"amount": 25.5,
   	"account": {
   		"id": {{accounts.created.accountId}}
   	}
   }],
   "token": "{{paymentreq.id}}",
   "entry_mode": "PayReq"
   }
   

Troubleshooting

PCI endpoints

You do not have to use the PCI endpoints for sandbox testing when you are simulating transactions only. Use PCI endpoints for requests that involve handling sensitive card data, such as PAN (Primary Account Number) and CVV (Card Verification Value).