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.

ObjectDescription
OrganizationDefines your company or enterprise. Contains one or more programs.
ProgramDefines a set of parameters for a group of accounts. A program has a type, such as credit, debit, or prepaid.
EntityA 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.
AccountEach account belongs to a single program. An attribute not defined for an account is inherited from its program.
CustomerEach 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

Setting up your Organization (Org) is done for you by the Pismo implementation team — using the following information (along with other requirements).

Org elementDescriptionExample
Official nameYour organization or company's legal namePismo Organização LTDA
Organization nameYour organization's preferred name on the Pismo platformChange the World
Document numberYour organization's documentation number08350504000143
AddressStreet addressRua Itambé
NumberStreet address number900
Complementary addressAny complementary address information - unit, floor, etc.Conj. 123
NeighborhoodNeighborhoods - some countries use assigned neighborhoods in addressJardim Satélite
ZipcodeCountry postal code12230660
CityCitySão Paulo
StateState/Province/RegionSP
CountryCountryBrazil
Legal proxy nameYour organization's legal representativePismo Organização LTDA
Legal proxy documentYour organization's legal representative document123456
EmailEmail[email protected]
Currency numeric codeISO 4217 currency numeric code, e.g., 986 (Brazilian real)986
TimezoneTimezone nameAmerica/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 Retrieve org data endpoint to retrieve your organization's information.

Program types and parameters

After you have your org set up, you can use the Pismo Control Center to create the first program associated with your org. Program attributes depend on the type of program. For a list of available program types, see Program parameters reference table.

📘

You can perform most program configurations using Control Center. However, some configuration steps may still require you to work through the Pismo implementation team.

The following table shows Program parameters you need to define during setup.

Program elementDescriptionExample
NameProgram nameXYZ credit card
TypeProgram typeCredit, Debit
Card networkVisa, Mastercard, or PrivateVisa
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
CurrencyISO 4217 currency codeBRL - Brazilian Real
TimezoneTimezone database nameAmerica/Sao Paulo
Due datesDay 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

Every customer has an associated entity object. If one isn't passed in the Create customer endpoint, then one is automatically created based on government document number. An organization can have multiple customer objects with different customer IDs all mapping to the same entity object, meaning they are all the same person or company. You can call Get customer to see a customer's entity object.

To search an organization's data using an entity ID, contact our Service Desk and request this.

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
collections_status string Account's financial status.
NORMAL, EM, ATRASO, ACORDO
"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"
email 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(Credit)
CREDITO ZERO-BALANCE
DEBITO(Debit)
DEBITO ZERO-BALANCE
LENDING
PRE-PAGO(Prepaid)
PRE-PAGO ZERO-BALANCE
CURRENT ACCOUNTS
INTERNAL ACCOUNTS
CORRESPONDENT ACCOUNTS
Credit
social_name string Social name "Frankie"
status string Current account status:
NORMAL, ACCOUNT_CANCELLATION, BLOCK_JUDICIAL_BLOCKED, CANCELLED DEFINITIVE_CANCELLATION, FULL_CANCELLATION
"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"
email 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
email 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

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.

To get started issuing cards, see Card issuing with pismo.