# Create earmark
Create an earmark.
An account holder can use an earmark to hold needed funds in reserve until a specified release date and time.
Optionally, the account holder can schedule a payout for the release date and time. At that time, an automatic process releases the earmarked funds and settles the payout.
It's possible to force the creation of an earmark by not performing any regular validations, such as account status, account balance, or flex controls validations.
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/account-balances-balance-change-1)
- [Account balance changed (Availables)](https://developers.pismo.io/events/docs/availables-change-available-1)
- [Transaction created](https://developers.pismo.io/events/docs/transaction-creation-1)
- [Earmark created, updated, or canceled](https://developers.pismo.io/events/docs/corporate-earmark-1) with `CREATED` action.
**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.
# 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": "Earmarking (external accounts)",
"description": "Earmarking endpoints supporting external accounts"
}
],
"components": {
"schemas": {
"AccountID3": {
"type": "integer",
"format": "int64",
"description": "Account ID generated by [Create Corporate Account](https://developers.pismo.io/pismo-docs/reference/post-account).
\n`minimum: 1`\n`maximum: 4294967295`\n",
"example": 102701621
},
"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"
},
"CancelEarmarkMetadata": {
"type": "object",
"description": "Key-value pairs containing data intended for storage in the Pismo system."
},
"CreateEarmarkRequestV2": {
"type": "object",
"required": [
"amount",
"internal_operation"
],
"oneOf": [
{
"required": [
"account_id"
]
},
{
"required": [
"external_account_id"
]
}
],
"properties": {
"amount": {
"$ref": "#/components/schemas/EarmarkAmount"
},
"internal_operation": {
"$ref": "#/components/schemas/InternalOperation2"
},
"account_id": {
"$ref": "#/components/schemas/AccountID3"
},
"external_account_id": {
"$ref": "#/components/schemas/ExternalAccountIdForEarmark"
},
"earmark_id": {
"$ref": "#/components/schemas/EarmarkIdCreation"
},
"description": {
"$ref": "#/components/schemas/EarmarkDescription"
},
"release_datetime": {
"$ref": "#/components/schemas/EarmarkReleaseDatetime"
},
"force_post": {
"$ref": "#/components/schemas/EarmarkForcePost"
}
}
},
"EarmarkAmount": {
"type": "number",
"format": "float",
"description": "Earmark amount
\n`minimum: 0.01`\n`maximum: 18446744073709551617`\n",
"minimum": 0.01,
"maximum": 18446744073709552000,
"example": 50
},
"EarmarkBalance": {
"type": "number",
"description": "Earmark balance. Initially equal to the earmarked amount and decreases as the reserved funds are used up or decreased in a decrease operation. It can also increase if an increase operation is performed.
\n`minimum: 0`\n`maximum: 18446744073709551617`\n",
"minimum": 0,
"maximum": 18446744073709552000,
"example": 123.45
},
"EarmarkDescription": {
"type": "string",
"description": "Earmark description",
"minLength": 1,
"maxLength": 40
},
"EarmarkForcePost": {
"type": "boolean",
"description": "If the account has any reason-based force debit payment restrictions, and the force earmark creation violates any of those restrictions, it fails. The reasons that restrict force debit operations are:\n - `CREDIT ONLY`: No force debit allowed\n - `ANY`: No force allowed\n - `MANUAL`: No force allowed\n"
},
"EarmarkIdCreation": {
"type": "string",
"description": "Optional earmark ID. If `earmark_id` already exists, the caller receives a 409 error.\nIf provided, the earmark is created with this ID.\nIf not provided, a random earmark ID is generated.\n",
"maxLength": 60,
"pattern": "^[a-zA-Z0-9-]+$",
"example": "da85b309-a7f7-4316-b2ad-f069f0838058"
},
"EarmarkIdReturned": {
"type": "string",
"description": "Earmark ID. Used as the primary key for query and update operations. It has the same value as the tracking ID, if one is provided. Generated by [Create Earmark](https://developers.pismo.io/pismo-docs/reference/post-corporate-v2-earmarks).",
"example": "da85b309-a7f7-4316-b2ad-f069f0838058"
},
"EarmarkReleaseDatetime": {
"type": "string",
"description": "RFC 3339 date/time for earmark release.\nUsed to schedule a cash-out (usually a payment) at the specified release date and time.\nAt `release_datetime`, an automatic process releases the earmarked funds and settles the cash-out.\nIf no `release_datetime` is set, the earmarked amount is held indefinitely until the customer cancels the earmark.\n",
"minLength": 20,
"maxLength": 30,
"example": "2022-02-10T15:00:00Z",
"format": "date-time"
},
"EarmarkResponse": {
"type": "object",
"properties": {
"earmark_id": {
"$ref": "#/components/schemas/EarmarkIdReturned"
},
"account_id": {
"$ref": "#/components/schemas/AccountID3"
},
"external_account_id": {
"$ref": "#/components/schemas/ExternalAccountIdForEarmark"
},
"description": {
"$ref": "#/components/schemas/EarmarkDescription"
},
"amount": {
"$ref": "#/components/schemas/EarmarkAmount"
},
"balance": {
"$ref": "#/components/schemas/EarmarkBalance"
},
"release_datetime": {
"$ref": "#/components/schemas/EarmarkReleaseDatetime"
},
"internal_operations": {
"$ref": "#/components/schemas/InternalOperations"
}
}
},
"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"
}
}
},
"ExternalAccountIdForEarmark": {
"type": "string",
"description": "External ID of the account on which the earmark is created.\nShould be the same `external_account_id` that was used to log in.\nShould be the same `external_account_id` used in [Create Corporate Account](https://developers.pismo.io/pismo-docs/reference/post-account).\n",
"maxLength": 60,
"pattern": "^[a-zA-Z0-9-]+$",
"example": "b993ba96-b3e8-4ef7-9cf7-7eee5ddafdab"
},
"Force": {
"type": "boolean",
"description": "Whether a payment validation rule should be executed in a forced state (`true`) or not (`false`).
\nAllowed for `LEDGER` validation rule.\n",
"example": false
},
"InternalOperation": {
"type": "object",
"description": "Internal operation performed to hold or release funds",
"properties": {
"tracking_id": {
"$ref": "#/components/schemas/TrackingID"
},
"business_date": {
"$ref": "#/components/schemas/BusinessDate"
},
"type": {
"$ref": "#/components/schemas/InternalOperationType"
},
"processing_code": {
"$ref": "#/components/schemas/ProcessingCode"
},
"amount": {
"$ref": "#/components/schemas/InternalOperationAmount"
},
"validation_rules": {
"$ref": "#/components/schemas/ValidationRules"
},
"created_at": {
"$ref": "#/components/schemas/InternalOperationCreatedAt"
},
"metadata": {
"$ref": "#/components/schemas/InternalOperationMetadata"
}
},
"required": [
"tracking_id"
]
},
"InternalOperation2": {
"type": "object",
"description": "Data used in transactions executed internally during the request.",
"properties": {
"tracking_id": {
"$ref": "#/components/schemas/TrackingID"
},
"business_date": {
"$ref": "#/components/schemas/BusinessDate"
},
"validation_rules": {
"$ref": "#/components/schemas/ValidationRules"
},
"metadata": {
"$ref": "#/components/schemas/CancelEarmarkMetadata"
}
},
"required": [
"tracking_id"
]
},
"InternalOperationAmount": {
"type": "number",
"description": "Internal operation amount
\n`minimum: 0`\n`maximum: 18446744073709551617`\n",
"minimum": 0,
"maximum": 18446744073709552000,
"example": 50
},
"InternalOperationCreatedAt": {
"type": "string",
"format": "datetime",
"description": "Internal operation creation time. Format = yyyy-mm-dd:hr:mm:ss.\n",
"example": "2022-02-10T15:00:00Z"
},
"InternalOperationMetadata": {
"type": "object",
"description": "Key-value pairs containing data intended for storage in the Pismo system."
},
"InternalOperations": {
"type": "array",
"description": "List of internal operations performed to hold or release the earmark funds.",
"items": {
"$ref": "#/components/schemas/InternalOperation"
}
},
"InternalOperationType": {
"type": "string",
"description": "Internal operation type.
\n`minLength: 1`\n`maxLength: 13`\n",
"enum": [
"HOLD_FUNDS",
"RELEASE_FUNDS",
"INCREASE",
"DECREASE"
],
"example": "HOLD_FUNDS"
},
"Override": {
"type": "boolean",
"description": "Whether to override the validation rule in the payment process (`true`) or not (`false`).
\nAllowed for `ACCOUNT_STATUS` validation rule.\n",
"example": false
},
"ProcessingCode": {
"type": "string",
"description": "Processing code used to create the underlying transaction. Each internal operation type uses a default processing code.
\n`minLength: 1`\n`maxLength: 6`\n",
"minLength": 1,
"maxLength": 6,
"example": "219248"
},
"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"
},
"ValidationRule": {
"title": "ValidationRule",
"type": "object",
"properties": {
"override": {
"$ref": "#/components/schemas/Override"
},
"force": {
"$ref": "#/components/schemas/Force"
}
}
},
"ValidationRules": {
"title": "ValidationRules",
"type": "object",
"description": "Rules that determine which validations are executed during the payment process.
\nAvailable validation rules:\n - `LEDGER`\n - `ACCOUNT_STATUS`\n",
"additionalProperties": {
"$ref": "#/components/schemas/ValidationRule"
},
"example": {
"ACCOUNT_STATUS": {
"override": false
},
"LEDGER": {
"force": false
}
}
}
},
"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/v2/earmarks": {
"post": {
"summary": "Create earmark",
"description": "Create an earmark.\nAn account holder can use an earmark to hold needed funds in reserve until a specified release date and time.\n\nOptionally, the account holder can schedule a payout for the release date and time. At that time, an automatic process releases the earmarked funds and settles the payout.\n\nIt's possible to force the creation of an earmark by not performing any regular validations, such as account status, account balance, or flex controls validations.\n\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/account-balances-balance-change-1)\n- [Account balance changed (Availables)](https://developers.pismo.io/events/docs/availables-change-available-1)\n- [Transaction created](https://developers.pismo.io/events/docs/transaction-creation-1)\n- [Earmark created, updated, or canceled](https://developers.pismo.io/events/docs/corporate-earmark-1) with `CREATED` action.\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",
"parameters": [],
"operationId": "post-corporate-v2-earmarks",
"tags": [
"Earmarking (external accounts)"
],
"requestBody": {
"description": "Request body",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateEarmarkRequestV2"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EarmarkResponse"
},
"examples": {
"Earmark created": {
"value": {
"earmark_id": "da85b309-a7f7-4316-b2ad-f069f0838058",
"account_id": 102701621,
"description": "string",
"amount": 50,
"balance": 50,
"release_datetime": "2022-02-10T15:00:00.000Z",
"internal_operations": [
{
"type": "HOLD_FUNDS",
"tracking_id": "10027506-171f-b1e1-8412-67f5f5145a3b",
"business_date": "2022-02-10",
"processing_code": "219248",
"amount": 50,
"created_at": "2022-02-10T15:00:00.000Z"
}
]
}
}
}
}
}
},
"400": {
"description": "A Bad Request validation error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Operations blocked for account": {
"description": "This error occurs when there's an operations block for this account",
"value": {
"code": "WOBK0007",
"message": "Operations blocked for account"
}
},
"Invalid JSON payload": {
"value": {
"code": "WEAM0014",
"message": "Invalid JSON payload received: Error unmarshalling request"
}
},
"earmark_id must be a maximum of 60 characters in length": {
"value": {
"code": "WEAM0015",
"message": "earmark_id must be a maximum of 60 characters in length"
}
},
"earmark_id contains characters not permitted": {
"value": {
"code": "WEAM0015",
"message": "earmark_id contains characters not permitted: {characters}"
}
},
"amount must be 100,000,000,000,000,000 or less": {
"value": {
"code": "WEAM0015",
"message": "amount must be 100,000,000,000,000,000 or less"
}
},
"amount must be greater than 0": {
"value": {
"code": "WEAM0015",
"message": "amount must be greater than 0"
}
},
"Missing account identifier": {
"value": {
"code": "WEAM0015",
"message": "Either of these fields must be provided: account_id, external_account_id"
}
},
"external_account_id must be a maximum of 60 characters in length": {
"value": {
"code": "WEAM0015",
"message": "external_account_id must be a maximum of 60 characters in length"
}
},
"external_account_id contains characters not permitted": {
"value": {
"code": "WEAM0015",
"message": "external_account_id contains characters not permitted: {characters}"
}
},
"description must be a maximum of 40 characters in length": {
"value": {
"code": "WEAM0015",
"message": "description must be a maximum of 40 characters in length"
}
},
"tracking_id is a required field": {
"value": {
"code": "WEAM0015",
"message": "tracking_id is a required field"
}
},
"release_datetime cannot be in the past": {
"value": {
"code": "WEAM0015",
"message": "release_datetime cannot be in the past"
}
},
"amount has invalid decimal places for currency": {
"value": {
"code": "WEAM0015",
"message": "The number of decimal places is not compatible with the specified currency"
}
},
"Invalid account status": {
"value": {
"code": "WEAM0005",
"message": "Invalid account status"
}
},
"Insufficient funds": {
"value": {
"code": "WEAM0006",
"message": "Insufficient funds"
}
},
"Orgs operation not found or parameterized": {
"value": {
"code": "WEAM0017",
"message": "Orgs operations not found or parameters are incorrect or invalid"
}
},
"Invalid account program type": {
"value": {
"code": "WEAM0019",
"message": "The account's program type is invalid"
}
},
"Account closed": {
"value": {
"code": "WEAM0026",
"message": "Action not permitted on a closed account"
}
},
"Misconfigured administrative division": {
"value": {
"code": "WEAM0036",
"message": "Administrative division is misconfigured"
}
},
"Account has not finished onboarding": {
"value": {
"code": "WEAM0037",
"message": "Account has not finished onboarding"
}
},
"Invalid business date for the current business day cycle": {
"value": {
"code": "WEAM0039",
"message": "Invalid business date for the current business day cycle"
}
},
"Business date before account creation date": {
"value": {
"code": "WEAM0040",
"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": "WEAM0047",
"message": "The payment date cannot be earlier than the account migration date"
}
},
"Future dated earmark operations are not allowed": {
"value": {
"code": "WEAM0042",
"message": "Future dated earmark operations are not allowed"
}
},
"Cannot post transaction on holidays": {
"value": {
"code": "WEAM0043",
"message": "Cannot post transaction on holidays"
}
},
"Cannot post transaction on weekends": {
"value": {
"code": "WEAM0044",
"message": "Cannot post transaction on weekends"
}
},
"Back business dating disabled": {
"value": {
"code": "WEAM0045",
"message": "Back business dating is disabled"
}
},
"Invalid account currency code": {
"value": {
"code": "WEAM0046",
"message": "Invalid account currency code: 999"
}
},
"Invalid account header": {
"description": "This error occurs when the x-account-id header is invalid or malformed",
"value": {
"code": "WEAM0016",
"message": "Invalid header account"
}
},
"Operation already executed": {
"description": "This error occurs when the operation has already been performed",
"value": {
"code": "WEAM0018",
"message": "operation already made"
}
}
}
}
}
},
"401": {
"description": "Unauthorized operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Account not authorized": {
"value": {
"code": "WEAM0009",
"message": "Account not authorized"
}
},
"Invalid Account token": {
"value": {
"code": "WEAM0020",
"message": "Use of a valid token for a valid account is required"
}
},
"Account cannot be debited": {
"description": "This error occurs when the account cannot be debited.",
"value": {
"code": "WEAM0023",
"message": "The account cannot be debited. Debit function is not active"
}
},
"Account cannot be credited": {
"description": "This error occurs when the account cannot be credited.",
"value": {
"code": "WEAM0024",
"message": "The account cannot be credited. Credit function is not active"
}
}
}
}
}
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"earmark_id [] is already in use": {
"value": {
"code": "WEAM0001",
"message": "earmark_id [{earmark_id}] is already in use",
"data": {
"earmark_id": "da85b309-a7f7-4316-b2ad-f069f0838058",
"account_id": 102701621,
"description": "string",
"amount": 20,
"balance": 20,
"release_datetime": "2022-02-10T15:00:00.000Z",
"internal_operations": [
{
"type": "HOLD_FUNDS",
"tracking_id": "10027506-171f-b1e1-8412-67f5f5145a3b",
"processing_code": "219248",
"amount": 10,
"created_at": "2022-02-10T15:00:00.000Z"
},
{
"type": "INCREASE",
"tracking_id": "77260e09-2839-4b9e-a663-4aee4cf1568f",
"processing_code": "219248",
"amount": 10,
"created_at": "2022-02-10T15:01:00.000Z"
}
]
}
}
},
"Tracking ID already in use": {
"description": "This error occurs when the client sends a duplicate tracking ID.",
"value": {
"code": "WEAM0025",
"message": "Tracking ID is already in use",
"data": {
"earmark_id": "da85b309-a7f7-4316-b2ad-f069f0838058",
"account_id": 102701621,
"description": "string",
"amount": 20,
"balance": 20,
"release_datetime": "2022-02-10T15:00:00.000Z",
"internal_operations": [
{
"type": "HOLD_FUNDS",
"tracking_id": "10027506-171f-b1e1-8412-67f5f5145a3b",
"processing_code": "219248",
"amount": 10,
"created_at": "2022-02-10T15:00:00.000Z"
},
{
"type": "INCREASE",
"tracking_id": "77260e09-2839-4b9e-a663-4aee4cf1568f",
"processing_code": "219248",
"amount": 10,
"created_at": "2022-02-10T15:01:00.000Z"
}
]
}
}
},
"Tracking ID already in use by another earmark or account": {
"description": "This error occurs when the client sends a duplicate tracking ID that is either already in use by another account, or by the same account with a different earmark ID than the one used in the original payment.",
"value": {
"code": "WEAM0034",
"message": "Tracking ID is already in use"
}
}
}
}
}
},
"423": {
"description": "Locked",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Transaction using this tracking ID in progress": {
"description": "This error occurs when multiple payment requests with the same `tracking_id` are made simultaneously.",
"value": {
"code": "WEAM0033",
"message": "transaction using this tracking_id is in progress, please try again later"
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/500InternalServer"
}
}
}
}
}
}
```