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.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "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.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
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.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "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.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "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
}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
{
"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
}
}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.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "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
}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.
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.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "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.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "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.
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.
Possible values: "cash", "bank_transfer", "card", "credit_card", "debit_card", "check", "paypal", "coupon", "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
}