Core objects
This topic describes getting started with the Pismo platform and the core objects that are configured during your onboarding process. Many endpoint calls address and interact with these core objects.
The following diagram shows, at a high-level, the mapping of account customers to entities.
Basic component structure
The Pismo platform has a built-in object hierarchy. The following table describes the platform's built-in object hierarchy and their basic relationships.
| Object | Description |
|---|---|
| Organization | Defines your company or enterprise. Contains one or more programs. |
| Program | Defines a set of parameters for a group of accounts. A program has a type , such as credit, debit, or prepaid. |
| Entity | A legal entity (person, company, or organization). As an attribute, an entity object contains a government document number, such as a driver's license, as well as other legal information that identifies a person, company, or organization. A customer has an associated entity object. If one isn't passed in the Create customer endpoint, a default one is created. Within an organization, multiple customers with different customer IDs could all map to the same entity object, meaning they are all the same person or company. Potentially, this could be used to track a person's or company's activities within an organization and to link them to a person or company in a different organization. To search an organization's data using an entity ID, contact our Service Desk and request this. |
| Account | Each account belongs to a single program. An attribute not defined for an account is inherited from its program. |
| Customer | Each account contains at least one customer, either an individual or company. Accounts can have multiple customers (typically to accommodate additional cardholders) but only one designated owner. A customer can only belong to one account. |
Core objects
Field lengths and ranges
Specific field lengths and ranges are not detailed in the tables below. However, you can find that information in API endpoint reference documentation.
The first thing you need to do is work with Pismo to onboard your Organization and first Program to the platform. Once those are in place, you can start creating accounts and customers, issuing cards, and calling Pismo API endpoints.
Organization
This Pismo implementation team works with you to set up your Organization.
| Description | Org element | Example |
|---|---|---|
| Your organization or company's legal name | Official name | Change the World LLC |
| Your organization's preferred name on the Pismo platform | Organization name | Change the World |
| Your organization's document number | Document number | 08350504000143 |
| Street address | Address | Maple Lane |
| Street address number | Number | 900 |
| Any complementary address information - unit, floor, etc. | Complementary address | Suite 200 |
| Neighborhoods - some countries use assigned neighborhoods in address | Neighborhood | Shady Oaks |
| Country postal code | Zipcode | 12230660 |
| City | City | London |
| State/Province/Region | State | SP |
| Country | Country | England |
| Your organization's legal representative | Legal proxy name | Pismo Organization LTDA |
| Your organization's legal representative document | Legal proxy document | 123456 |
| [email protected] | ||
| ISO 4217 currency numeric code, e.g., 986 (Brazilian real) | Currency numeric code | 986 |
| Timezone name | Timezone | America/Sao_Paulo |
Once created, your Org is assigned an identifier that is referred to as either an Org ID or Tenant ID and will look similar to this:
tn-34778262-f4f0-464d-b4c6-a14e2dc6f4be
Most endpoints take this field as a parameter, usually in a header. You can use the Get Org endpoint to retrieve your organization's information.
Program
After you have your Org set up, you can use the Pismo Control Center to create your organization's first program. Program attributes depend on the program type . Pismo also has an API specifically for program operations.
Pismo Control Center limitations
You can perform most program configurations using the Pismo Control Center. However, some configuration steps may still require you to work through the Pismo implementation team.
The following table shows Program attributes you need to define during setup.
| Program element | Description | Example |
|---|---|---|
| Name | Program name | XYZ credit card |
| Type | Program type | Credit, Debit |
| Card network | Visa, Mastercard, ELO, or Private | Visa |
| BIN (bank identification number) BIN start range BIN end range | Refers to the first four to eight numbers on a payment card. The BIN identifies the financial institution that issued the card. It is used to match transactions to the card issuer and can help identify fraudulent or stolen payment cards. | 67845321, 100, 899000 |
| Currency | ISO 4217 currency code | BRL - Brazilian Real |
| Timezone | Timezone database name | America/Sao Paulo |
| Due dates | Day of the month that the statements for the account come due. Each program has one or more program due dates that you can assign to new accounts. | 1, 15 |
Entity
An entity object has the following fields:
| Property | Type | Description | Example |
|---|---|---|---|
| id | string | Entity ID - unique within an organization. | "5446" |
| document_number | string | A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). | "8675309" |
| name | string | Person or company name | "Acme Banking" |
| registration | string | Registration number with the local governing board. For example, in Brazil, this could be the RG (Registro Geral) number. | "909910" |
| birth_date | string | Birth date if person, format = MM/DD/YYYY | "01/23/1985" |
| gender | string | Gender if person - "M", "F", or " " | "M" |
| mothers_name | string | Mother's name if person | "Mabel Sirrup" |
| marital_status | string | Martial status if person | "SINGLE" |
Account
You can create an account with the Create account application endpoint.
An account object has the following fields:
| Property | Type | Description | Example |
|---|---|---|---|
| org | string | Organization/tenant ID | "TN-34778262-f4f0-464d-b4c6-a14e2dc6f4be" |
| program_id | integer | Associated program ID | 87654 |
| account_id | integer | Pismo account ID | 103687654 |
| customer_id | integer | Pismo customer ID | 122687654 |
| parent_account_id | integer | Parent account ID | 122687654 |
| external_id | string | Client-generated account ID. | "3ed4f6d4-ad35-4857-b1e3-dbf5d5bd4148" |
| account_status_date | string | Account status date/time in RFC3339 format | "2021-10-21T00:00:00.000Z" |
| acquisition_id | integer | Acquisition channel ID. An acquisition channel is the mechanism that brought the account creator to Pismo, such as a web app, mobile app, or web page. The mechanisms and ids are derived from the program. | 123 |
| available_limit | number | Available credit limit | 2270 |
| available_monthly_credit | number | Monthly amount available for credit programs. | 0.0 |
| available_total_installment_credit | number | Available total installment credit | 0.0 |
| available_withdrawal_credit | number | Available withdrawal amount for credit programs. | 0.0 |
| blocked_amount | number | Blocked amount | 0.04 |
| collection_status | string | Account's financial status.NORMAL, OVERDUE |
"NORMAL" |
| creation_date | string | Account creation date/time in RFC3339 format | "2021-10-21T00:00:00.000Z" |
| current_balance | number | Current balance for credit programs. | 100.43 |
| current_cicle | integer | Current statement cycle for credit programs. | 3 |
| document_number | string | Government document number | "514-08-3862" |
| string | Account email | "[email protected]" | |
| entity_type | string | Account's entity type. Can be FISICA for
natural persons or JURIDICA for legal persons.
|
"FISICA" |
| exchange_mode | string | Whether any foreign transaction should be charged by the
exchange rate on the day it occurred or at the statement's closing date.SAME_DAY, CLOSING |
"SAME_DAY" |
| is_owner | boolean | Is customer account owner flag | true |
| max_credit_limit | number | Maximum credit limit | 0.0 |
| monthly_credit_limit | number | Monthly credit limit | 0.0 |
| name | string | Account owner name | "Frank N. Stein" |
| open_due_date | string | Open due date | "2018-01-01T00:00:00.000Z" |
| postal_address_type | integer | Postal address type | 123 |
| program_due_date_id | integer | Program due date ID | 3456 |
| program_name | string | Name of account program | "Digital Wallet Program" |
| program_type | enum string | Account's program type |
CREDITO |
| social_name | string | Social name | "Frankie" |
| status | string | Current account status:NORMAL, BLOCKED, CANCELLED plus custom statuses. |
"CANCELLED" |
| status_reason_description | string | Status reason, Status reasons and status reason IDs need to be configured on a per-client basis with your Pismo representative. | "FRAUD SUSPECTED" |
| status_reason_id | integer | Status reason ID | 16 |
| total_credit_limit | number | The total credit limit as set by the user. This can be any value up to the max_credit_limit. |
0.0 |
| total_installment_credit_limit | number | Total installment credit limit | 0.0 |
| withdrawal_credit_limit | number | Amount withdrawal limit for credit programs | 0.0 |
For more information on accounts, see the Accounts overview.
Customer
An account customer can be either a person or a company. When you create an account, the first customer - the account owner - is also created. Accounts can have multiple customers, typically to accommodate primary and additional cardholders, but only one owner. A customer can only belong to one account.
Call the Create customer endpoint to add a customer to an account.
Person customer object
| Property | Type | Description | Example |
|---|---|---|---|
| assets | number | Customer assets value | 2000000 |
| birth_date | string | Birth date, format="YYYY-MM-DD" type | "2019-01-01" |
| city_of_birth | string | Birth city | "São Paulo" |
| country_of_birth | string | Customer birth country | "Brazil" |
| customer_id | number | Pismo customer ID | 4902184 |
| document_issued_at | string | Where document issued | "Sao Paulo" |
| document_issued_by | string | Document issuer | "SSP" |
| document_issued_date | string | Document issued date, format="YYYY-MM-DD" type | "2005-12-20" |
| document_number | string | Government document number | "12345678910" |
| document_type | string | Government document type | "Registro Geral" |
| string | Customer email | "[email protected]" | |
| entity_type | string | Entity type | "Person" |
| fathers_name | string | Father's name | "Terry Dactyl" |
| gender | string | Gender - M, F, '' |
" M" |
| income | number | Customer income | 200000 |
| marital_status | string | Marital status - SINGLE, MARRIED, DIVORCED, WIDOWED |
" MARRIED" |
| mothers_name | string | Mother's name | "Petra Dactyl" |
| name | string | Customer name | "Teri Dactyl" |
| nationality | string | Nationality | "Brasileiro" |
| net_worth | number | Customer net worth | 4000000 |
| nickname | string | Customer nickname | "Skippy" |
| occupation | string | Customer occupation | "Programmer" |
| other_id_number | string | Other ID number | "29000000" |
| pep | boolean | Is person a PEP (Politically Exposed Person) flag. A PEP generally presents a higher risk for potential involvement in bribery and corruption by virtue of their position and the influence that they may hold. |
true
|
| printed_name | string | Display name | "TDactyl |
| social_name | string | Social name | "Teri" |
| state_of_birth | string | Birth state | "Sao Paulo" |
| type_id | integer | Type ID | 1 |
Company customer object
| Field | Type | Description | Example |
| activity | string | The economic activity the government has licensed the company to do. | "ESPORTE" |
| annual_revenues | float | Company annual revenues (monthly billing average) | 6000000 |
| company_consititution_date | string | The company's operational start date in RFC3339 format | 2004-01-20T00:00:00.000Z |
| company_format | string | The legal category under which the company is registered (LLC, LTD, INC, etc) | "LLC" |
| company_name | string | Company name | "Acme Banking Inc." |
| company_type | string | Company type | "DENTISTA" |
| customer_id | integer | Pismo customer ID | 122687654 |
| debt | float | Company debt | 2890000.00 |
| string | Company email | "[email protected]" | |
| income | float | Company income | 230000000.00 |
| name | string | Company representative name | "Fran Tick" |
| net_worth | float | Company net worth | 4590000000 |
| nickname | string | Company representative nickname | "Fridge" |
| number_of_partners | integer | Number of company partners | 2 |
| occupation | string | Company representative's occupation | "Financial Analyst" |
| partners | object array | Partner objects - similar to person customer object | |
| perc_ownership | float | Company percentage ownership | 80.24 |
| pep | boolean | Is company representative a PEP (Politically Exposed Person) flag |
true
|
| printed_name | string | Printed name on card | "Lynn O’Leeum" |
| registration_number | string | Company registration number | "98484037575038" |
| social_name | string | Company representative's social name | "Curveball" |
| type | string | Nature of business relationship | "B2C" |
Other objects
Card
To get started issuing cards, refer to Card issuing with Pismo. You can issue a card with the Create card endpoint.
A card object has the following fields:
| Property | Type | Description | Example |
|---|---|---|---|
| org_id | string | Pismo organization ID | "TN-f878e4a1-2879-48ba-be16-821e73ac98db" |
| program_id | integer | Pismo program ID | 8765 |
| account_id | integer | Pismo account ID | 102378693 |
| customer_id | integer | Pismo customer ID | 102377856 |
| card_id | integer | Pismo card ID | 6741322 |
| abu_enabled | boolean | Must card number be sent to Mastercard's Automatic Billing Updater service? Mastercard only. |
true
|
| card_name | string | Card alias name | "Vacation card" |
| card_number | string | Also known as the PAN - primary account number- 14, 15, or 16 digit number generated as a unique identifier for a primary account | "1234560056527111" |
| card_printed_name | string | Printed name for physical (plastic or metal) cards | "Jenna Flect" |
| card_status | string enum | Card status |
NORMAL
|
| card_type | string |
Card type.
PLASTIC - Physical card
VIRTUAL - Digital card
|
VIRTUAL
|
| contactless_enabled | boolean | For physical cards. Can card make transactions using contactless entry mode? |
true
|
| cvv | integer | Card verification value on card back | 345 |
| cvv_next_rotation_date | string | For virtual cards. Scheduled date and time for next CVV2/CVC2 value change in RFC3339 format. | "2019-07-03T17:23:18.000Z" |
| cvv_rotation_type | string | For virtual cards. Rotation method for CVV2/CVC2 value - manual or automatic |
AUTOMATIC
|
| embossing_custom_field | string | For physical cards. Additional information for embossing company such as a tracking ID or whether card is plastic or metal. | "tracking number=4859302u85u5" |
| expiration_date | string | Card expiration date. Format=yymm | 2401 |
| issuing_date | string | Date and time when card issued formatted as a RFC3339 string. | "2019-07-03T17:23:18.000Z" |
| mode | string | Card mode enum -
DEBIT or
CREDIT
|
DEBIT
|
| mode_type | string | Card mode type enum -
SINGLE or
COMBO. Indicates whether card can be used as both a credit and debit card. See Create a combintation card with card modes for more information.
|
COMBO
|
| pin | string | Card password | "7654" |
| stage | string | Card status stage -
CREATED,
BLOCKED and
UNBLOCKED.
|
CREATED
|
| template_id | string | Template ID if template used to create card. | "EAFA693A-57B2-4029-97F3-D20D6F06D79B" |
| transaction_limit | number | For virtual cards. Maximum amount allowed per transaction. | 750.10 |
Cards also come with associated mode object(s) for combination cards - cards that can be used for both credit and debit transactions. For more information, see Create a combination card with modes.
Updated 24 days ago