Posted Payments

Posted payments represent completed payment transactions in the system. They include details about the payment source and the actual transfer of funds.

A posted payment can also be a draft: a proposal (typically from Snapbooks automation for a bank transaction) that stores the transfer, account entries and reconciliation entries but has not been booked. A draft creates no journal entry, no reconciliation and no document status change, and its transfer stays at payment_status NONE until it is booked with PATCH /payments/{id}.

Endpoints

Query Parameters

The GET /payments endpoint supports the following query parameters:

Create Posted Payment

POST /api/v2/payments

Creates a posted payment (or, with "is_draft": true, a draft proposal — see the note on drafts above).

Request Body

Example Request

{
  "client_account_id": 1,
  "source_type": "INVOICE",
  "source_id": 123,
  "memo": "Invoice payment",
  "transfer": {
    "payment_type": "CREDIT_TRANSFER",
    "amount": "1000.00",
    "currency_code": "EUR",
    "requested_transfer_date": "2023-05-11",
    "debtor": { "bank_account_id": 1 },
    "creditor": { "bank_account_id": 2 },
    "reconciliation_entries": [
      {
        "relation_type": "ARINV",
        "relation_id": 123,
        "amount": "1000.00",
        "currency_code": "EUR"
      }
    ]
  }
}

Response

Returns the created posted payment with status 201 Created. See Attributes below.

Attributes

Payment Transfer

Each posted payment includes a transfer with the following attributes:

Relationships

Example Response

{
    "id": 1,
    "client_account_id": 1,
    "source_type": "INVOICE",
    "source_id": 123,
    "source_line_id": 456,
    "memo": "Invoice payment",
    "transfer": {
        "id": 1,
        "created_at": "2023-05-10T12:00:00Z",
        "created_by_id": 1,
        "requested_transfer_date": "2023-05-11",
        "payment_type": "CREDIT_TRANSFER",
        "payment_status": "COMPLETED",
        "rejection_code": null,
        "rejection_message": null,
        "booking_date": "2023-05-11",
        "booking_reference": "REF123",
        "amount": "1000.00",
        "currency_code": "EUR",
        "exchange_rate": "1.0000",
        "creditor_reference": "INV123",
        "debtor": {
            "bank_account_id": 1,
            "business_partner_id": 1,
            "bank_account": {
                "id": 1,
                "account_number": "DE89370400440532013000"
            },
            "business_partner": {
                "id": 1,
                "name": "ACME Corp"
            }
        },
        "creditor": {
            "bank_account_id": 2,
            "business_partner_id": 2,
            "bank_account": {
                "id": 2,
                "account_number": "FR7630006000011234567890189"
            },
            "business_partner": {
                "id": 2,
                "name": "Supplier Inc"
            }
        },
        "reconciliation_entries": [],
        "account_entries": []
    }
}

Booking and discarding drafts

PATCH /payments/{id} accepts only {"is_draft": false}. Booking re-validates the proposal against the current ledger and then posts it exactly like a direct POST: the journal entry, reconciliation, external reconciliation and document status changes are created at that point, and created_by_id is kept, so a draft booked unchanged stays attributed to automation. Responses:

DELETE /payments/{id} removes a draft and returns 204. It returns 400 for a booked payment.

Notes

• The client_account_id must be one of the eligible client accounts for the authenticated user.
• When creating a posted payment, the created_by_id is automatically set to the authenticated user’s ID.
• The source_type and source_id fields help track the origin of the payment (e.g., an invoice or other document).
• Bank account and business partner relationships can be included by specifying them in the with_relations parameter.
• All amounts are returned as string representations of decimal numbers.
• Dates are returned in ISO 8601 format.
• The source_type filter accepts a single value; it is not a list parameter.