Payment Requests

Payment requests represent instructions to transfer money between bank accounts. They can involve single or multiple transfers, and support various payment types and means.

Endpoints

Query Parameters

The GET /payment-requests endpoint supports the following query parameters:

Results are always ordered newest first (by id descending).

GET /payment-requests/{id} takes the same client_account_id and with parameters. client_account_id is required there too — the request is looked up within that client account, and a missing or inaccessible one answers 403.

Payment Request Attributes

Payment Status Values

Payment Transfer Attributes

Each payment request can include one or more transfers with the following attributes:

Relationships

Include these with the with query parameter. Nothing below is returned by default — a payment request without with=transfers is just the eight attributes above.

Once transfers is included, each transfer always carries debtor and creditor objects with their bank_account_id/business_partner_id, plus the reconciliation_entries and account_entries arrays — those three need no further with.

Example Response

Requested with ?with=transfers,transfers.debtor.bank_account,transfers.debtor.business_partner,transfers.creditor.bank_account,transfers.creditor.business_partner.

{
    "id": 1,
    "created_at": "2023-05-10T12:00:00+00:00",
    "created_by_id": 1,
    "client_account_id": 1,
    "payment_means": "SEPA",
    "payment_status": "SCHEDULED",
    "rejection_code": null,
    "rejection_message": null,
    "transfers": [
        {
            "id": 1,
            "created_at": "2023-05-10T12:00:00+00:00",
            "created_by_id": 1,
            "requested_transfer_date": "2023-05-11",
            "payment_type": "CREDIT_TRANSFER",
            "payment_status": "SCHEDULED",
            "rejection_code": null,
            "rejection_message": null,
            "booking_date": null,
            "booking_reference": null,
            "amount": 1000.0,
            "currency_code": "EUR",
            "exchange_rate": 1.0,
            "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": []
        }
    ]
}

Notes

• The client_account_id must be one of the eligible client accounts for the authenticated user.
• When creating a payment request, the created_by_id is automatically set to the authenticated user’s ID.
• POST /payment-requests reads only client_account_id, payment_means, payment_type and transfers from the body. Any other field is ignored rather than rejected.
• The payment request will be processed according to the specified payment_type and payment_means.
• payment_type is accepted in the request body when creating a payment request, but it is not echoed back on the top-level payment request object — only payment_means is returned there. Each transfer under transfers[] does return its own payment_type, which is derived server-side from the transfer’s account entries and may differ from the value submitted in the request (e.g. it becomes MIXED when a transfer combines multiple payment types).
• Each transfer in the request can have its own status and rejection information.
• Bank account and business partner relations are expanded with the with query parameter (with=transfers.debtor.bank_account), not with_relations.
• Amounts are returned as JSON numbers, not strings. Send them as numbers or as decimal strings; both are accepted on write.
• Dates are ISO 8601 (YYYY-MM-DD); timestamps are ISO 8601 with a UTC offset (2023-05-10T12:00:00+00:00).