The earmark feature enables you to set aside funds for some purpose. An account holder can create an earmark to schedule a cash-out (usually a payment), holding needed funds in reserve until a scheduled date and time. At the specified time, an automatic process releases the earmarked funds and settles the cash-out.

Organizations can earmark funds for any purpose. Setting no release date or time sets funds aside in perpetuity. An organization might want to do this, for example, to keep some money in an account in reserve for emergencies.

Earmarks leverage the Hold funds feature of the Pismo core platform, but for the specific purpose of corporate banking. To get information about current and historical earmarks, use List earmarks. To get information about a specific earmark, use Get earmark and provide the earmark_id.

The earmarks feature offers three different actions:

Create earmark holds needed funds in reserve until a specified date and time for release. The amount to earmark must be available in the client account.
Update scheduled earmark changes the value of an earmark, increasing or decreasing the value, and the release date or time. The updated amount must be available in the client account. Decreasing the earmark amount reduces the held funds, making them available for other purposes.
Cancel an earmark removes an earmark associated with an account. This releases held funds and invalidates the scheduled earmark.

Examples of earmark actions

Create earmark

You can set aside a certain amount of funds using the Create earmark endpoint. Once an earmark is created, the funds are set aside for release at a specified date and time, or if a release date is not specified, in perpetuity. This endpoint requires an account-specific access token, acquired by calling the Get OpenID access token endpoint with an external account ID.

Find below a sample of a request to create an earmark.

POST /corporate/v1/earmarks

{
    "earmark_id": "604cd837-8bfc-4423-b785-36448f3563b7",
    "account_id": 250318,
    "external_account_id": "61a05298-7579-4ff8-ac32-3f5eeef632e7",
    "release_datetime": "2023-06-20T16:09:13.121Z",
    "amount": 10,
    "balance": 10,
    "description": "string",
    "internal_operations": [
        {
            "type": "HOLD_FUNDS",
            "tracking_id": "83b31d6e-b714-cd00-7b1e-87f1583faa85",
            "processing_code": "219248",
            "amount": 10,
            "created_at": "2023-06-19T16:09:13.291946274Z"
        }
    ]
}

There are several things unique to earmarks to note here.

earmark_id Every earmark has an earmark ID that you can use to view, update, or cancel it. You can specify the earmark ID by populating the earmark_id field when you create the earmark. If you don't supply a value for this field, the Pismo platform generates one automatically and returns it in the request result.
external_account_id The required ‘external_account_id’ is generated when you use the Create corporate account endpoint to create a corporate account. The code below shows the result of running this endpoint, showing both the standard Pismo account ID and the external account ID.

{
    "account_id": 250318,
    "external_account_id": "61a05298-7579-4ff8-ac32-3f5eeef632e7",
    "program_id": 16
}

internal_operations The internal operations fields are generated or altered during the earmark creation/update/cancel processes. These fields enable Pismo to hold and release funds from and to the proper accounts. The internal operations fields enable interaction between the corporate banking earmarking endpoints and the Pismo core platform Payments API Hold funds endpoints.

Note the “type” above shows “HOLD FUNDS,” which indicates that this earmark has held funds currently. Other options for “type” include these:

"type": "INCREASE", "type": "DECREASE", "type": "RELEASE_FUNDS",

As the names indicate, “INCREASE” means the earmark has raised the amount of funds held. “DECREASE” means the opposite, that the earmark has lowered the amount of funds held. ‘RELEASE_FUNDS” means that the earmark has reached its date and time release point and transferred the funds appropriately.

Modify earmark

The Update scheduled earmark endpoint enables you to modify an existing earmark. The following sample code shows the result of updating an earmark’s amount from $10 to $20. Note that the internal_operations object shows exactly how the earmark was affected by the request.

PATCH /corporate/v1/earmarks/{earmarkId}

{
    "earmark_id": "e894e8d2-c788-44ad-9440-7320e9b7ee45",
    "account_id": 250318,
    "external_account_id": "61a05298-7579-4ff8-ac32-3f5eeef632e7",
    "release_datetime": "2023-06-02T20:24:43.786Z",
    "amount": 20,
    "balance": 20,
    "description": "string",
    "internal_operations": [
        {
            "type": "INCREASE",
            "tracking_id": "e8202372-a92b-4ae4-a8a4-e722fd0d3367",
            "processing_code": "219248",
            "amount": 10,
            "created_at": "2023-06-01T21:11:02.002501187Z"
        },
        {
            "type": "HOLD_FUNDS",
            "tracking_id": "9b61daac-6125-e25e-8b66-4778d03be920",
            "processing_code": "219248",
            "amount": 10,
            "created_at": "2023-06-01T20:24:43.979438613Z"
        }
    ]
}

Leaving the release_datetime field blank in the Request body makes no change to the currently active earmark release date and time.

Pismo earmarks enable organizations to react to changing circumstances fluidly and rapidly. This helps you address those scenarios where you ‘thought’ you had the right amount of funds set aside to handle a payment but added expenses require a change.

When you initially create an earmark, you can choose not to insert a release date and time. This sets the earmarked funds aside indefinitely, until you choose to release them. Use the Update scheduled earmark endpoint to change an indefinite release date and time to a definite one.

Cancel earmark

If an earmark becomes irrelevant or funds set aside need to be accessed for more pressing needs, you can remove the earmark using Cancel an earmark. You need the earmarkId, but nothing else. Running the endpoint successfully generates a 204 No Content message, showing no remaining earmark for that earmarkId.

The following sample code shows the result of canceling a $20 earmark. Note that the balance has changed from 20 to 0.

DELETE /corporate/v1/earmarks/{earmarkId}

{
    "earmark_id": "e894e8d2-c788-44ad-9440-7320e9b7ee45",
    "account_id": 250318,
    "external_account_id": "61a05298-7579-4ff8-ac32-3f5eeef632e7",
    "release_datetime": "2023-06-02T20:24:43.786Z",
    "amount": 20,
    "balance": 0,
    "description": "Client X",
    "internal_operations": [
        {
            "type": "RELEASE_FUNDS",
            "tracking_id": "b065adcc-6af4-c513-e76c-47088265dc8c",
            "processing_code": "219251",
            "amount": 20,
            "created_at": "2023-06-01T21:36:25.817205064Z"
        },
        {
            "type": "HOLD_FUNDS",
            "tracking_id": "9b61daac-6125-e25e-8b66-4778d03be920",
            "processing_code": "219248",
            "amount": 10,
            "created_at": "2023-06-01T20:24:43.979438613Z"
        },
        {
            "type": "INCREASE",
            "tracking_id": "e8202372-a92b-4ae4-a8a4-e722fd0d3367",
            "processing_code": "219248",
            "amount": 10,
            "created_at": "2023-06-01T21:11:02.002501187Z"
        }
    ]
}

Accessing earmark information

Two endpoints enable you to review earmarks:

List earmarks
Get earmark

List earmarks

List earmarks retrieves all the earmarks for an organization, including those that have already been executed and deleted.

The following is an example of the information returned by the List earmarks endpoint.

GET /corporate/v1/earmarks

{
    "earmarks": [
        {
            "earmark_id": "8b9e91d3-fd40-44e0-8c04-751a74c3b946",
            "account_id": 250318,
            "external_account_id": "61a05298-7579-4ff8-ac32-3f5eeef632e7",
            "release_datetime": "2023-06-02T14:20:25.106Z",
            "amount": 10,
            "balance": 0,
            "description": "Client X",
            "internal_operations": [
                {
                    "type": "HOLD_FUNDS",
                    "tracking_id": "474b7d5a-9835-e577-058c-9cc2125bd185",
                    "processing_code": "219248",
                    "amount": 10,
                    "created_at": "2023-06-01T16:37:40.463488702Z"
                },
                {
                    "type": "RELEASE_FUNDS",
                    "tracking_id": "e515f589-bf38-9c5c-70f2-8f4f7f03c9cd",
                    "processing_code": "219251",
                    "amount": 10,
                    "created_at": "2023-06-01T16:38:15.583657716Z"
                }
            ]
        },
        {
            "earmark_id": "e894e8d2-c788-44ad-9440-7320e9b7ee45",
            "account_id": 250318,
            "external_account_id": "61a05298-7579-4ff8-ac32-3f5eeef632e7",
            "release_datetime": "2023-06-02T14:20:25.106Z",
            "amount": 10,
            "balance": 10,
            "description": "Client X",
            "internal_operations": [
                {
                    "type": "HOLD_FUNDS",
                    "tracking_id": "9b61daac-6125-e25e-8b66-4778d03be920",
                    "processing_code": "219248",
                    "amount": 10,
                    "created_at": "2023-06-01T20:24:43.979438613Z"
                }
            ]
        },
        {
            "earmark_id": "f9784be5-addf-4ef0-ae4b-2322118b40e6",
            "account_id": 250318,
            "external_account_id": "61a05298-7579-4ff8-ac32-3f5eeef632e7",
            "release_datetime": "2023-06-02T14:20:25.106Z",
            "amount": 10,
            "balance": 0,
            "description": "Client X",
            "internal_operations": [
                {
                    "type": "HOLD_FUNDS",
                    "tracking_id": "019341de-5c73-04c3-1cae-8229228badec",
                    "processing_code": "219248",
                    "amount": 10,
                    "created_at": "2023-06-01T14:20:25.229144451Z"
                },
                {
                    "type": "RELEASE_FUNDS",
                    "tracking_id": "860a9fa2-0566-e7fa-5c6a-a8203f8a7526",
                    "processing_code": "219251",
                    "amount": 10,
                    "created_at": "2023-06-01T16:36:29.558453818Z"
                }
            ]
        }
    ],
    "pagination": {
        "limit": 10,
        "cursor": ""
    }
}

Get an earmark

The Get earmark endpoint enables you to access information about an earmark based on the earmark ID. The following shows the output of Get earmark for the account earmarked in the “Create earmark” section previously in this document.

GET /corporate/v1/earmarks{earmarkId}

{
    "earmark_id": "8b9e91d3-fd40-44e0-8c04-751a74c3b946",
    "account_id": 250318,
    "external_account_id": "61a05298-7579-4ff8-ac32-3f5eeef632e7",
    "release_datetime": "2023-06-02T16:37:40.372Z",
    "amount": 10,
    "balance": 10,
    "description": "string",
    "internal_operations": [
        {
            "type": "HOLD_FUNDS",
            "tracking_id": "474b7d5a-9835-e577-058c-9cc2125bd185",
            "processing_code": "219248",
            "amount": 10,
            "created_at": "2023-06-01T16:37:40.463488702Z"
        },
        {
            "type": "RELEASE_FUNDS",
            "tracking_id": "e515f589-bf38-9c5c-70f2-8f4f7f03c9cd",
            "processing_code": "219251",
            "amount": 10,
            "created_at": "2023-06-01T16:38:15.583657716Z"
        }
    ]
}