Corporate banking launch reference

Introduction

To launch Corporate Demand Deposit Accounts (DDA) 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 Corporate DDA at Pismo:

ComponentSingle (S) or Multiple (M)*Required**Creation method
Organization (Org)SYPismo creates the Org based on your specifications
HierarchyMYAPI
DivisionMYAPI
HolidayMNAPI
Account schema validationMNAPI
ProgramMYPismo Console / API
Processing codeMYAPI

* 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. For example, it's possible for a client to have only one Program, 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:

Org ElementDescriptionExample
Official nameYour organization or company's legal nameYour Org LLC
Organization nameYour organization's preferred nameChange the World
Document numberYour organization's government documentation number08350504000143
AddressStreet addressChurchill Street
NumberStreet address number100
Complementary addressComplementary information - unit, floor, etc.Conj. 123
NeighborhoodNeighborhoods - some countries use assigned neighborhoods in addressCanary Wharf
ZipcodeCountry postal codeE145AC
CityCityLondon
StateState/Province/RegionEngland
CountryCountryUnited Kingdom
Legal proxy nameYour organization's legal representativeYour Pismo Org LTDA
Legal proxy documentYour organization's legal representative document123456
EmailEmail[email protected]
Currency numeric codeISO 4217 currency numeric code, e.g., 986 (Brazilian real)826
TimezoneTimezone nameEurope/London

When the implementation team creates your Org, it is assigned an identifier that is referred to as either an Org ID or a Tenant ID. It 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 Get org info endpoint to retrieve the information for your organization.

See Organization (Org) setup for more info.

Step 2 – Set up a hierarchy

For corporate 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 like 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” which 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 corporate 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 this:

{  
  "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:

ParameterDescriptionType
hierarchyIdHierarchy IDString
levelIdLevel IDString

It also takes the following body parameters:

ParameterDescriptionTypeRequired
idUnique identifier for the division. A unique value is automatically generated by the Pismo platform.StringNM
parent_idParent level division ID. If you don't include a parent ID, then the platform assumes the division doesn't have a parent, and it won't inherit the features of a parent. This should only be the case for divisions in the topmost level. It's your responsibility to ensure that all divisions that are not in the topmost level are assigned parent IDs.StringN
nameDivision nameStringY
descriptionDivision descriptionStringN

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. For example, brick and mortar branches 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:

ParameterDescriptionType
hierarchyIdHierarchy IDString
levelIdLevel IDString
divisionIdDivision IDString

It takes the following body parameters:*

ParameterDescriptionTypeRequired
holidaysAn array of objects.
Each object is defined
by the next 3 rows:
ArrayN
holidays.dayThe day of the month on which the holiday takes placeIntegerY (for each holiday)
holidays.monthThe month in which the holiday takes placeIntegerY (for each holiday)
holidays.descriptionA name or description for the holidayStringN
program_idsThe IDs of the programs that the holiday applies to. If no IDS are provided, the holiday applies to all the programs in the division.Array of integersN

*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 --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 --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, you 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, you need to 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:

ParameterDescriptionType
hierarchyIdHierarchy IDString
levelIdLevel IDString
divisionIdDivision IDString

It takes the following body parameters:*

ParameterDescriptionTypeRequired
schemaAn array of schemas. Each schema is a JSON value pair in the form: [new Key]:[new Value]. See the code snippet below for an example. Since you can use this endpoint for other things besides assigning a schema, the schema field is not required.JSONN

*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:*

Field NameDescriptionField TypePossible ValuesRequired
nameA name for the programStringY
typeThe type of program. (This indicates the template that Pismo uses behind the scenes.) Examples:
- Current accounts
- Internal accounts
- Correspondent accounts
String- CURRENT ACCOUNTS

- INTERNAL ACCOUNTS

- CORRESPONDENT ACCOUNTS
Y
timezone Program timezoneStringY
currency_numeric_code Numeric code (ISO 4217) of the currency used by the program.StringY

*Fields not listed in the above table are not applicable to corporate 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 are telling 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:

ParameterDescriptionType
hierarchyIdHierarchy IDString
levelIdLevel IDString
divisionIdDivision IDString

It takes the following body parameter:*

ParameterDescriptionType
program_idsProgram IDsArray of strings

*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. For example, the standard processing code 220035 (CASHIN TRANSFER) 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.

Processing codeProcessing code descriptionAvailable Balance impactTransaction typeTransaction type description
219248HOLD FUNDSNEGATIVE7128HOLD FUNDS
219249HOLD FUNDS CANCELPOSITIVE92000046HOLD FUNDS CANCE
219250HOLD FUNDS UNDO CANCELNEGATIVE
219251RELEASE FUNDSPOSITIVE7129RELEASE FUNDS
219252RELEASE FUNDS CANCELNEGATIVE92000047RELEASE FUNDS CANCEL
219253RELEASE FUNDS UNDO CANCELPOSITIVE
220035CASHIN TRANSFERPOSITIVE92000040CASHIN TRANSFER
220036UNDO CASHIN TRANSFERNEGATIVE92000041UNDO CASHIN TRANSFER
220037CASHOUT TRANSFERNEGATIVE92000042

801

412
CASHOUT TRANSFER

CASHOUT WIRE TRANSFER FEE

VALUE ADDED TAXES
220038UNDO CASHOUT TRANSFERPOSITIVE92000043UNDO CASHOUT TRANSFER
220039CREDIT ADJUSTMENTPOSITIVE92000044CREDIT ADJUSTMENT
220040DEBIT ADJUSTMENTNEGATIVE92000045DEBIT ADJUSTMENT

Step 9 – Create flex controls using processing codes

You create flex controls using the Create account flex control endpoint. For example, you can use the processing code 220037 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. For example, it should generate entries that show what debit account and credit account an amount flows into. An organization can have one or more accounting scripts.
  • Accounting events – Events issued by the Pismo platform that impact your organization's records. Your account scripts determine the impact of each accounting event.
  • Accounting entries – The final product of the accounting events processing. These entries affect your organization's accounting records.
  • Accounting accounts – These 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) – Entities that cost an organization money or resources. For example, 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.

For the bank, providing credit to customers is a liability, so when a customer makes a purchase using a credit card, the accounting script credits the liabilities account for the amount of the purchase and debits the assets account.

Customer payments become assets for the bank, so when a customer makes a purchase using a debit card, the accounting script credits the assets account and debits the liabilities account.

If no interest is taken and no fee 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 corporate account

You use the Create corporate account endpoint to create a corporate 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-corporate accounts. Since corporate 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 corporate 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 corporate 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 corporate 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 Schedult earmark has the following optional argument that is specific to corporate 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 transactions 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 Schedule 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.