# Create check posting
Allow clients to post a check for a specified external account, with the option to settle the amount either immediately or in the future.
**NOTES**:
* This endpoint requires an account token - an access token encoded with an external account ID. Tokens can expire quickly, which can result in a `401 Unauthorized` message.
* This endpoint generates the following events:
- [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1)
- [Check posting status change](https://developers.pismo.io/events/docs/cash-management-check-status-change-1)
See [Data and reporting](doc:data-reporting-overview) for more information about events and setting up event notifications.
# 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": "Check posting",
"description": "Check posting endpoints"
}
],
"components": {
"schemas": {
"AmountValue": {
"type": "number",
"format": "float",
"description": "Amount value",
"exclusiveMinimum": false,
"minimum": 0,
"maximum": 100000000000000000,
"example": 1000.52
},
"BusinessDate": {
"type": "string",
"format": "date",
"description": "Specifying a `business_date` value impacts the account balance history.
\nNotes:\n - The business date is in ISO 8601 format.\n - The business date allows users to designate the balance history cycle in which a payment is posted.\n - You can specify a `business_date` within the current working day or up to one working day before or after.\n",
"example": "2023-03-09"
},
"CheckPostingResponse": {
"type": "object",
"description": "Check posting response object.",
"required": [
"check_id"
],
"properties": {
"check_id": {
"$ref": "#/components/schemas/CheckId"
}
}
},
"CheckPostingRequest": {
"type": "object",
"description": "Request body for posting a check transaction.",
"required": [
"check_id",
"check_amount",
"settlement_type",
"settlements"
],
"properties": {
"check_id": {
"$ref": "#/components/schemas/CheckId"
},
"check_amount": {
"$ref": "#/components/schemas/CheckAmount"
},
"settlement_type": {
"$ref": "#/components/schemas/CheckSettlementType"
},
"business_date": {
"$ref": "#/components/schemas/BusinessDate"
},
"description": {
"$ref": "#/components/schemas/CheckPostingDescription"
},
"settlements": {
"type": "array",
"description": "List of check settlements. Each settlement represents a portion of the check amount to be settled on a specific date, with an associated type and tracking identifier.",
"items": {
"$ref": "#/components/schemas/CheckSettlementRequestItem"
}
}
}
},
"Currency": {
"type": "string",
"description": "3-letter code in ISO 4217-compliant format for the currency used in the transaction.",
"maxLength": 3,
"minLength": 3,
"example": "USD"
},
"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"
}
}
},
"CheckId": {
"type": "string",
"description": "Check ID.",
"maxLength": 60,
"minLength": 1,
"pattern": "^[a-zA-Z0-9-]+$",
"example": "c462b2f3-55cc-42b4-ae9a-7614df3e8e72"
},
"CheckAmount": {
"type": "object",
"description": "Total check amount.",
"required": [
"value"
],
"properties": {
"value": {
"$ref": "#/components/schemas/AmountValue"
},
"currency": {
"$ref": "#/components/schemas/Currency"
}
}
},
"CheckPostingDescription": {
"type": "string",
"description": "A brief description about a check posting transaction.",
"maxLength": 100,
"example": "Check posting"
},
"CheckSettlementType": {
"type": "string",
"description": "Indicates when funds become available to the bank: `BEGINNING` or `END`.\n",
"enum": [
"BEGINNING",
"END"
],
"example": "END"
},
"SettlementType": {
"type": "string",
"description": "Settlement type. Indicates the nature of the settlement.",
"enum": [
"DEPOSIT",
"PENDING",
"HOLD"
],
"example": "HOLD"
},
"CheckSettlementDate": {
"type": "string",
"format": "date",
"description": "Settlement date in ISO 8601 format (yyyy-mm-dd).",
"example": "2025-01-06"
},
"CheckSettlementAmount": {
"type": "number",
"format": "decimal",
"description": "Amount to be settled in the specified operation.",
"example": 100
},
"CheckSettlementRequestItem": {
"type": "object",
"description": "Check settlement item representing a portion of the check amount to be settled on a specific date.",
"properties": {
"type": {
"$ref": "#/components/schemas/SettlementType"
},
"tracking_id": {
"$ref": "#/components/schemas/TrackingID"
},
"settlement_date": {
"$ref": "#/components/schemas/CheckSettlementDate"
},
"amount": {
"$ref": "#/components/schemas/CheckSettlementAmount"
}
},
"required": [
"type",
"tracking_id",
"settlement_date",
"amount"
]
},
"TrackingID": {
"type": "string",
"description": "A unique payment tracking number provided by the client. If an existing `tracking_id` already exists in the system, the API returns a `409` error.\n\nThis field is:\n - Unique within the Organization.\n - Immutable — It can't be updated.\n - Not recyclable — You can't reuse a `tracking_id`.\n",
"minLength": 1,
"maxLength": 43,
"example": "0a50c88a-ade8-4bcc-a639-9a0b0f11e244"
}
},
"responses": {
"403Forbidden": {
"description": "The request has been lost"
},
"500InternalServer": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Generic internal error": {
"value": {
"code": "ECMN9999",
"message": "Internal error"
}
}
}
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/corporate/v1/checks": {
"post": {
"summary": "Create check posting",
"description": "Allow clients to post a check for a specified external account, with the option to settle the amount either immediately or in the future.\n\n**NOTES**:\n * This endpoint requires an account token - an access token encoded with an external account ID. Tokens can expire quickly, which can result in a `401 Unauthorized` message.\n * This endpoint generates the following events:\n - [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1)\n - [Check posting status change](https://developers.pismo.io/events/docs/cash-management-check-status-change-1)\n\nSee [Data and reporting](https://developers.pismo.io/pismo-docs/docs/data-reporting-overview) for more information about events and setting up event notifications.",
"operationId": "corporate-post-v1-checks",
"tags": [
"Check posting"
],
"requestBody": {
"description": "Check posting request body",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckPostingRequest"
},
"examples": {
"Check posting request": {
"value": {
"check_id": "c462b2f3-55cc-42b4-ae9a-7614df3e8e72",
"check_amount": {
"value": 2000,
"currency": "USD"
},
"description": "Check posting",
"settlement_type": "BEGINNING",
"business_date": "2025-01-04",
"settlements": [
{
"type": "DEPOSIT",
"tracking_id": "73cc7fa5-79f1-4b85-9e13-124cc58c651f",
"settlement_date": "2025-01-05",
"amount": 100
},
{
"type": "HOLD",
"tracking_id": "9d7c898e-dd57-4ab4-bfe3-23a48d56851f",
"settlement_date": "2025-01-10",
"amount": 800
},
{
"type": "HOLD",
"tracking_id": "953109dc-e943-454a-95b6-4b15d2c5b31d",
"settlement_date": "2025-01-20",
"amount": 900
},
{
"type": "HOLD",
"tracking_id": "cd593acd-a056-42a1-aec8-3ae14d427a4d",
"settlement_date": "2025-01-30",
"amount": 200
}
]
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted. Returns the created check posting.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckPostingResponse"
},
"examples": {
"Check posting response": {
"value": {
"check_id": "c462b2f3-55cc-42b4-ae9a-7614df3e8e72"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Invalid json": {
"summary": "Invalid JSON payload",
"value": {
"code": "WCPT0001",
"message": "Invalid JSON payload received: Error unmarshalling request"
}
},
"check_id required": {
"summary": "check_id is a required field",
"value": {
"message": "check_id is a required field",
"code": "WCPT0002"
}
},
"check_id max": {
"summary": "check_id exceeds maximum length",
"value": {
"message": "check_id must be a maximum of 60 characters in length",
"code": "WCPT0002"
}
},
"settlements.tracking_id required": {
"summary": "tracking_id is a required field",
"value": {
"message": "tracking_id is a required field",
"code": "WCPT0002"
}
},
"settlements.tracking_id max": {
"summary": "tracking_id exceeds maximum length",
"value": {
"message": "tracking_id must be a maximum of 43 characters in length",
"code": "WCPT0002"
}
},
"check_amount required": {
"summary": "check_amount is a required field",
"value": {
"message": "check_amount is a required field",
"code": "WCPT0002"
}
},
"check_amount.value decimalGt": {
"summary": "value must be greater than 0",
"value": {
"message": "value must be greater than 0",
"code": "WCPT0002"
}
},
"check_amount.value decimalMax": {
"summary": "value exceeds the maximum allowed",
"value": {
"message": "value must be 100,000,000,000,000,000 or less",
"code": "WCPT0002"
}
},
"check_amount.value must match settlement values": {
"summary": "check_amount.value must be equal to the total sum of all settlement amounts",
"value": {
"message": "check_amount.value must be equal to the total sum of all settlement amounts",
"code": "WCPT0002"
}
},
"decimal places not compatible with currency": {
"summary": "decimal places is not compatible with the specified currency",
"value": {
"message": "The number of decimal places is not compatible with the specified currency",
"code": "WCPT0002"
}
},
"currency iso4217": {
"summary": "currency must be a valid ISO 4217 code",
"value": {
"message": "currency: invalid currency code",
"code": "WCPT0002"
}
},
"description max": {
"summary": "description exceeds maximum length",
"value": {
"message": "description must be a maximum of 100 characters in length",
"code": "WCPT0002"
}
},
"settlement_type required": {
"summary": "settlement_type is a required field",
"value": {
"message": "settlement_type is a required field",
"code": "WCPT0002"
}
},
"settlement_type oneof": {
"summary": "settlement_type must be BEGINNING or END",
"value": {
"message": "settlement_type must be one of [BEGINNING END]",
"code": "WCPT0002"
}
},
"settlement_type BEGINNING with invalid settlements": {
"summary": "settlement_type BEGINNING must contain settlements of type DEPOSIT or HOLD",
"value": {
"message": "settlement_type BEGINNING must contain up to one settlement of type DEPOSIT and up to three settlements of type HOLD",
"code": "WCPT0002"
}
},
"settlement_type END with invalid settlements": {
"summary": "settlement_type END must contain settlement of type PENDING",
"value": {
"message": "settlement_type END must contain only one settlement of type PENDING",
"code": "WCPT0002"
}
},
"settlements.settlement_date required": {
"summary": "settlement_date is a required field",
"value": {
"message": "settlement_date is a required field",
"code": "WCPT0002"
}
},
"settlements.settlement_date max": {
"summary": "settlement_date exceeds maximum length",
"value": {
"message": "settlement_date must be a maximum of 10 characters in length",
"code": "WCPT0002"
}
},
"settlements.settlement_date dateOnly": {
"summary": "settlement_date must be a valid date (yyyy-mm-dd)",
"value": {
"message": "settlement_date [date] should be formatted as yyyy-mm-dd and be a valid date",
"code": "WCPT0002"
}
},
"settlements.settlement_date must be future": {
"summary": "settlements.settlement_date must be in the future when settlements.type is HOLD or PENDING",
"value": {
"message": "settlements.settlement_date must be in the future when settlements.type is HOLD or PENDING",
"code": "WCPT0002"
}
},
"settlements.settlement_date must be today": {
"summary": "settlement_date must be today when settlements.type is DEPOSIT",
"value": {
"message": "settlement_date must be today when settlements.type is DEPOSIT",
"code": "WCPT0002"
}
},
"settlements.settlement_date exceeded": {
"summary": "Settlement date exceeds allowed range",
"value": {
"message": "settlements.settlement_date cannot surpass current_business_date by more than 30 calendar days when settlements.type is PENDING",
"code": "WCPT0002"
}
},
"settlements.settlement_date must be unique": {
"summary": "settlements.settlement_date must be unique",
"value": {
"message": "settlements.settlement_date must be unique",
"code": "WCMN0002"
}
},
"settlements.settlement_date cannot be before business_date": {
"summary": "settlements.settlement_date cannot be before the business_date",
"value": {
"message": "settlements.settlement_date cannot be before the business_date",
"code": "WCMN0002"
}
},
"settlements.type oneof": {
"summary": "type must be DEPOSIT, PENDING, or HOLD",
"value": {
"message": "type must be one of [DEPOSIT HOLD PENDING]",
"code": "WCPT0002"
}
},
"settlements.tracking_id must be unique\"": {
"value": {
"code": "WCPT0002",
"message": "settlements.tracking_id must be unique"
}
},
"Holiday": {
"summary": "Posting on a holiday",
"value": {
"code": "WCPT0006",
"message": "Cannot post checks on holiday"
}
},
"Weekend": {
"summary": "Posting on a weekend",
"value": {
"code": "WCPT0007",
"message": "Cannot post checks on a weekend"
}
},
"Invalid BusinessDate": {
"summary": "Invalid business date",
"value": {
"code": "WCPT0008",
"message": "Invalid business date for the current business day cycle"
}
},
"Invalid Processing Code": {
"summary": "Invalid check processing code",
"value": {
"code": "WCPT0010",
"message": "Invalid check processing code"
}
},
"Invalid Check Status": {
"summary": "Invalid check status",
"value": {
"code": "WCPT0011",
"message": "Check status is invalid for this operation"
}
},
"Corporate Account Not Found": {
"summary": "Corporate account not found",
"value": {
"code": "WCPT0004",
"message": "Corporate account not found"
}
},
"Account Closed": {
"summary": "Account is closed",
"value": {
"code": "WCPT0009",
"message": "Action not permitted on a closed account"
}
},
"Credit Not Active": {
"summary": "Account credit not active",
"value": {
"code": "WCPT0012",
"message": "The account cannot be credited. Credit function is not active"
}
},
"Invalid account currency code": {
"summary": "Invalid account currency code",
"value": {
"code": "WCPT0014",
"message": "Invalid account currency code: 999"
}
},
"Business date before account creation date": {
"summary": "Business date before account creation date",
"value": {
"code": "WCPT0016",
"message": "The payment date cannot be earlier than the account creation date"
}
},
"Business date before account migration date": {
"summary": "Business date before account migration date",
"value": {
"code": "WCPT0017",
"message": "The payment date cannot be earlier than the account migration date"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Unauthorized account": {
"value": {
"code": "WCAC0001",
"message": "Account not authorized"
}
}
}
}
}
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"CheckIdExists": {
"summary": "Check ID already exists",
"value": {
"code": "WCPT0005",
"message": "check_id [...] is already in use",
"data": {
"check_id": "e219459f-9a7e-48ec-9c2b-1a40a62d5ca3",
"tracking_id": "e219459f-9a7e-48ec-9c2b-1a40a62d5ca3",
"status": "UNCLEARED"
}
}
},
"TrackingIdExists": {
"summary": "Tracking ID already exists",
"value": {
"code": "WCPT0013",
"message": "tracking_id [...] is already in use"
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/500InternalServer"
}
}
}
}
}
}
```