Treasury

Record an incoming or outgoing payment

Records a payment in a treasury account.

POST

/api/v1/treasury/payments

curl https://app.filmo.io/api/v1/treasury/payments \
  --request POST \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \
  --header 'Content-Type: application/json' \
  --data '{
  "direction": "in",
  "amount": "1815.50",
  "currency": "EUR",
  "date": "2026-09-04T12:00:00+02:00",
  "paymentMethodId": "pmt_transferencia",
  "treasuryAccountId": "tac_principal",
  "contactId": "cont_00118",
  "linkedDocumentType": "invoice",
  "linkedDocumentId": "inv_02291",
  "reference": "Transf. 4471-A"
}'

Node.jsfetch('https://app.filmo.io/api/v1/treasury/payments', { method: 'POST', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' }, body: JSON.stringify({ direction: 'in', amount: '1815.50', currency: 'EUR', date: '2026-09-04T12:00:00+02:00', paymentMethodId: 'pmt_transferencia', treasuryAccountId: 'tac_principal', contactId: 'cont_00118', linkedDocumentType: 'invoice', linkedDocumentId: 'inv_02291', reference: 'Transf. 4471-A' }) })Pythonimport uuid import requests requests.post( "https://app.filmo.io/api/v1/treasury/payments", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json" }, json={ "direction": "in", "amount": "1815.50", "currency": "EUR", "date": "2026-09-04T12:00:00+02:00", "paymentMethodId": "pmt_transferencia", "treasuryAccountId": "tac_principal", "contactId": "cont_00118", "linkedDocumentType": "invoice", "linkedDocumentId": "inv_02291", "reference": "Transf. 4471-A" } )

{
  "data": {
    "id": "payment_9f3a2b",
    "direction": "Example direction",
    "amount": "120.00",
    "currency": "EUR",
    "date": "2026-09-01T08:00:00.000Z",
    "type": "Example type",
    "treasuryAccountId": "treasury_account_9f3a2b",
    "contactId": "contact_9f3a2b",
    "reference": "2026-0001",
    "linkedDocuments": [
      {
        "type": "invoice",
        "id": "linked_document_9f3a2b",
        "amount": "120.00"
      }
    ],
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z"
  }
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "treasury:write"
}

{
  "type": "https://docs.filmo.io/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Resource not found",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "The current state of the resource does not allow the operation",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "",
      "code": "invalid_state",
      "message": "The current state of the resource does not allow the operation"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/precondition_failed",
  "title": "Precondition failed",
  "status": 412,
  "code": "precondition_failed",
  "detail": "The resource changed since you read it: read it again and retry",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/idempotency_key_reused",
  "title": "Idempotency-Key reused",
  "status": 422,
  "code": "idempotency_key_reused",
  "detail": "The Idempotency-Key header was already used with a different body",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generated from the schema

Send your own Idempotency-Key

A retry without the same key duplicates the effect. Send your own Idempotency-Key and follow the retry table.

The document it is tied to goes as the PAIR linkedDocumentType + linkedDocumentId, never as one field per type: sending two identifiers at once would leave it unknown which one it was tied to. type: "deposit" marks a security deposit collected from a customer: it requires direction: in (400 on direction otherwise) and does not deduct from the order total. The date can be any time of today but not a later day, in the time zone of the account (400 on date). Send Idempotency-Key: a retry without it records the payment twice. Returns the full payment, the same projection as its GET.

Authorizations

Bearer API key with the scope below. treasury:write

Headers

Idempotency-Keystring

Unique identifier of the request, chosen by the client (a UUID works). Between 1 and 255 characters: an empty header is rejected with 400 validation_error, because the client would believe itself protected. Repeating the same key with the SAME body within 24 h returns the stored response without executing again, with the Idempotent-Replay: true header. With a DIFFERENT body it returns 422. It is the safe way to retry after a network timeout.

Limits: min length 1, max length 255

Example:"9f1c2f4e-3a5b-4f6d-8e7a-0b1c2d3e4f5a"

If-Matchstring

Optimistic locking: the ETag you read from the resource (or *). If the resource changed since, the write is rejected with 412 precondition_failed before doing anything; read it again and retry. Without the header the write always proceeds.

Example:"\"3sT3d9pBvZq4h2N0w8x1YkLmQ7c\""

Body

application/json

Body schema: PaymentCreateBody

directionstringRequired

in for a collection from a customer, out for a payment to a supplier.

Available options: in, out

amountstringRequired

Amount as a decimal string, greater than zero.

Limits: pattern ^\d{1,13}(\.\d{1,2})?$

currencystring

Currency in ISO 4217. Defaults to EUR.

Limits: min length 3, max length 3

datestring<date-time>Required

Payment date, in ISO 8601 with offset. Any time of today is accepted; a later day, in the time zone of the account, is rejected with 400.

paymentMethodIdstringRequired

Payment method configured in the account.

Limits: min length 1

treasuryAccountIdstringRequired

Treasury account through which the money comes in or goes out.

Limits: min length 1

typestring

"deposit" marks a security deposit collected from a customer: it requires direction=in (400 otherwise) and is not deducted from the order total.

Available options: normal, deposit

contactIdstring

Customer or supplier of the payment.

linkedDocumentTypestring

Type of the document the payment is linked to. Goes with linkedDocumentId.

Available options: invoice, creditNote, supplierInvoice, quote, proforma, salesReceipt, simpleCreditNote, purchaseOrder

linkedDocumentIdstring

Document the payment is linked to. Goes with linkedDocumentType.

referencestring

External reference of the payment.

Limits: max length 200

notesstring

Notes. They are stored in Filmo and NOT returned.

Limits: max length 2000

Response

application/json

Successful response.

Response schema: PaymentDto

Envelope: PaymentResponse. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay

dataobject

A collection or a payment recorded in treasury.

Show child attributes

data.idstring

Payment identifier.

data.directionstring

in when money comes in (a collection) and out when it goes out (a payment).

data.amountstring

Payment amount as a decimal string, in the indicated currency.

Limits: pattern ^-?\d+\.\d{2}$

data.currencystring

Payment currency, as an ISO 4217 code.

data.datestring<date-time>

Payment date in ISO 8601 UTC.

data.typestring

normal, or deposit when it is an advance payment.

data.treasuryAccountIdstring

Treasury account the payment goes through.

data.contactIdstring | null

Customer or supplier of the payment; null if not declared.

data.referencestring | null

External reference of the payment; null if it has none.

data.linkedDocumentsobject[]

Documents the payment is assigned to; empty if it is not linked to any.

Show child attributes

data.linkedDocuments.typestring

Kind of the linked document.

Available options: invoice, creditNote, supplierInvoice, quote, proforma, salesReceipt, simpleCreditNote, purchaseOrder

data.linkedDocuments.idstring

Identifier of the linked document.

data.linkedDocuments.amountstring

Amount of this payment assigned to the document, as a decimal string.

Limits: pattern ^-?\d+\.\d{2}$

data.createdAtstring<date-time>

Creation date in ISO 8601 UTC.

data.updatedAtstring<date-time>

Last modification date in ISO 8601 UTC.

metaobject

Additional information about the response.

Show child attributes

meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes

meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

Errors

Status	Codes	Meaning
400	`validation_error`	Malformed query or body. `errors[]` lists every offending field with its stable code.
404	`not_found`	It does not exist or is outside the scope of the API key.
409	`conflict`	The current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation.
412	`precondition_failed`	The `If-Match` entity tag does not match the current representation. Read the resource again and retry.
422	`idempotency_key_reused`	The same key was used before with a different body. Change the key.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. Versioning policy

Finance
Payment
A collection or a payment recorded in treasury.

Was this page helpful?

Request examples

Authorizations

Headers

Body

Response

Errors

Deprecation

Related

Related pages

Payment