Payments
Payments
Payment management operations.
Record payments against outgoing documents and expenses.
Supports partial payments, credit note applications, and automatic payment status updates.
The Payment object
Attributes
Payment amount in the linked document currency's major unit; for EUR, 29.90 means €29.90, not 2,990 cents.
Payment method. Use credit_card or debit_card to preserve the card distinction in Portuguese SAF-T (CC/CD). Legacy card remains accepted and exports as CC. crypto is opt-in: it is accepted only on a crypto-currency document, or when the entity enabled settings.crypto_invoicing or settings.crypto_equivalents; otherwise the API answers 422 with cause.code crypto_payment_type_not_enabled.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "crypto", "other", "credit_note", "advance"
Date the payment was received (ISO 8601 datetime at midnight UTC)
Custom string key-value data for your own use, with up to 50 properties. Keys are opaque and may contain periods. Useful for storing external IDs, tags, or integration data.
{
"id": "pmt_def789ghi012",
"invoice_id": "inv_abc123def456",
"credit_note_id": null,
"advance_invoice_id": null,
"expense_id": null,
"applied_to_expense_id": null,
"amount": 12500,
"type": "bank_transfer",
"date": "2024-01-10T00:00:00.000Z",
"reference": "ORB-2025-042",
"tag": null,
"note": "First installment for antenna array",
"entity_id": "ent_xyz789",
"metadata": {
"source": "web_app",
"processor": "stripe"
},
"created_at": "2024-01-10T14:20:00.000Z",
"updated_at": "2024-01-10T14:20:00.000Z",
"deleted_at": null
}Create a new payment
/paymentsRecord a payment against an outgoing document or a supplier expense.
At least one document reference is required.
For new direct outgoing payments, prefer document_id; the API infers invoice_id, credit_note_id, or advance_invoice_id from the ID prefix.
Legacy type-specific fields remain supported for backward compatibility.
For outgoing type credit_note, both invoice_id and credit_note_id are required.
Expense payments support direct supplier invoice payments in V1; AP credit-note settlement is reserved for a later release.
Document payment totals are automatically updated. Ordinary payments on invoices with linked advances atomically reduce the auto-applied advance amount so combined settlement never exceeds the invoice total.
Credit note refunds or settlements cannot exceed the remaining credit balance.
Draft advance invoices may accumulate payments up to their total and must be fully paid before they can be issued. Issued advance invoices must retain exact full payment coverage.
Expense payments are capped at the expense's open balance (total_with_tax minus the payments already recorded), compared at the currency's minor unit (0.01 EUR, 1 JPY, 0.001 KWD). A payment that would exceed it returns 422 with cause.code expense_payment_exceeds_open_balance and records nothing. Concurrent payments on one expense are serialized, so they can never together exceed its total.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Optional idempotency key. Reusing it with the same authenticated entity and identical body replays the original result. A different body returns 409 idempotency_key_mismatch. A concurrent attempt returns 409 request_in_progress: wait for Retry-After, then retry the identical body with the same ID. A 503 idempotency_unavailable means the current send was not safely reserved; use a new ID only when no earlier send remains unresolved. A 503 idempotency_legacy_scope_ambiguous means a request with this ID was logged before idempotent payments were introduced (only within 24 hours of that change) and cannot be verified; do not resend with a new ID, check whether the payment exists first. More than 100 characters returns 400 invalid_request_id. X-Request-Id identifies the affected attempt when available.
Body parameters
Payment amount in the linked document currency's major unit; for EUR, 29.90 means €29.90, not 2,990 cents.
Payment method. Use credit_card or debit_card to preserve the card distinction in Portuguese SAF-T (CC/CD). Legacy card remains accepted and exports as CC. crypto is opt-in: it is accepted only on a crypto-currency document, or when the entity enabled settings.crypto_invoicing or settings.crypto_equivalents; otherwise the API answers 422 with cause.code crypto_payment_type_not_enabled.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "crypto", "other", "credit_note", "advance"
Payment date in YYYY-MM-DD format
Custom string key-value data for your own use, with up to 50 properties. Keys are opaque and may contain periods. Useful for storing external IDs, tags, or integration data.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.create({
invoice_id: "inv_abc123def456",
amount: 1500,
type: "cash"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Payment amount in the linked document currency's major unit; for EUR, 29.90 means €29.90, not 2,990 cents.
Payment method. Use credit_card or debit_card to preserve the card distinction in Portuguese SAF-T (CC/CD). Legacy card remains accepted and exports as CC. crypto is opt-in: it is accepted only on a crypto-currency document, or when the entity enabled settings.crypto_invoicing or settings.crypto_equivalents; otherwise the API answers 422 with cause.code crypto_payment_type_not_enabled.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "crypto", "other", "credit_note", "advance"
Date the payment was received (ISO 8601 datetime at midnight UTC)
Custom string key-value data for your own use, with up to 50 properties. Keys are opaque and may contain periods. Useful for storing external IDs, tags, or integration data.
{
"id": "pmt_abc123def456",
"invoice_id": "inv_abc123def456",
"credit_note_id": null,
"advance_invoice_id": null,
"expense_id": null,
"applied_to_expense_id": null,
"amount": 1500,
"type": "cash",
"date": "2024-01-15T00:00:00.000Z",
"reference": null,
"tag": null,
"note": null,
"entity_id": "ent_xyz789",
"metadata": {},
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z",
"deleted_at": null
}Upload a bank statement file
/bank-importsDetects the bank statement format (Revolut Business CSV, camt.053 XML and, for US entities only, Chase business checking CSV and Stripe balance CSV) or uses source_format when supplied, parses it into immutable normalized transactions, and deduplicates re-uploads. Processing is synchronous and ALSO runs the matching engine against open invoices/expenses immediately: an exact, unambiguous match creates a payment (bank_transfer, except on a US entity's import whose ledger_account_code is not 1000: card for invoices, other for expenses) and marks the transaction auto_matched (see the response's match_summary.auto_matched count); a weaker or ambiguous match, or an expense whose open balance is smaller than the bank amount, is left suggested for a human to confirm; everything else is unmatched. Use the bank transaction review endpoints (link, confirm-fee, ignore, unlink) to act on suggested/unmatched rows.
US-only formats: chase_csv and stripe_balance_csv are refused with 422 for any other country, whether named in source_format or detected. stripe_balance_csv reads Stripe's "Balance change from activity - itemized" report or the dashboard "Balance history" export; each row carries the gross amount and the processor fee in fee_amount, and it settles to ledger_account_code 1050 by default (1000 is refused with 422). For US entities, the ledger posts the import's processor fees and categorized rows against ledger_account_code, except rows in a currency other than the entity's, which are reported as worksheet warnings. Payout rows of a US import whose ledger_account_code is not 1000 are never auto-matched.
Set source_format=generic_csv with a column_mapping JSON object ({ booking_date, amount } or { booking_date, credit, debit }, plus optional currency, counterparty_name, counterparty_iban, reference, description, account_iban, date_format ) to import a CSV layout the automatic detectors do not recognize. For generic CSV, duplicate detection hashes the whole row: every column as a header name (trimmed, lower-cased) and cell value (trimmed) pair in header order, plus the parsed signed amount and currency, the account IBAN (the account_iban column or the account_iban form field) and the occurrence number among byte-identical rows in the file. Re-uploading the same file with a richer descriptive mapping (reference, description, counterparty) therefore imports nothing new, and an overlapping export with the same headers skips the rows it shares with an earlier file; two different movements on the same day for the same amount are both imported, and the same cells under a credit header and a debit header are +100 and -100, not duplicates. Limitations: a bank that renames, reorders, adds or drops a column or reformats a date or amount changes the keys of the affected rows, so the same movement exported in the old and the new layout is imported twice; mapping the credit and debit columns the other way round (another sign) or mapping a currency column that the first import did not map also gives new keys; identical rows from two accounts are only kept apart when an account_iban is supplied; and a movement imported as camt.053 and again as a CSV is not recognised as a duplicate. Every mapped value must fit its stored column (reference up to 140 characters, description up to 1000, currency a 3-letter code, real calendar dates); otherwise the upload is a 422 naming the CSV row. The file's size and mime type are checked before it is parsed.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Required idempotency key. Reusing it with the same entity and identical file replays the original import (200). Reusing it with different file content fails with 409 Conflict.
Body parameters
Bank statement file (CSV or XML)
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
import fs from 'fs';
const sdk = new SpaceInvoices('YOUR_API_KEY');
// Read file as Buffer
const fileBuffer = fs.readFileSync('/path/to/image.png');
const file = new File([fileBuffer], 'image.png', { type: 'image/png' });
const response = await sdk.payments.importBankStatement({
file
}, { entity_id: 'YOUR_ENTITY_ID', request_id: 'UNIQUE_REQUEST_ID' });
console.log(response);Returns
{
"id": "id",
"entity_id": "entity-id",
"source_format": "revolut_csv",
"status": "processing",
"account_iban": "account-iban",
"ledger_account_code": "1000",
"statement_from": "statement-from",
"statement_to": "statement-to",
"imported_count": 0,
"duplicate_count": 0,
"skipped_count": 0,
"error_code": "error-code",
"error_message": "error-message",
"request_id": "request-id",
"source_filename": "source-filename",
"source_mime_type": "source-mime-type",
"source_bytes": 0,
"source_content_sha256": "source-content-sha256",
"created_at": "2025-01-15T10:30:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z",
"match_summary": {
"unmatched": 0,
"auto_matched": 0,
"suggested": 0,
"resolved_link": 0,
"resolved_fee": 0,
"resolved_account": 0,
"ignored": 0,
"fee_candidates": 0
}
}List all payments
/paymentsRetrieve a paginated list of payments with optional filtering and sorting. Supports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting across both outgoing and expense payment references.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Query parameters
Number of results per request.
Default: 10
Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.
Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.
Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.
Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with - for descending order. When paginating, reuse cursors only with the same effective ordering.
JSON query object for filtering results. Supports MongoDB-style operators.
Array columns (such as an item's categories) compare as sets: a direct value asks whether the list contains it, contains takes an array and requires all of them, in matches any of them, and notIn matches none. Scalar operators such as gt do not apply and are ignored.
Supported operators:
- equals or direct value - Exact match (default)
- gte - Greater than or equal
- lte - Less than or equal
- gt - Greater than
- lt - Less than
- in - Value in array
- notIn - Value not in array
- contains - String contains (case-insensitive)
- startsWith - String starts with
- endsWith - String ends with
- between - Value between two numbers/dates [min, max]
Allowed fields: id, invoice_id, credit_note_id, advance_invoice_id, expense_id, applied_to_expense_id, amount, type, date, reference, note, metadata, created_at, updated_at
Examples:
- {"total": {"gte": 1000}} - Invoices over 1000
- {"customer.name": {"contains": "Acme"}} - Customer name contains "Acme"
- {"date": {"between": ["2025-01-01", "2025-12-31"]}} - Date range
Full-text search query to filter results across multiple fields.
Searches are case-insensitive and match partial strings.
Searches across all text fields including names, descriptions, addresses, and metadata values.
Comma-separated list of relations to include in the response.
Available relations:
- Invoice - The invoice this payment is linked to
- CreditNote - The credit note this payment is linked to
- AdvanceInvoice - The advance invoice this payment is linked to
- Expense - The expense this payment is linked to
- AppliedToExpense - The supplier invoice expense this credit note settlement is applied to
Usage:?include=Invoice?include=Invoice,CreditNote,AdvanceInvoice,Expense,AppliedToExpense
When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.list({
limit: 20,
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Pagination metadata including cursors and result counts
{
"data": [
{
"id": "pmt_abc123def456",
"invoice_id": "inv_abc123def456",
"credit_note_id": null,
"advance_invoice_id": null,
"expense_id": null,
"applied_to_expense_id": null,
"amount": 1500,
"type": "cash",
"date": "2024-01-15T00:00:00.000Z",
"reference": null,
"tag": null,
"note": null,
"entity_id": "ent_xyz789",
"metadata": {},
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z",
"deleted_at": null
},
{
"id": "pmt_def789ghi012",
"invoice_id": "inv_abc123def456",
"credit_note_id": null,
"advance_invoice_id": null,
"expense_id": null,
"applied_to_expense_id": null,
"amount": 12500,
"type": "bank_transfer",
"date": "2024-01-10T00:00:00.000Z",
"reference": "ORB-2025-042",
"tag": null,
"note": "First installment for antenna array",
"entity_id": "ent_xyz789",
"metadata": {
"source": "web_app",
"processor": "stripe"
},
"created_at": "2024-01-10T14:20:00.000Z",
"updated_at": "2024-01-10T14:20:00.000Z",
"deleted_at": null
}
],
"pagination": {
"total": 2,
"next_cursor": null,
"prev_cursor": null,
"has_more": false
}
}List bank statement imports
/bank-importsCursor-paginated list of bank statement imports for the entity, newest first.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Query parameters
Number of results per request.
Default: 10
Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.
Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.
Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.listBankImports(undefined, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Pagination metadata including cursors and result counts
{
"data": [
{
"id": "bankimport_abc123",
"entity_id": "ent_abc123",
"source_format": "revolut_csv",
"status": "completed",
"account_iban": "LT000000000000000001",
"ledger_account_code": "1000",
"statement_from": "2026-08-01",
"statement_to": "2026-08-31",
"imported_count": 21,
"duplicate_count": 0,
"skipped_count": 0,
"error_code": null,
"error_message": null,
"request_id": "req_2026-08-31-statement",
"source_filename": "revolut-business-2026.csv",
"source_mime_type": "text/csv",
"source_bytes": 4200,
"created_at": "2026-08-31T10:00:00.000Z",
"updated_at": "2026-08-31T10:00:00.000Z"
}
],
"pagination": {
"total": 1,
"next_cursor": null,
"prev_cursor": null,
"has_more": false
}
}List bank transactions
/bank-transactionsCursor-paginated list of immutable bank transaction rows for the entity, newest booking date first. Does not include raw; fetch the detail route for that.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Query parameters
Number of results per request.
Default: 10
Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.
Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.
Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.
Filter to transactions in one or more match statuses, comma-separated (e.g. unmatched,suggested).
Filter to transactions parsed from this bank statement import.
Filter to transactions with booking_date on or after this date (YYYY-MM-DD).
Filter to transactions with booking_date on or before this date (YYYY-MM-DD).
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.listBankTransactions(undefined, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Pagination metadata including cursors and result counts
{
"data": [
{
"id": "banktxn_abc123",
"entity_id": "ent_abc123",
"import_id": "bankimport_abc123",
"source_format": "revolut_csv",
"bank_transaction_ref": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"booking_date": "2026-08-31",
"value_date": "2026-08-31",
"amount": -4000,
"currency_code": "EUR",
"fee_amount": null,
"counterparty_name": "PODJETJE 8834 D.O.O.",
"counterparty_iban": "SI56299536963735251",
"counterparty_bic": "KBMASI2XXXX",
"reference": "2026-00023",
"description": "To PODJETJE 8834 D.O.O.",
"transaction_type": "TRANSFER",
"account_iban": "LT000000000000000001",
"is_fee_candidate": false,
"match_status": "unmatched",
"payment_id": null,
"ledger_account_code": null,
"ledger_related_party": false,
"ledger_contact_id": null,
"ledger_memo": null,
"created_at": "2026-08-31T10:00:00.000Z"
}
],
"pagination": {
"total": 1,
"next_cursor": null,
"prev_cursor": null,
"has_more": false
}
}Get payment by ID
/payments/{id}Retrieve a single payment by its unique identifier. Returns the complete payment details including amount, type, date, and reference information.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
Query parameters
Comma-separated list of relations to include in the response.
Available relations:
- Invoice - The invoice this payment is linked to
- CreditNote - The credit note this payment is linked to
- AdvanceInvoice - The advance invoice this payment is linked to
- Expense - The expense this payment is linked to
- AppliedToExpense - The supplier invoice expense this credit note settlement is applied to
Usage:?include=Invoice?include=Invoice,CreditNote,AdvanceInvoice,Expense,AppliedToExpense
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.get('pay_6595a27b5d35015c3ef0c3fd', undefined, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Payment amount in the linked document currency's major unit; for EUR, 29.90 means €29.90, not 2,990 cents.
Payment method. Use credit_card or debit_card to preserve the card distinction in Portuguese SAF-T (CC/CD). Legacy card remains accepted and exports as CC. crypto is opt-in: it is accepted only on a crypto-currency document, or when the entity enabled settings.crypto_invoicing or settings.crypto_equivalents; otherwise the API answers 422 with cause.code crypto_payment_type_not_enabled.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "crypto", "other", "credit_note", "advance"
Date the payment was received (ISO 8601 datetime at midnight UTC)
Custom string key-value data for your own use, with up to 50 properties. Keys are opaque and may contain periods. Useful for storing external IDs, tags, or integration data.
{
"id": "pmt_def789ghi012",
"invoice_id": "inv_abc123def456",
"credit_note_id": null,
"advance_invoice_id": null,
"expense_id": null,
"applied_to_expense_id": null,
"amount": 12500,
"type": "bank_transfer",
"date": "2024-01-10T00:00:00.000Z",
"reference": "ORB-2025-042",
"tag": null,
"note": "First installment for antenna array",
"entity_id": "ent_xyz789",
"metadata": {
"source": "web_app",
"processor": "stripe"
},
"created_at": "2024-01-10T14:20:00.000Z",
"updated_at": "2024-01-10T14:20:00.000Z",
"deleted_at": null
}Get a bank statement import by ID
/bank-imports/{id}Get a bank statement import by ID
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.getBankImport('pay_6595a27b5d35015c3ef0c3fd', {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "bankimport_abc123",
"entity_id": "ent_abc123",
"source_format": "revolut_csv",
"status": "completed",
"account_iban": "LT000000000000000001",
"ledger_account_code": "1000",
"statement_from": "2026-08-01",
"statement_to": "2026-08-31",
"imported_count": 21,
"duplicate_count": 0,
"skipped_count": 0,
"error_code": null,
"error_message": null,
"request_id": "req_2026-08-31-statement",
"source_filename": "revolut-business-2026.csv",
"source_mime_type": "text/csv",
"source_bytes": 4200,
"created_at": "2026-08-31T10:00:00.000Z",
"updated_at": "2026-08-31T10:00:00.000Z"
}Get a bank transaction by ID
/bank-transactions/{id}Returns the full row including raw, the parsed source data this transaction was built from.
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.getBankTransaction('pay_6595a27b5d35015c3ef0c3fd', {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "banktxn_abc123",
"entity_id": "ent_abc123",
"import_id": "bankimport_abc123",
"source_format": "revolut_csv",
"bank_transaction_ref": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"booking_date": "2026-08-31",
"value_date": "2026-08-31",
"amount": -4000,
"currency_code": "EUR",
"fee_amount": null,
"counterparty_name": "PODJETJE 8834 D.O.O.",
"counterparty_iban": "SI56299536963735251",
"counterparty_bic": "KBMASI2XXXX",
"reference": "2026-00023",
"description": "To PODJETJE 8834 D.O.O.",
"transaction_type": "TRANSFER",
"account_iban": "LT000000000000000001",
"is_fee_candidate": false,
"match_status": "unmatched",
"payment_id": null,
"ledger_account_code": null,
"ledger_related_party": false,
"ledger_contact_id": null,
"ledger_memo": null,
"created_at": "2026-08-31T10:00:00.000Z",
"raw": {
"ID": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"Amount": "-4000.00"
}
}Update a payment
/payments/{id}Update an existing payment.
Only the provided fields will be updated.
Document references cannot be changed.
If amount is changed, payment totals on all linked outgoing or incoming documents are automatically recalculated. Ordinary invoice payment increases atomically reduce any linked advance allocation.
System-managed settlement payments cannot be modified.
For active issued advance invoices, non-amount metadata may be updated, but amount changes must preserve exact full payment coverage.
An expense payment's amount can be raised up to the expense's open balance plus the payment's current amount; a larger amount returns 422 with cause.code expense_payment_exceeds_open_balance and leaves the payment unchanged. Lowering an amount is always allowed.
Changing type on a payment attached to a fiscalized invoice is not a local edit — the payment method is part of what was reported, so the change is validated and, in Croatia, reported onward. A 422 carries a cause.code naming which rule applied:
- fiscalization_required_for_payment_type — Slovenia. The invoice was issued under a FURS skip, which is only legal for some payment types; the requested type is not one of them. Fiscalize the document first (POST /documents/{id}/fiscalize, naming business_premise_name and electronic_device_name — a skipped invoice has no FURS record to derive them from), then retry.
- fina_payment_change_window_expired — Croatia. CIS only accepts a payment-method change on the fiscal issue day, before midnight in Europe/Zagreb. Technical failures do not extend this cutoff, including for retries. The retained fiscal issue time must be valid and not in the future. Issue a credit note and a corrected invoice instead.
- fina_cis_record_unavailable — Croatia. The invoice was fiscalized before its CIS record was retained, so the change cannot be reported and must not be made locally.
- fiscalization_provider_error — Croatia. CIS rejected the change; the provider code and message are preserved, and every field the request changed is restored so the stored payment and the CIS record never disagree. Caller-correctable CIS codes (for example certificate, OIB or invoice-data errors) return 422; a CIS message defect (s001, s004) returns 500; a CIS system error (s006) or an unrecognised CIS code returns 503.
A 500 with cause.code fina_payment_change_unrecorded means CIS accepted the change but it could not be recorded locally; retry the same change. A 503 with cause.code fina_unreachable means CIS could not be reached; the payment is left unchanged. Because CIS may nonetheless hold the change, the attempt is recorded on the invoice (fina.data.payment_change_unconfirmed): retrying the same change clears it once CIS answers, while a different change is refused with 409 fina_payment_change_unconfirmed until then. Type changes on one invoice are serialized, so two corrections issued at once are applied one after the other.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
Body parameters
Payment amount in the linked document currency's major unit; for EUR, 29.90 means €29.90, not 2,990 cents.
Payment method. Use credit_card or debit_card to preserve the card distinction in Portuguese SAF-T (CC/CD). Legacy card remains accepted and exports as CC. crypto is opt-in: it is accepted only on a crypto-currency document, or when the entity enabled settings.crypto_invoicing or settings.crypto_equivalents; otherwise the API answers 422 with cause.code crypto_payment_type_not_enabled.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "crypto", "other", "credit_note", "advance"
Payment date in YYYY-MM-DD format
Custom string key-value data for your own use, with up to 50 properties. Keys are opaque and may contain periods. Useful for storing external IDs, tags, or integration data.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.update('pay_6595a27b5d35015c3ef0c3fd', {
amount: 15000
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Payment amount in the linked document currency's major unit; for EUR, 29.90 means €29.90, not 2,990 cents.
Payment method. Use credit_card or debit_card to preserve the card distinction in Portuguese SAF-T (CC/CD). Legacy card remains accepted and exports as CC. crypto is opt-in: it is accepted only on a crypto-currency document, or when the entity enabled settings.crypto_invoicing or settings.crypto_equivalents; otherwise the API answers 422 with cause.code crypto_payment_type_not_enabled.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "crypto", "other", "credit_note", "advance"
Date the payment was received (ISO 8601 datetime at midnight UTC)
Custom string key-value data for your own use, with up to 50 properties. Keys are opaque and may contain periods. Useful for storing external IDs, tags, or integration data.
{
"id": "pmt_def789ghi012",
"invoice_id": "inv_abc123def456",
"credit_note_id": null,
"advance_invoice_id": null,
"amount": 15000,
"type": "bank_transfer",
"date": "2024-01-10T00:00:00.000Z",
"reference": "MSN-2025-001-FINAL",
"tag": null,
"note": "Final payment for ground station antenna array",
"entity_id": "ent_xyz789",
"metadata": {},
"created_at": "2024-01-10T14:20:00.000Z",
"updated_at": "2024-01-15T09:00:00.000Z",
"deleted_at": null
}Delete a payment
/payments/{id}Soft delete a payment by its unique identifier. The payment is moved to trash and can be restored later. Payment totals on all linked outgoing or incoming documents are automatically recalculated after deletion. System-managed settlement payments remain immutable. Payments providing coverage for active issued advance invoices cannot be deleted.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
await sdk.payments.delete('pay_6595a27b5d35015c3ef0c3fd', {
entity_id: "YOUR_ENTITY_ID"
});
console.log('Deleted successfully');Permanently delete a payment
/payments/{id}/permanentPermanently delete a soft-deleted payment. Only payments in the trash can be permanently deleted. Document payment totals are automatically recalculated.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
await sdk.payments.permanentDeletePayment('pay_6595a27b5d35015c3ef0c3fd', {
entity_id: "YOUR_ENTITY_ID"
});
console.log('Deleted successfully');Restore a deleted payment
/payments/{id}/restoreRestore a soft-deleted payment from the trash. Document payment totals are automatically recalculated. Restoring an ordinary invoice payment atomically reduces any linked advance allocation when needed to keep combined settlement within the invoice total. A restored expense payment must fit the expense's open balance; otherwise the request returns 422 with cause.code expense_payment_exceeds_open_balance and the payment stays deleted. A payment that was created from a bank transaction (a payment linked or auto-matched on the Bank page, or the fee payment of a bank-fee expense) cannot be restored: the request returns 409 with cause.code bank_payment_restore_not_supported and cause.bank_transaction_id, and the payment stays deleted. Link the bank transaction again from the Bank page instead.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.restorePayment('pay_6595a27b5d35015c3ef0c3fd', {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Payment amount in the linked document currency's major unit; for EUR, 29.90 means €29.90, not 2,990 cents.
Payment method. Use credit_card or debit_card to preserve the card distinction in Portuguese SAF-T (CC/CD). Legacy card remains accepted and exports as CC. crypto is opt-in: it is accepted only on a crypto-currency document, or when the entity enabled settings.crypto_invoicing or settings.crypto_equivalents; otherwise the API answers 422 with cause.code crypto_payment_type_not_enabled.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "crypto", "other", "credit_note", "advance"
Date the payment was received (ISO 8601 datetime at midnight UTC)
Custom string key-value data for your own use, with up to 50 properties. Keys are opaque and may contain periods. Useful for storing external IDs, tags, or integration data.
{
"id": "pmt_def789ghi012",
"invoice_id": "inv_abc123def456",
"credit_note_id": null,
"advance_invoice_id": null,
"expense_id": null,
"applied_to_expense_id": null,
"amount": 12500,
"type": "bank_transfer",
"date": "2024-01-10T00:00:00.000Z",
"reference": "ORB-2025-042",
"tag": null,
"note": "First installment for antenna array",
"entity_id": "ent_xyz789",
"metadata": {
"source": "web_app",
"processor": "stripe"
},
"created_at": "2024-01-10T14:20:00.000Z",
"updated_at": "2024-01-10T14:20:00.000Z",
"deleted_at": null
}Get match-status counts for a bank statement import
/bank-imports/{id}/summaryCounts of the import's bank transactions by match status, for the review-page summary UI.
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.getBankImportSummary('pay_6595a27b5d35015c3ef0c3fd', {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"unmatched": 3,
"auto_matched": 15,
"suggested": 2,
"resolved_link": 0,
"resolved_fee": 1,
"ignored": 0,
"fee_candidates": 1
}Re-run matching for a bank statement import
/bank-imports/{id}/matchRe-runs the matching engine over this import's unmatched and suggested rows only — already resolved rows (auto_matched/resolved_link/resolved_fee/resolved_account/ignored) are left untouched. An exact, unambiguous match found on this pass creates a payment (bank_transfer, except on a US entity's import whose ledger_account_code is not 1000: card for invoices, other for expenses) and marks the row auto_matched, exactly like the initial upload (an expense whose open balance is smaller than the bank amount is only suggested); everything else stays suggested or unmatched for the bank transaction review endpoints (link, confirm-fee, ignore, unlink). Calling it again does not create duplicate payments: each row's transition is a status-conditional claim.
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.rematchBankImport('pay_6595a27b5d35015c3ef0c3fd', {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "bankimport_abc123",
"entity_id": "ent_abc123",
"source_format": "revolut_csv",
"status": "completed",
"account_iban": "LT000000000000000001",
"ledger_account_code": "1000",
"statement_from": "2026-08-01",
"statement_to": "2026-08-31",
"imported_count": 21,
"duplicate_count": 0,
"skipped_count": 0,
"error_code": null,
"error_message": null,
"request_id": "req_2026-08-31-statement",
"source_filename": "revolut-business-2026.csv",
"source_mime_type": "text/csv",
"source_bytes": 4200,
"created_at": "2026-08-31T10:00:00.000Z",
"updated_at": "2026-08-31T10:00:00.000Z",
"match_summary": {
"unmatched": 3,
"auto_matched": 15,
"suggested": 2,
"resolved_link": 0,
"resolved_fee": 1,
"ignored": 0,
"fee_candidates": 1
}
}Link a bank transaction to an invoice or expense
/bank-transactions/{id}/linkCreates a payment for the linked document (dated on the booking date) and moves the transaction to resolved_link. The payment is a bank_transfer, except on a US entity's import whose ledger_account_code is not 1000: card for invoices, other for expenses. The document type must match the transaction's direction: a credit (incoming) row links to an invoice or to an expense that is a supplier credit note, a debit (outgoing) row links to an expense that is not a credit note (422 otherwise). amount may be lower than the row (a partial payment) but not higher (422). An invoice that is already fully paid can still be linked and records an overpayment. An expense is capped at its open balance by the payments service: a link above it is 422 with cause.code expense_payment_exceeds_open_balance (and cause.max_amount), the transaction stays unlinked and no payment is created. Only valid from unmatched or suggested; any other status is 409.
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
Body parameters
Must match the transaction's direction: a credit row (money in) links to an invoice or to an expense that is a supplier credit note; a debit row (money out) links to an expense that is not a credit note. A mismatch is a 422.
Possible values: "invoice", "expense"
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.linkBankTransaction('pay_6595a27b5d35015c3ef0c3fd', {
document_type: "expense",
document_id: "exp_2fb1c9d6e8a94b17"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "banktxn_abc123",
"entity_id": "ent_abc123",
"import_id": "bankimport_abc123",
"source_format": "revolut_csv",
"bank_transaction_ref": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"booking_date": "2026-08-31",
"value_date": "2026-08-31",
"amount": -4000,
"currency_code": "EUR",
"fee_amount": null,
"counterparty_name": "PODJETJE 8834 D.O.O.",
"counterparty_iban": "SI56299536963735251",
"counterparty_bic": "KBMASI2XXXX",
"reference": "2026-00023",
"description": "To PODJETJE 8834 D.O.O.",
"transaction_type": "TRANSFER",
"account_iban": "LT000000000000000001",
"is_fee_candidate": false,
"match_status": "resolved_link",
"payment_id": "pay_9c1a2b3d4e5f6071",
"ledger_account_code": null,
"ledger_related_party": false,
"ledger_contact_id": null,
"ledger_memo": null,
"created_at": "2026-08-31T10:00:00.000Z",
"raw": {
"ID": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"Amount": "-4000.00"
},
"match": {
"payment_id": "pay_9c1a2b3d4e5f6071",
"document_type": "expense",
"document_id": "exp_2fb1c9d6e8a94b17",
"document_number": "2026-00087",
"is_fee": false,
"suggested_documents": []
}
}Confirm a bank transaction as a bank fee
/bank-transactions/{id}/confirm-feeCreates a paid expense for the fee amount (VAT-exempt bank-fee category, dated on the booking date) and moves the transaction to resolved_fee. Only valid for a debit (outgoing) row, from unmatched or suggested; any other status is 409.
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.confirmBankTransactionFee('pay_6595a27b5d35015c3ef0c3fd', {
category: "Bank fees"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "banktxn_abc123",
"entity_id": "ent_abc123",
"import_id": "bankimport_abc123",
"source_format": "revolut_csv",
"bank_transaction_ref": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"booking_date": "2026-08-31",
"value_date": "2026-08-31",
"amount": -4.5,
"currency_code": "EUR",
"fee_amount": null,
"counterparty_name": "PODJETJE 8834 D.O.O.",
"counterparty_iban": "SI56299536963735251",
"counterparty_bic": "KBMASI2XXXX",
"reference": "2026-00023",
"description": "To PODJETJE 8834 D.O.O.",
"transaction_type": "TRANSFER",
"account_iban": "LT000000000000000001",
"is_fee_candidate": true,
"match_status": "resolved_fee",
"payment_id": null,
"ledger_account_code": null,
"ledger_related_party": false,
"ledger_contact_id": null,
"ledger_memo": null,
"created_at": "2026-08-31T10:00:00.000Z",
"raw": {
"ID": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"Amount": "-4000.00"
},
"match": {
"payment_id": null,
"document_type": "expense",
"document_id": "exp_5a6b7c8d9e0f1a2b",
"document_number": "2026-00088",
"is_fee": true,
"suggested_documents": []
}
}Categorize a bank transaction to a ledger account
/bank-transactions/{id}/categorizeUS entities only (403 for other countries). For a bank transaction that is not a document payment (a Stripe payout, an owner loan, a Delaware franchise tax payment, interest): moves it to resolved_account and stores the counter-account (account_code), the optional related_party flag (foreign shareholder, Form 5472), contact_id (a contact of this entity, for 1099-NEC attribution) and memo. account_code cannot be the ledger_account_code of the transaction's import (422), nor 1000 for a payout row of an import whose ledger_account_code is not 1000 (422). A transaction in a currency other than the entity's is refused with 422. Only valid from unmatched or suggested; any other status is 409. Undo it with the unlink action, which returns the row to unmatched and clears the ledger fields.
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
Body parameters
Account code from the US chart of accounts (GET /ledger/accounts).
Possible values: "1000", "1050", "1100", "1300", "1400", "1500", "1510", "1900", "2000", "2100", "2200", "2300", "2400", "2500", "2700", "2800", "3000", "3100", "3200", "3300", "4000", "4500", "4800", "4900", "5000", "5100", "5200", "6000", "6100", "6150", "6200", "6250", "6300", "6400", "6500", "6550", "6600", "6700", "6800", "6810", "6820", "6830", "6840", "6850", "6990", "7000", "7900", "8000"
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.categorizeBankTransaction('pay_6595a27b5d35015c3ef0c3fd', {
account_code: "1050",
related_party: false,
contact_id: null,
memo: "Stripe payout, July"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "banktxn_abc123",
"entity_id": "ent_abc123",
"import_id": "bankimport_abc123",
"source_format": "revolut_csv",
"bank_transaction_ref": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"booking_date": "2026-08-31",
"value_date": "2026-08-31",
"amount": 4210.55,
"currency_code": "USD",
"fee_amount": null,
"counterparty_name": "PODJETJE 8834 D.O.O.",
"counterparty_iban": "SI56299536963735251",
"counterparty_bic": "KBMASI2XXXX",
"reference": "2026-00023",
"description": "To PODJETJE 8834 D.O.O.",
"transaction_type": "TRANSFER",
"account_iban": "LT000000000000000001",
"is_fee_candidate": false,
"match_status": "resolved_account",
"payment_id": null,
"ledger_account_code": "1050",
"ledger_related_party": false,
"ledger_contact_id": null,
"ledger_memo": "Stripe payout, July",
"created_at": "2026-08-31T10:00:00.000Z",
"raw": {
"ID": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"Amount": "-4000.00"
},
"match": {
"payment_id": null,
"document_type": null,
"document_id": null,
"document_number": null,
"is_fee": false,
"suggested_documents": []
}
}Ignore a bank transaction
/bank-transactions/{id}/ignoreMoves the transaction to ignored. Only valid from unmatched or suggested; any other status is 409.
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.ignoreBankTransaction('pay_6595a27b5d35015c3ef0c3fd', {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "banktxn_abc123",
"entity_id": "ent_abc123",
"import_id": "bankimport_abc123",
"source_format": "revolut_csv",
"bank_transaction_ref": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"booking_date": "2026-08-31",
"value_date": "2026-08-31",
"amount": -4000,
"currency_code": "EUR",
"fee_amount": null,
"counterparty_name": "PODJETJE 8834 D.O.O.",
"counterparty_iban": "SI56299536963735251",
"counterparty_bic": "KBMASI2XXXX",
"reference": "2026-00023",
"description": "To PODJETJE 8834 D.O.O.",
"transaction_type": "TRANSFER",
"account_iban": "LT000000000000000001",
"is_fee_candidate": false,
"match_status": "ignored",
"payment_id": null,
"ledger_account_code": null,
"ledger_related_party": false,
"ledger_contact_id": null,
"ledger_memo": null,
"created_at": "2026-08-31T10:00:00.000Z",
"raw": {
"ID": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"Amount": "-4000.00"
},
"match": {
"payment_id": null,
"document_type": null,
"document_id": null,
"document_number": null,
"is_fee": false,
"suggested_documents": []
}
}Undo a link, auto-match, confirmed fee, or ledger categorization
/bank-transactions/{id}/unlinkDeletes the payment created for this transaction (and, for a confirmed fee, voids the expense created with it) and returns the transaction to unmatched. If voiding the fee expense fails, the unlink is undone, the transaction stays resolved_fee and the request fails with 500 so it can be retried. For a resolved_account row (see categorize) it clears the ledger fields instead, which removes its general-ledger posting. Only valid from auto_matched, resolved_link, resolved_fee, or resolved_account; any other status is 409.
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.payments.unlinkBankTransaction('pay_6595a27b5d35015c3ef0c3fd', {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "banktxn_abc123",
"entity_id": "ent_abc123",
"import_id": "bankimport_abc123",
"source_format": "revolut_csv",
"bank_transaction_ref": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"booking_date": "2026-08-31",
"value_date": "2026-08-31",
"amount": -4000,
"currency_code": "EUR",
"fee_amount": null,
"counterparty_name": "PODJETJE 8834 D.O.O.",
"counterparty_iban": "SI56299536963735251",
"counterparty_bic": "KBMASI2XXXX",
"reference": "2026-00023",
"description": "To PODJETJE 8834 D.O.O.",
"transaction_type": "TRANSFER",
"account_iban": "LT000000000000000001",
"is_fee_candidate": false,
"match_status": "unmatched",
"payment_id": null,
"ledger_account_code": null,
"ledger_related_party": false,
"ledger_contact_id": null,
"ledger_memo": null,
"created_at": "2026-08-31T10:00:00.000Z",
"raw": {
"ID": "6a9572dd-e589-a2ed-ae68-0a29bb6dd5e5",
"Amount": "-4000.00"
},
"match": {
"payment_id": null,
"document_type": null,
"document_id": null,
"document_number": null,
"is_fee": false,
"suggested_documents": []
}
}