# Request bulk settlement
This endpoint triggers the clearing of future value-dated payments and check-release operations in bulk.
A future value dated payment is a banking transaction that is scheduled to occur on a future date, such as a prepayment or normal payment. The bank is instructed to send the payment on a specific date, which can be the next day or later. When a payment is scheduled for a future date, the funds remain in the payer's account, continuing to accrue interest until the payment is settled on the scheduled date.
A check release is the process that moves funds from an uncleared or held state into the customer’s available balance. After a check is deposited, some or all of its amount remains pending until a scheduled release. When the check is released, the pending funds are applied, and the account balances are updated so that the amount becomes fully available for use.
NOTE: You can call this endpoint once with the same parameters, per division, settlement date, and operation type. If the process fails, you can retry up to 9 times per division, per business day.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"title": "Banking - Transaction banking",
"version": "0.9.0",
"description": "Transaction banking API",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://sandbox.pismolabs.io",
"description": "Sandbox API server for testing"
}
],
"security": [
{
"BearerAuth": []
}
],
"tags": [
{
"name": "Bulk settlement",
"description": "Bulk settlement related endpoints"
}
],
"components": {
"schemas": {
"BulkID": {
"type": "string",
"description": "Bulk settlement request ID provided by the requester.",
"maximum": 60,
"pattern": "^[a-zA-Z0-9-]+$",
"example": "0a50c88a-ade8-4bcc-a639-9a0b0f11e244"
},
"BulkSettlementRequest": {
"description": "Bulk settlement request",
"type": "object",
"required": [
"operation_type",
"settlement_date",
"division_code",
"bulk_id"
],
"properties": {
"operation_type": {
"$ref": "#/components/schemas/OperationType"
},
"settlement_date": {
"$ref": "#/components/schemas/SettlementDate"
},
"division_code": {
"$ref": "#/components/schemas/DivisionCode2"
},
"bulk_id": {
"$ref": "#/components/schemas/BulkID"
}
}
},
"DivisionCode2": {
"type": "string",
"description": "Division code registered in the [Create division](https://developers.pismo.io/pismo-docs/reference/post-division-v2) endpoint.",
"maximum": 36,
"example": "US"
},
"ErrorCode": {
"description": "Error code\n`minLength: 1`\n`maxLength: 12`\n",
"type": "string",
"minLength": 1,
"maxLength": 12,
"example": "WPMT0017"
},
"ErrorMessage": {
"description": "Error message\n`minLength: 1`\n`maxLength: 1000`\n",
"type": "string",
"minLength": 1,
"maxLength": 1000,
"example": "Invalid JSON payload received: Error unmarshalling request"
},
"ErrorResponse": {
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/ErrorCode"
},
"message": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
},
"OperationType": {
"type": "string",
"description": "Operation type.
\nThe maximum number of times you can call the Request bulk settlement endpoint per division per business day is 10, regardless of the operation type. For example, you can retry up to 9 times if the first call fails.\n",
"enum": [
"future-dated",
"float-payment",
"check-release"
],
"example": "float-payment"
},
"SettlementDate": {
"type": "string",
"format": "date",
"description": "Future date on which the `float_amount` is settled. Corresponds to the cycle closing date relative to the payment date.
\nNotes:\n - The settlement date is in ISO 8601 format.\n - It's similar to the `business_date` attribute for regular payment operations.\n",
"example": "2023-03-09"
}
},
"responses": {
"401Unauthorized": {
"description": "Access token is missing or invalid"
},
"403Forbidden": {
"description": "The request has been lost"
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/corporate/v1/bulk-settlement": {
"post": {
"summary": "Request bulk settlement",
"description": "This endpoint triggers the clearing of future value-dated payments and check-release operations in bulk.
\nA future value dated payment is a banking transaction that is scheduled to occur on a future date, such as a prepayment or normal payment. The bank is instructed to send the payment on a specific date, which can be the next day or later. When a payment is scheduled for a future date, the funds remain in the payer's account, continuing to accrue interest until the payment is settled on the scheduled date.\n\nA check release is the process that moves funds from an uncleared or held state into the customer’s available balance. After a check is deposited, some or all of its amount remains pending until a scheduled release. When the check is released, the pending funds are applied, and the account balances are updated so that the amount becomes fully available for use.\n\nNOTE: You can call this endpoint once with the same parameters, per division, settlement date, and operation type. If the process fails, you can retry up to 9 times per division, per business day.\n",
"operationId": "post-bulk-settlement",
"tags": [
"Bulk settlement"
],
"parameters": [],
"requestBody": {
"description": "Bulk settlement request body",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkSettlementRequest"
},
"examples": {
"Request bulk settlement": {
"value": {
"operation_type": "float-payment",
"settlement_date": "2024-07-03",
"bulk_id": "74f8e8df",
"division_code": "74f8e8df-2c2b-412f-8d35-abdf17d896ec"
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"description": "A Bad Request validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"invalid JSON payload": {
"value": {
"code": "WSTM0001",
"message": "Invalid JSON payload received: Error unmarshalling request"
}
},
"bulk id required": {
"value": {
"code": "WSTM0002",
"message": "bulk_id is a required field"
}
},
"bulk id max length": {
"value": {
"code": "WSTM0002",
"message": "bulk_id must be a maximum of 60 characters in length"
}
},
"bulk id invalid characters": {
"value": {
"code": "WSTM0002",
"message": "bulk_id contains invalid characters: [characters]"
}
},
"operation type required": {
"value": {
"code": "WSTM0002",
"message": "operation_type is a required field"
}
},
"operation type invalid": {
"value": {
"code": "WSTM0002",
"message": "operation_type must be one of [future-dated float-payment]"
}
},
"settlement date required": {
"value": {
"code": "WSTM0002",
"message": "settlement_date is a required field"
}
},
"settlement date max length": {
"value": {
"code": "WSTM0002",
"message": "settlement_date must be a maximum of 10 characters in length"
}
},
"settlement date wrong format": {
"value": {
"code": "WSTM0002",
"message": "settlement_date 07/15/2024 should be formatted as yyyy-mm-dd and be a valid date"
}
},
"division code required": {
"value": {
"code": "WSTM0002",
"message": "division_code is a required field"
}
},
"division code max length": {
"value": {
"code": "WSTM0002",
"message": "division_code must be a maximum of 36 characters in length"
}
},
"settlement date in the future": {
"value": {
"code": "WSTM0003",
"message": "Settlement date cannot be a future date"
}
},
"settlement date before allowed time": {
"value": {
"code": "WSTM0004",
"message": "Current date can be the same as settlement date only after 00:15 in the division's time zone"
}
},
"division not found": {
"value": {
"code": "WSTM0005",
"message": "Division not found"
}
},
"settlement date invalid": {
"value": {
"code": "WSTM0006",
"message": "Settlement date must be a valid date in ISO 8601 format"
}
},
"Settlement not yet allowed": {
"value": {
"code": "WSTM0010",
"message": "Bulk settlement for the current date is allowed only after {hour}:{minute}, according to the division’s time zone"
}
},
"administrative division is misconfigured": {
"value": {
"code": "WSTM0011",
"message": "Administrative division is misconfigured"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"duplicated parameters": {
"value": {
"code": "WSTM0007",
"message": "Bulk settlement already posted with parameters division code [division], settlement date [date] and type [type]"
}
},
"duplicated bulk id": {
"value": {
"code": "WSTM0009",
"message": "Bulk id [id] is already in use"
}
}
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"posts limit": {
"value": {
"code": "WSTM0008",
"message": "You cannot post more than 10 daily bulk settlements"
}
}
}
}
}
},
"500": {
"description": "Internal Errors",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Generic internal error": {
"value": {
"code": "ECMN9999",
"message": "Internal error"
}
}
}
}
}
}
}
}
}
}
}
```