Managing cash positions often involves blocking or releasing funds across thousands of accounts simultaneously—a scale that can overwhelm systems designed for single‑transaction API calls. To simplify this process, the Pismo platform provides a file‑based processing solution. You can upload UTF‑8 NDJSON files containing a specific operation type, such as RESTRICT_FUNDS, to execute multiple transactions in bulk. Each file is processed asynchronously, line by line, ensuring that a failure in one instruction does not halt the rest.

This diagram illustrates the step‑by‑step flow of file-based processing.

The diagram summarizes the process as follows.

1. Sign the plaintext bulk file.
2. Request an AES-256 key from Pismo using the encryption key endpoint.
3. Decrypt the JWE payload with your private key to retrieve aes_key and iv.
4. Encrypt the signed file using AES-256-CBC with the retrieved key and IV.
5. Upload the encrypted file to Pismo.

Send and process files for restrict funds

To facilitate file-based processing, the Pismo platform builds an extensible, AWS-based bulk-processing platform capable of ingesting and executing large file-driven workloads. Its plugin architecture allows new operational workflows to be added quickly. All capabilities available through the single-operation endpoint can be invoked through files that contain hundreds or thousands of instructions.

One of the solutions supported by file-based processing is restricted funds. Here are the endpoints.

• Create fund restriction
• Release restriction

💡

Notes

• Each line in the file is executed independently. A failure on one instruction does not halt the rest, and the response file lists both successes and errors.
• Files are UTF-8 NDJSON—a header line followed by one JSON object per operation, conforming to the prescribed schema.
• No in-flight tracking or cancellation. You can monitor progress through the output event/response file when your bulk file loading completes.
• This is a deferred validation upload, meaning the file is accepted on upload, but full transaction validation occurs later during asynchronous processing.
• Validation results are included in the output file once processing is complete.

By consolidating thousands of restrict and release requests into a handful of files, the Pismo platform reduces API traffic while maintaining fault isolation and horizontal scalability.

Prepare your input and output files

Before you upload your files to Pismo, you must prepare an input and output file according to these guidelines.

Input file

The Pismo platform processes file requests by reading a UTF-8 input file that begins with a single header line and is followed by numerous NDJSON lines, with each one describing an operation that follows the schema described in the Operation type JSON payload for restrict funds section.

Input file format

Name

Because you upload the file through an endpoint, the filename is irrelevant and does not appear in the output.

Header

Here is an example of a header file.

{
  "bulk_id": "TESTE-3-TRANSFER-20250905",
  "org_id": "TN-097d9c0e-0331-492a-93e2-95c8c2019fd1",
  "header_version": "1.0.0",
  "operation_type": "RESTRICT_FUNDS",
  "n_entries": 4
}

Operation type JSON payload for restrict funds

After the header object, add a JSON payload in which each row corresponds to the operation type you specified in the header. There are only two allowable operation types.

• RESTRICT_FUNDS: This operation specifies that each row in the file transfers the amount from the available balance to restricted funds.
• RELEASE_RESTRICTION: This operation specifies that each row in the file transfers the amount from restricted funds back to the available balance.

Input file example (RESTRICT_FUNDS)

{"bulk_id": "HOLD-CSIID-Uniqueid", "org_id": "<your_org_id>", "header_version": "1.0.0", "operation_type": "RESTRICT_FUNDS", "n_entries": 2}
{"external_account_id": "f94eb97c-43e2-4069-9720-5b08d17f03aa", "tracking_id": "f94eb97c-43e2-4069-9720-5b08d174510001", "restricted_funds_id": "8a4bfca4-d2e7-441a-8e5c-2dda797d0001", "hold_method": "FLEXIBLE", "amount": 1500.44, "soft_descriptor": "Hold for transaction processing", "metadata": {}}
{"external_account_id": "f94eb97c-43e2-4069-9720-5b08d17f03ab", "tracking_id": "f94eb97c-43e2-4069-9720-5b08d174510002", "restricted_funds_id": "8a4bfca4-d2e7-441a-8e5c-2dda797d0002", "hold_method": "FLEXIBLE", "amount": 1500.01, "soft_descriptor": "Hold for transaction processing", "metadata": {}}

Input file example (RELEASE_RESTRICTION)

{"bulk_id": "RELEASE-CSIID-Uniqueid", "org_id": "TN-097d9c0e-0331-492a-93e2-95c8c2019fd1", "header_version": "1.0.0", "operation_type": "RELEASE_RESTRICTION", "n_entries": 2}
{"external_account_id": "f94eb97c-43e2-4069-9720-5b08d17f03aa", "tracking_id": "f94eb97c-43e2-4069-9720-5b08d1745130001", "restricted_funds_id": "8a4bfca4-d2e7-441a-8e5c-2dda797d0001", "hold_method": "STRICT", "amount": 1500.44, "soft_descriptor": "Release for transaction processing", "metadata": {}}
{"external_account_id": "f94eb97c-43e2-4069-9720-5b08d17f03ab", "tracking_id": "f94eb97c-43e2-4069-9720-5b08d1745130002", "restricted_funds_id": "8a4bfca4-d2e7-441a-8e5c-2dda797d0002", "hold_method": "STRICT", "amount": 1500.01, "soft_descriptor": "Release for transaction processing", "metadata": {}}

Output file

An output file contains the results of file‑based processing. After the Pismo platform processes your input file, it generates an output file detailing the outcome of each transaction. This file is then stored in the Amazon S3 bucket you specified.

Here are the details of output file format.

• Output files follow this naming convention: {creation-datetime}-{bulk-id}-out.original.
• creation-datetime: This is a UTC timestamp that conforms to the format of YYYY-MM-DD-hh-mm-ss.
• bulk-id: An alphanumeric string (letters, digits, and hyphens only) that represents your file-based processing operation. The ID cannot exceed 50 characters.

The complete file name does not exceed 120 characters. This table summarizes the output file format.

Sample responses

When the upload is complete and the operation is processed successfully, a 201 Created response is returned. Refer to the endpoints for more details.

{
  "response_status": 201,
  "tracking_id": "9d15bfd1-5db9-4e96-b846-8d8707454430",
  "cid": "ex-cid-1",
  "data": {
    "restricted_funds_id": "4a4060d5-3649-46e8-8d64-93949b212918",
    "amount”: 1932.22,
    "applied_amount": 1932.22,
    "status": "SUCCEEDED"
  }
}

Otherwise, a 4xx error is returned indicating the reason for the failure.

{
  "response_status": 4xx,
  "tracking_id": "9d15bfd1-5db9-4e96-b846-8d8707454430",
  "cid": "ex-cid-1",
  "data": {
    "restricted_funds_id": "4a4060d5-3649-46e8-8d64-93949b212918",
    "amount”: 1932.22,
    "status": "FAILED"
  },
  "error": {
    "code": "AHF00##",
    "message": "The request attributes are different from the previous hold funds operation"
  }
}

Once you finish preparing the input and output files, proceed to:

1. Create a public key and a private key
2. Prepare a signature envelope file
3. Sign the bulk file
4. Verify signature
5. Encrypt the bulk file

The detailed steps are described in File signature and encryption.

Error codes

Refer to Create fund restriction for error code details.

File retention policy

To ensure sustainable cost management and secure file handling, the Pismo platform implements these file retention rules.

1. First 30 days: Files remain in the input and output buckets.
2. After 30 days: Files are migrated to a storage class with longer recovery times.
3. After 365 days: Files are migrated again to a storage class that requires at least 12 hours to recover.

It's best to implement a policy to delete files from long‑term storage once they are no longer needed.