Introduction

To launch demand deposit accounts (DDAs) at Pismo, you need to set up an organization (Org) on the Pismo platform and a hierarchy of divisions within that Org. Then you can set up programs and bind them to one or more divisions belonging to that Org.

The following table lists the components of DDA at Pismo:

* A component is considered single if you would normally have only one of them. A component is multiple if it's normal to have more than one. It's possible for a client to have only one program, for example, but most clients have more than one, so program is marked as multiple.

** A component is considered required if the DDA product does not work without it. A component that is not technically required might still be required in practice because of local regulations or business rules.

The following sections describe how to set up these components.

Step 1 – Set up your Org

The Org is an object that represents your organization on the Pismo platform. You can’t create programs until you have an Org to put them in, so this step is mandatory. The process of setting up an Org is the same for all products on the Pismo platform. There is no API for this. The Pismo implementation team will hold a workshop where you'll be asked to provide the following information, along with other information about your banking needs:

When the implementation team creates your Org, the team assigns an identifier, either an Org ID or a Tenant ID. The ID looks 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 the information for your organization.

See Organization (Org) setup for more info.

Step 2 – Set up a hierarchy

For transaction banking, you need to set up a hierarchy that describes the structure of your Org. A hierarchy is made up of nested components called divisions. Those divisions are organized into levels, which correspond to categories such as geographical region, country, city, branch, etc.

An operation that affects a division also affects all the divisions that are nested within it. For example, suppose you have a level named “City” that contains a level named “Branch”. If you set up weekends as holidays for the City division “London”, then all the Branch divisions nested within the “London” division will treat weekends as holidays.

You set up a hierarchy by defining its levels using the Create hierarchy levels endpoint. A level has a name, an index, and a description. The highest level within the hierarchy should have index 0, the next highest should have index 1, etc. When you first create a hierarchy, it consists of empty levels. You populate the levels with divisions in Step 3.

Most of the transaction banking endpoints act on divisions, and you have to create a hierarchy before you can create divisions, so this step is mandatory.

The following sample code shows how to use the endpoint to create the levels for a hierarchy:

curl --request POST  
     --url <https://api-sandbox.pismolabs.io/corporate/hierarchies>  
     --header 'Accept: application/json'  
     --header 'Content-Type: application/json'  
     --data '  
{  
     "levels": [  
          {  
               "index": 0,  
               "name": "Headquarters",  
               "description": "Root level"  
          },  
          {  
               "index": 1,  
               "name": "Region",  
               "description": "Regional level"  
          },  
          {  
               "index": 2,  
               "name": "Country",  
               "description": "Country level"  
          },  
          {  
               "index": 3,  
               "name": "City",  
               "description": "City level"  
          },  
          {  
               "index": 4,  
               "name": "Branch",  
               "description": "Branch level"  
          }  
     ],  
     "name": "Hierarchy One"  
}

If successful, the call returns a response similar to the following:

{  
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  
  "name": "Hierarchy One",  
  "levels": [  
    {  
      "id": "df48f983-c906-4bb3-83c7-ac2e18babb59",  
      "name": "Headquarters",  
      "index": 0,  
      "description": "Root level"  
    },  
    {  
      "id": "e7685dd9-e2c8-4a05-baf7-c7dd72c0969f",  
      "name": "Region",  
      "index": 1,  
      "description": "Regional level"  
    },  
    {  
      "id": "0b05d677-602f-4874-92ea-a23471573c67",  
      "name": "Country",  
      "index": 2,  
      "description": "Country level"  
    },  
    {  
      "id": "3cf5d1cf-e440-4813-ab14-7de22d2418e3",  
      "name": "City",  
      "index": 3,  
      "description": "City level"  
    },  
    {  
      "id": "22f4f976-11f2-451c-b62c-d4e2e174d90b",  
      "name": "Branch",  
      "index": 4,  
      "description": "Branch level"  
    }  
  ]  
}

Notice that the response includes an ID for each new level (and also one for the array).

See Creating a hierarchy with levels for more info.

Step 3 – Add divisions

Divisions are the nested components that make up the structure of your Org. Each division is assigned to a level. A division can contain other divisions, but only if they are at a lower level in the hierarchy.

For example, under a level named "Country", the divisions could be "United Kingdom", "Germany", "The United States", etc. Under the “United Kingdom” division, you might add City divisions, such as “London”, “Manchester”, etc. Under each City division, you might add Branch divisions.

Divisions are the components that actually make up a hierarchy. Levels are just a way of organizing them by type. So, adding divisions to the levels is a mandatory step. You use the ID of a level to add divisions to it. You add a division using the Create division endpoint. This endpoint requires the following path parameters:

It also takes the following body parameters:

A typical call to Create division looks something like this:

curl -X POST '<https://api-sandbox.pismolabs.io/corporate/hierarchies/><hierarchy ID>/levels/<level ID>/divisions' -H 'x-tenant: <Organization ID>' -H 'Content-Type: application/json' -d '{"parent_id": 1c6ca187-e61f-4301-8dcb-0e9749e89eef, "name": "London", "description": "LON - London City"}'

If successful, the call returns a response similar to this:

{  
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  
  "level_id": "3cb85fcc-c00c-4c83-ae89-cd2568531125",  
  "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",  
  "name": "London",  
  "description": "LON - London City"  
}

Notice that the response includes an ID for the new division.

A division element (for example, Country = "United Kingdom") can have a parent/child relationship with a division at a higher level. For example, “London” is not only a division element for the City level, it could also have “United Kingdom” as its parent division at the Country level. You define a division's parent division by putting the ID of the parent in the parent_id field. This field is mandatory for every division that is not in the topmost level. Divisions that are in the topmost level do not have parents, so parent_id is not required for them.

See Adding divisions for more info.

Step 4 – Set up holidays

For each division, you can set up holidays for the days on which you do not want to allow your customers to complete transactions. If you do not set up any holidays, transactions are allowed at any time, 24/7 - 365 days a year.

Organizations often need to block transactions on certain days for security or regulatory reasons. Brick and mortar branches, for example, might close on weekends and some holidays. Accepting transactions when no one is working could increase the regulatory and operational risk. Also, some countries only allow interest to accrue on business days. If an account holder is allowed to make a transaction on a non-business day, this can cause problems calculating interest.

You set up holidays using the Update division endpoint. This endpoint requires the following path parameters:

It takes the following body parameters:*

*Fields not listed in the above table are not applicable to holidays.

Examples:

1. Define a holiday in the Temuco division. (Assume the path variables hierarchyId, levelId, and divisionId are set for Temuco.):

   cURL

   curl --request PATCH '<https://api-sandbox.pismolabs.io/corporate/hierarchies/{hierarchyId}/levels/{levelId}/divisions/{divisionId}>'  
   --header 'x-tenant: {tenId}'  
   --header 'Content-Type: application/json'  
   --data-raw '{  
       "holidays": [  
           {"month": 2, "day": 2, "description": "Temuco festival"},  
           {"month": 2, "day": 3, "description": "Temuco festival"}  
       ],  
       "allow_weekends_transactions": false  
   }'
   

2. Define a holiday in the Chile division. (Assume the path variables hierarchyId, levelId, and divisionId are set for Chile.):

   cURL

   curl --request PATCH '<https://api-sandbox.pismolabs.io/corporate/hierarchies/{hierarchyId}/levels/{levelId}/divisions/{divisionId}>'  
   --header 'x-tenant: {tenId}'  
   --header 'Content-Type: application/json'  
   --data-raw '{  
       "holidays": [  
           {"month": 3, "day": 15, "description": "Chile special date"}  
       ],  
       "allow_weekends_transactions": false  
   }'
   

📘

Since the program_id field is not included in the above requests, the holidays are applied to all programs in the specified divisions.

See Managing holiday and weekend calendars for more info.

Step 5 – Set up an account schema for specific validations

You can store more information in a customer account than just the regular objects. To do this, use the custom fields in the Create corporate account endpoint, which are inside the applicant object. If you need to perform specific validations on those custom fields, define those validations on the division where the account is located. You do this by defining the validation rules in a JSON schema and using the Update division endpoint to attach the schema to the division.

Using a JSON schema to validate custom fields is not mandatory, but it might be needed to meet local regulations and business rules. For example, you might have a business rule to retrieve a customer number from the applicant’s address confirmation document. You would need to set up a JSON schema to confirm that a number is retrieved from the document.

You set up an account schema using the Update division endpoint. This endpoint requires the following path parameters:

It takes the following body parameters:*

*Fields not listed in the above table are not applicable to account schemas.

The following sample code shows how to use the Update division endpoint to make the custom field product_id required:

curl --request PATCH \\ --url https\: //api-sandbox.pismolabs.io/corporate-beta/hierarchies/hierarchyId/levels/levelId/divisions/divisionId \--header 'Content-Type: application/json'  
--data ' {  
    "schema": {  
        "$schema": "<https://json-schema.org/draft/2020-12/schema>  

",  
        "$id": "<https://pismo.io/acquisitions.latam.schema.json>  

",  
        "title": "Schema validator for Chile V1",  
        "type": "object",  
        "properties": {  
            "product_id": {  
                "description": "The unique identifier for a product",  
                "type": "integer"  
            }  
        },  
        "required": [  
            "product_id"  
        ]  
    }  
}'

See Create a schema validation for account creation metadata for more info.

Step 6 – Set up your programs

Programs define the types of accounts a customer can open with your Org, such as credit and debit accounts. You can't create customer accounts without at least one program, so this step is mandatory.

You can set up a program using the Pismo Console. See Program setup for more info.

Alternatively, you can set up a program using the API endpoint Create a program based on Pismo's template. This endpoint takes the following fields:*

*Fields not listed in the above table are not applicable to transaction banking.

The following sample code shows how to use this endpoint to create a current accounts program named "Sample_current_accounts_program":

curl --request POST  
     --url <https://api-sandbox.pismolabs.io/programs/v1/programs/template>  
     --header 'Accept: application/json'  
     --header 'Authorization: Bearer eyGhbGciOiJSUzI1NiIsImtpZCI6IkQ3Y2JlZTU3MmFlM2MzZGQzNjBjNzA5OGRhOTA1MjMzNmJjN2FjYTIiLC'  
     --header 'Content-Type: application/json'  
     --data '  
{  
     "timezone": "America/Sao_Paulo",  
     "currency_numeric_code": "986",  
     "name": "Sample_current_accounts_program",  
     "type": "CURRENT ACCOUNTS"  
}'

Step 7 – Bind your programs to divisions

To use a program, it must be bound to at least one division. You bind programs to divisions using the Update division endpoint. See Binding a program to a division for more info.

When you bind a program to a division, you tell the Pismo platform that accounts of that type can be opened in the division. You won’t be able to open any accounts until you bind at least one program to at least one division, so this step is mandatory.

You bind your programs using the Update division endpoint. A division can be bound to one program set (the group of programs that are available to a division).

🚧

If you use Update division to bind a program set to a division, a subsequent call to this endpoint for the same division creates a new program set that effectively replaces the previous one.

The Update division endpoint requires the following path parameters:

The Update division endpoint takes the following body parameter:*

*Fields not listed in the above table are not applicable to program binding.

The following sample code shows how to bind a program to a division:

curl --request POST  
     --url <https://api-sandbox.pismolabs.io/corporate/corporate/hierarchies/{hierarchyId}/levels/{levelId}/divisions/{divisionId}/program-set>  
     --header 'Accept: application/json'  
     --header 'Content-Type: application/json'  
     --data '{  
     "program_ids": [  
          1214,  
          1215,  
          1225  
     ]  
}'

If successful, the call returns a response similar to this:

{  
    204 no content  
}

Step 8 – Set up processing codes

A processing code is a numeric identifier that you can use to modify how Pismo handles certain transactions. Pismo provides a number of standard, predefined processing codes, but you can also add and configure your own codes.

Each code is associated with one or more transaction types. The standard processing code 220035 (CASHIN TRANSFER), for example, is associated with one transaction type 92000040 (CASHIN TRANSFER). The standard code 220037, however, is associated with three transaction types:

• 92000042 – CASHOUT TRANSFER
• 801 - CASHOUT WIRE TRANSFER FEE
• 412 - VALUE ADDED TAXES

See Processing codes and transaction types for more information and Payments configurations for a step by step guide.

Step 9 – Create flex controls using processing codes

You create flex controls using the Create account flex control endpoint. You can use the processing code 220037, for example, to create a flex control that limits the amount of money an account can move in one cashout transaction:

curl --request POST  
     --url <https://api-sandbox.pismolabs.io/rules/v1/accounts/{account-id}/flex-controls>  
     --header 'Accept: application/json'  
     --header 'Content-Type: application/json'  
     --data '  
{  
     "processing_codes": [  
          "220037"  
     ],  
     "conditions": [  
          {  
               "attribute": "amount",  
               "operator": "lt",  
               "value": "1000"  
          }  
     ],  
     "active": true,  
     "type": "spending_limit",  
     "name": "1k Cashout limit",  
     "deny_code": "CASHOUT_LIMIT_1K",  
     "currency_code": "GBP",  
     "max_limit": 1000  
}  
'

Step 10 – Configure accounting

The Pismo platform provides tools to keep track of business and financial transactions for accounting purposes. There are five accounting elements in the Pismo platform:

• Accounting scripts – Accounting scripts determine what accounting entries the Pismo platform generates when an accounting event occurs. An accounting script, for example, should generate entries that show what debit account and credit account into which an amount flows. An organization can have one or more accounting scripts.
• Accounting events – The Pismo platform issues accounting events that impact your organization's records. Your accounting scripts determine the impact of each accounting event.
• Accounting entries – Accounting entries are the final product of the accounting events processing. These entries affect your organization's accounting records.
• Accounting accounts – Accounting accounts are the accounts from your organization's balance sheet. They keep a record of the funds in your general ledger. Each accounting script has two accounting accounts. One records your organization's assets, and the other records its liabilities.
• Cost centers (optional) – Cost centers are entities that cost an organization money or resources. Examples of a cost center are a human resources department or a revenue center.

You create accounting accounts and then configure accounting scripts to generate accounting entries based on accounting events.

Loans or credits extended by the bank to customers are considered the bank's assets, as customers are obligated to repay these amounts, often with interest. Conversely, deposits held by the bank are viewed as liabilities, as the bank is responsible for returning the customer's funds upon request.

If no interest is taken and no fee is charged for a transaction, the resulting balance of the operation, from an accounting standpoint, is zero for both assets and liabilities.

Cost centers are subdivisions of the balance sheet, but with a more operational view as opposed to the pure accounting view.

Step 11 – Create transaction account

You use the Create corporate account endpoint to create a transaction account. This endpoint requires you to specify both a division_id and a program_id. The program specified by program_id must be bound to the division specified by division_id. See Bind your programs to divisions for more information.

🚧

You can only use the Create account application endpoint to create non-transaction banking accounts. Since transaction accounts must be associated with divisions, you need a special endpoint to create them.

Step 12 – Retrieve account information

You can retrieve information about a transaction account using the Get account info endpoint.

Balance types

The Get account info endpoint returns several balance types:

• available_balance – Amount available for withdrawal (amount not earmarked)
• book_balance – Total amount in account (available_balance + earmarked_balance)
• earmarked_balance – Amount earmarked for settlement

If an action has an impact on the available_balance, the core platform domain issues a change_available event. For example:

 {
	"arrival_epoch": 1667587104040,
	"event_id": "bcaa68bb-6159-4485-908d-f52d68570230",
	"timestamp": "2022-11-04T18:38:23.916776539Z",
	"domain": "availables",
	"event_type": "change_available",
	"schema_version": 1,
	"org_id": "TN-bc205a0c-11b8-4505-8668-f24a2af5123e",
	"cid": "85cc8e81-d7f9-90c8-ba7e-ca0eccfa74d7",
	"data": {
		"id": "e9f05dc8-2d6f-4623-906b-0acfc53467fb",
		"available_credit_limit": 632,
		"available_withdraw_limit": 0,
		"available_installment_limit": 0,
		"available_savings_account_limit": 0,
		"amount": 18,
		"amount_consider": 18,
		"tracking_id": "286186e4-2d9b-4fe4-a90b-e612-Cashout-debit",
		"account_id": 104436406,
		"org_id": "TN-bc205a0c-11b8-4505-8668-f24a2af5123e",
		"operation_type": "DEBIT",
		"updated_at": "2022-11-04 15:38:23.898503",
		"available_update_datetime": "2022-11-04T18:38:23Z",
		"caller": "p2ptransactions-api"
	}
}

The amount property shows that the value of the account balance increased by 18. (A positive amount indicates an increase.) The available_credit_limit is the credit limit for the account.

This transaction causes the transaction banking domain to issue a balance_change event. The balances communicated by this event are the resulting balances after the transaction impacted them. For example:

{
	"event_id": "bcaa68bb-6159-4485-908d-f52d68570230",
	"timestamp": "2022-11-04T18:38:23.916776539Z",
	"domain": "account_balances",
	"event_type": "balance_change",
	"schema_version": 1,
	"org_id": "TN-bc205a0c-11b8-4505-8668-f24a2af5123e",
	"cid": "85cc8e81-d7f9-90c8-ba7e-ca0eccfa74d7",
	"data": {
    "id": "e9f05dc8-2d6f-4485-908d-f52d68570230",
    "account_id": 104436406,
    "operation_type": "DEBIT",
    "operation_amount": 18,
    "uncleared_funds": 0,
    "book_balance": 632,
    "earmarked_balance": 0,
    "available_balance": 0,
    "change_available_event_id": "e9f05dc8-2d6f-4623-906b-0acfc53467fb",	
    "tracking_id": "286186e4-2d9b-4fe4-a90b-e612-Cashout-debit",
    "balance_update_datetime": "2022-11-04T18:38:23Z"
  }
}

Step 13 – Perform operations

📘

Endpoints Initiate a payment and Schedule transactions have the following optional arguments that are specific to transaction banking:

• allow_suspense_postingboolean
  Defines if this transaction should be posted in suspense, in case it’s denied for any reason, such as lack of balance, account status, invalid currency, etc.
• skip_account_date_validationboolean
  Defines if the transaction should be posted regardless of date validations. This parameter allows transactions to be back-dated beyond the account creation date and time.

📘

Endpoint Create earmark has the following optional argument that is specific to transaction banking:

• expiry_datetimedate-time
  ISO 8601 date/time for earmark release.

You can use the following operations to move funds between accounts.

Cash-in

Use the Initiate a payment endpoint to perform a cash-in operation. The following code shows how to perform a cash-in of 320 GBP on 2022-02-09.

🚧

Currently, the maximum number of days supported for backdating is seven (7).

curl --location --request POST 'https://api-sandbox.pismolabs.io/corporate/payments' \
--header 'x-tenant: {tenantId}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"descriptor": "Cash-in payment",
	"from": [
		{
			"custom_info": {
				"type": "CASHIN"
			}
		}
	],
	"to": [
		{
			"amount": 320,
			"currency": "GBP",
			"account": {
				"id": {accountId}
			}
		}
	],
    "payment_datetime": "2022-02-09T10:00:00Z",
}'

Cash-out

Use the Initiate a payment endpoint to perform a cash-out operation. The following code shows how to perform a cash-out of 400 GBP on 2022-02-07:

curl --location --request POST 'https://api-sandbox.pismolabs.io/corporate/payments' \
--header 'x-tenant: {tenantId}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"descriptor": "Cash-out payment",
	"from": [
		{
			"amount": 400,
			"currency": "GBP",
			"account": {
				"id": {accountId}
			}
		}
	],
	"to": [
		{
			"custom_info": {
				"type": "CASHOUT"
			}
		}
	],
    "payment_datetime": "2022-02-07T10:00:00Z",
}'

P2P transfer

Use the Initiate a payment endpoint to perform a Pismo platform account to Pismo platform account (P2P) operation. The following code shows how to perform a P2P transfer of 100 GBP between two accounts on 2022-02-08:

curl --location --request POST 'https://api-sandbox.pismolabs.io/corporate/payments' \
--header 'x-tenant: {tenantId}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"descriptor": "P2P payment",
	"from": [
		{
			"amount": 100,
			"currency": "GBP",
			"account": {
				"id": {accountId1}
			}
		}
	],
  "to": [
    {
    	"amount": 100,
			"currency": "GBP",
      "account": {
      	"id": {accountId2}
      }
    }
  ],
    "payment_datetime": "2022-02-08T10:00:00Z",
}'

Schedule a payment

Use the Scheduled payment endpoint to schedule a payment to occur at a future date and time. The endpoint performs validations to ensure that the scheduled date is in the future and does not occur on a holiday. The following code shows how to schedule a payment of 200 GBP for payment on 2024-04-10:

curl --request POST 'https://api-sandbox.pismolabs.io/corporate/payments/schedules' 
-H 'x-tenant: <organization ID>' -H 'Content-Type: application/json' 
-d '{
    "descriptor": "P2P payment",
    "from": [
        {
            "custom_info": {
                "type": "CASHIN",
                "external_id": "e731652e-87d5-4acb-8f32-cb5cfd095a12"
            }
        }
    ],
    "to": [
        {
            "amount": 200,
            "currency": "GBP",
            "account": {
                "id": {accountId}
            }
        }
    ],
    "payment_datetime": "2024-04-10T15:00:00Z"
}'

See Scheduled payments for more information.

Earmark funds

Use the Create earmark endpoint to earmark funds for a future cash-out (usually a payment). The difference between scheduling a payment and earmarking funds for a payment is that earmarking the funds holds them in reserve, so that they cannot be withdrawn from the account before the payment.

The following code shows how to earmark 50 USD for payment on 2024-04-10:

curl --request POST \
     --url https://api-sandbox.pismolabs.io/corporate/earmarks \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "from": {
          "account": {
               "id": "102701621"
          },
          "amount": 50,
          "currency": "USD"
     },
     "to": {
          "custom_info": {
               "type": "Scheduled earmark",
               "external_id": "123ABC"
          }
     },
     "tracking_id": "ABC123",
     "descriptor": "Hold Funds",
     "expiry_datetime": "2024-04-10T15:00:00Z"
}
'

See Earmarking funds for more information.