# Create fund restriction

Create fund restriction. You can move funds from the `available_balance` to the `restricted_funds` balance.

For details, refer to [Restrict funds](doc:restrict-funds).

NOTE:
- 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)
- [Account balance changed](https://developers.pismo.io/events/docs/availables-change-available-1)
- [Restricted Funds created or released](https://developers.pismo.io/events/docs/corporate-restricted-funds-1)
- [Account balance changed](https://developers.pismo.io/events/docs/account-balances-balance-change-1)

See [Data and reporting](doc:data-reporting-overview) for more information on 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": "Restricted funds",
      "description": "Restricted funds endpoints"
    }
  ],
  "components": {
    "schemas": {
      "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"
          }
        }
      },
      "Metadata": {
        "type": "object",
        "description": "Key-value pairs containing data intended for storage in the Pismo system.<br>\n<b>NOTES</b>:\n- The `metadata` field includes a `corporate_metadata` object with the following fields:\n    - `credit_external_account_id`: Included in the `corporate_metadata` field when it's provided in the credit leg.\n    - `debit_external_account_id`: Included in the `corporate_metadata` field when it's provided in the debit leg.\n    - `earmark_id`: Included in the `corporate_metadata` field when it's provided in the debit leg.\n- The `corporate_metadata` attribute must be an object. A type mismatch results in an error as mapped in the responses section.\n",
        "example": {
          "my-id": 2932
        }
      },
      "RestrictedFundsAppliedAmount": {
        "type": "number",
        "format": "float",
        "description": "Amount actually executed by the operation at the time it was applied.\n\nDepending on the `hold_method`, this value may be different from the requested_amount.\n\nHold Method:\n  - STRICT holds either apply the full requested amount or fail\n  - FLEXIBLE may apply only the available portion\n\nType:\n  - For RESTRICT_FUNDS, it is the portion of the requested amount that was successfully held.\n  - For RELEASE_FUNDS, it is the portion that was actually released back to the available balance.\n",
        "minimum": 0,
        "multipleOf": 0.0001,
        "maximum": 100000000000000000,
        "example": 800.22
      },
      "RestrictedFundsAmount": {
        "type": "number",
        "format": "float",
        "description": "Amount requested by the operation.\n\nThe final applied amount may differ (see applied_amount) depending on execution rules and available balance at execution time.\n\nNotes:\n  - For `RESTRICT_FUNDS`, this is the amount to be held.\n  - For `RELEASE_FUNDS`, this is the amount to be released.\n  - Precision depends on the currency's minor units. For example:\n    - 2 decimals (USD, EUR) → multiples of 0.01\n    - 3 decimals (BHD, JOD, KWD, OMR, TND) → multiples of 0.001\n    - 4 decimals (CLF) → multiples of 0.0001\n",
        "minimum": 0.0001,
        "maximum": 100000000000000000
      },
      "RestrictedFundsRequestedAmount": {
        "type": "number",
        "format": "float",
        "description": "Amount originally requested at the time the restriction was created; remains unchanged after the initial request.",
        "minimum": 0.0001,
        "maximum": 100000000000000000
      },
      "RestrictedFundsHoldMethod": {
        "type": "string",
        "description": "Determines how the system processes the restriction request in relation to the available balance at the time of execution.\n\nNotes:\n  - `STRICT`: Applies to the full requested amount or fails (no partial holds).\n  - `FLEXIBLE`: Can apply only to the available portion, resulting in a partial hold.",
        "enum": [
          "STRICT",
          "FLEXIBLE"
        ],
        "example": "STRICT"
      },
      "RestrictedFundsHeldAmount": {
        "type": "number",
        "format": "float",
        "minimum": 0,
        "maximum": 100000000000000000
      },
      "RestrictedFundsID": {
        "type": "string",
        "format": "uuid",
        "maxLength": 36,
        "example": "e4adf199-c925-4d11-b002-c5bfd5679030"
      },
      "RestrictedFundsRequest": {
        "description": "Create funds restriction request body",
        "type": "object",
        "properties": {
          "hold_method": {
            "$ref": "#/components/schemas/RestrictedFundsHoldMethod"
          },
          "amount": {
            "$ref": "#/components/schemas/RestrictedFundsAmount"
          },
          "operation": {
            "$ref": "#/components/schemas/RestrictedFundsRequestOperation"
          },
          "restricted_funds_id": {
            "$ref": "#/components/schemas/RestrictedFundsID"
          },
          "soft_descriptor": {
            "$ref": "#/components/schemas/RestrictedFundsSoftDescriptor"
          }
        },
        "required": [
          "hold_method",
          "amount",
          "operation"
        ]
      },
      "RestrictedFunds": {
        "type": "object",
        "properties": {
          "restricted_funds_id": {
            "$ref": "#/components/schemas/RestrictedFundsID"
          },
          "hold_method": {
            "$ref": "#/components/schemas/RestrictedFundsHoldMethod"
          },
          "requested_amount": {
            "$ref": "#/components/schemas/RestrictedFundsRequestedAmount"
          },
          "held_amount": {
            "$ref": "#/components/schemas/RestrictedFundsHeldAmount"
          },
          "created_at": {
            "$ref": "#/components/schemas/RestrictedFundsCreatedAt"
          },
          "soft_descriptor": {
            "$ref": "#/components/schemas/RestrictedFundsSoftDescriptor"
          },
          "operations": {
            "$ref": "#/components/schemas/RestrictedFundsOperations"
          }
        },
        "required": [
          "restricted_funds_id",
          "hold_method",
          "requested_amount",
          "held_amount",
          "created_at"
        ]
      },
      "RestrictedFundsCreatedAt": {
        "type": "string",
        "format": "date-time",
        "minLength": 1,
        "maxLength": 30,
        "description": "Date and time when the restriction or operation was created, shown in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.<br>\n`minLength: 1`\n`maxLength: 30`\n",
        "example": "2023-04-27T12:01:24Z"
      },
      "RestrictedFundsAppliedAt": {
        "type": "string",
        "format": "date-time",
        "minLength": 1,
        "maxLength": 30,
        "description": "Date and time when the financial operation was actually executed, shown in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.<br>\n`minLength: 1`\n`maxLength: 30`\n",
        "example": "2023-04-27T12:01:24Z"
      },
      "RestrictedFundsOperationType": {
        "type": "string",
        "description": "Represents the kind of financial operation being performed.\nIndicates whether the operation is creating a funds restriction or releasing funds.\n",
        "enum": [
          "RESTRICT_FUNDS",
          "RELEASE_FUNDS"
        ],
        "example": "RELEASE_FUNDS"
      },
      "RestrictedFundsOperation": {
        "type": "object",
        "properties": {
          "tracking_id": {
            "$ref": "#/components/schemas/TrackingID"
          },
          "type": {
            "$ref": "#/components/schemas/RestrictedFundsOperationType"
          },
          "status": {
            "$ref": "#/components/schemas/RestrictedFundsOperationStatus"
          },
          "processing_code": {
            "$ref": "#/components/schemas/RestrictedFundsProcessingCode"
          },
          "requested_amount": {
            "$ref": "#/components/schemas/RestrictedFundsAmount"
          },
          "applied_amount": {
            "$ref": "#/components/schemas/RestrictedFundsAppliedAmount"
          },
          "created_at": {
            "$ref": "#/components/schemas/RestrictedFundsCreatedAt"
          },
          "soft_descriptor": {
            "$ref": "#/components/schemas/RestrictedFundsSoftDescriptor"
          },
          "applied_at": {
            "$ref": "#/components/schemas/RestrictedFundsAppliedAt"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        },
        "required": [
          "tracking_id",
          "type",
          "status",
          "processing_code",
          "requested_amount",
          "applied_amount",
          "created_at"
        ]
      },
      "RestrictedFundsOperations": {
        "type": "array",
        "description": "List of operations performed to restrict or release funds.",
        "items": {
          "$ref": "#/components/schemas/RestrictedFundsOperation"
        }
      },
      "RestrictedFundsProcessingCode": {
        "type": "string",
        "description": "Processing code used to create the underlying transaction. Each operation type uses a default processing code.<br>\n`minLength: 1`\n`maxLength: 6`\n",
        "minLength": 1,
        "maxLength": 6,
        "example": "PSM045"
      },
      "RestrictedFundsRequestOperation": {
        "description": "Represents the data of the hold or release transaction.",
        "type": "object",
        "properties": {
          "tracking_id": {
            "$ref": "#/components/schemas/TrackingID"
          },
          "soft_descriptor": {
            "$ref": "#/components/schemas/RestrictedFundsSoftDescriptor"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        },
        "required": [
          "tracking_id"
        ]
      },
      "RestrictedFundsSoftDescriptor": {
        "type": "string",
        "description": "Brief description that helps to identify a particular restriction or operation.",
        "example": "FDIC 12 C.F.R. § 360.9",
        "maxLength": 100,
        "minLength": 0
      },
      "RestrictedFundsOperationStatus": {
        "type": "string",
        "description": "Indicates the current execution state of the operation.\n",
        "enum": [
          "PROCESSING",
          "SUCCEEDED",
          "FAILED",
          "TIMED_OUT"
        ],
        "example": "SUCCEEDED"
      },
      "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": {
      "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/restricted-funds": {
      "post": {
        "summary": "Create fund restriction",
        "description": "Create fund restriction. You can move funds from the `available_balance` to the `restricted_funds` balance.\n\nFor details, refer to [Restrict funds](https://developers.pismo.io/pismo-docs/docs/restrict-funds).\n\nNOTE:\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.\nThis endpoint generates the following events:\n- [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1)\n- [Account balance changed](https://developers.pismo.io/events/docs/availables-change-available-1)\n- [Restricted Funds created or released](https://developers.pismo.io/events/docs/corporate-restricted-funds-1)\n- [Account balance changed](https://developers.pismo.io/events/docs/account-balances-balance-change-1)\n\nSee [Data and reporting](https://developers.pismo.io/pismo-docs/docs/data-reporting-overview) for more information on events and setting up event notifications.",
        "operationId": "post-corporate-v1-restricted-funds",
        "tags": [
          "Restricted funds"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestrictedFundsRequest"
              },
              "example": {
                "restricted_funds_id": "4a4060d5-3649-46e8-8d64-93949b212918",
                "hold_method": "FLEXIBLE",
                "amount": 100.21,
                "operation": {
                  "tracking_id": "9d15bfd1-5db9-4e96-b846-8d8707454430",
                  "soft_descriptor": "Funds restriction requested by FDIC 12 C.F.R. 360.9",
                  "metadata": {
                    "key": "value"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestrictedFunds"
                },
                "example": {
                  "restricted_funds_id": "4a4060d5-3649-46e8-8d64-93949b212918",
                  "hold_method": "FLEXIBLE",
                  "requested_amount": 100.21,
                  "held_amount": 99.9,
                  "created_at": "2025-05-29T11:33:22Z",
                  "operations": [
                    {
                      "tracking_id": "9d15bfd1-5db9-4e96-b846-8d8707454430",
                      "type": "RESTRICT_FUNDS",
                      "status": "SUCCEEDED",
                      "processing_code": "PSM045",
                      "soft_descriptor": "Funds restriction requested by FDIC 12 C.F.R. 360.9",
                      "requested_amount": 100.21,
                      "applied_amount": 99.9,
                      "created_at": "2025-05-29T11:33:22Z",
                      "applied_at": "2025-05-29T11:33:52Z",
                      "metadata": {
                        "key": "value"
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Invalid JSON": {
                    "value": {
                      "code": "WRFO0001",
                      "message": "Invalid JSON payload received: Error unmarshalling request"
                    }
                  },
                  "Insufficient funds": {
                    "value": {
                      "code": "WRFO0006",
                      "message": "Insufficient funds"
                    }
                  },
                  "Invalid decimal places": {
                    "value": {
                      "code": "WRFO0009",
                      "message": "The number of decimal places is not compatible with the specified currency"
                    }
                  },
                  "Operation Blocked": {
                    "value": {
                      "code": "WOBK0007",
                      "message": "Operations blocked for account"
                    }
                  },
                  "Invalid account status": {
                    "value": {
                      "code": "WRFO0011",
                      "message": "Invalid account status"
                    }
                  },
                  "Account has not finished onboarding": {
                    "value": {
                      "code": "WRFO0012",
                      "message": "Account has not finished onboarding"
                    }
                  },
                  "Invalid account currency code": {
                    "value": {
                      "code": "WRFO0013",
                      "message": "Invalid account currency code: 999"
                    }
                  },
                  "Invalid restricted funds processing code": {
                    "description": "This error occurs when the processing code for restricted funds operation is invalid",
                    "value": {
                      "code": "WRFO0014",
                      "message": "Invalid restricted funds processing code"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Unauthorized account": {
                    "value": {
                      "code": "WRFO0010",
                      "message": "Account not authorized"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Already exist": {
                    "value": {
                      "code": "WRFO0004",
                      "message": "Restricted funds already exist"
                    }
                  },
                  "Tracking ID already exist": {
                    "value": {
                      "code": "WRFO0005",
                      "message": "tracking_id is already in use"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "Account locked": {
                    "description": "This error occurs when the account is locked due to concurrent operations",
                    "value": {
                      "code": "WRFO0003",
                      "message": "Account is locked, please try again later"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500InternalServer"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}
```