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
| Method | Endpoint | Description |
|---|---|---|
| GET | /payment-requests | List payment requests |
| GET | /payment-requests/{id} | Get a specific payment request |
| POST | /payment-requests | Create a payment request |
Query Parameters
The GET /payment-requests endpoint supports the following query parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | Yes | Filter by client account ID. Must be one of the user’s eligible client accounts |
| page | integer | No | Page number for pagination |
| per_page | integer | No | Number of items per page |
Payment Request Attributes
| Attribute | Type | Description |
|---|---|---|
| id | integer | The unique identifier of the payment request |
| created_at | datetime | When the request was created |
| created_by_id | integer | The ID of the user who created the request |
| client_account_id | integer | The ID of the client account |
| payment_type | string | The type of payment |
| payment_means | string | The means of payment |
| payment_status | string | The current status of the payment |
| rejection_code | string | Code indicating reason for rejection, if applicable |
| rejection_message | string | Detailed message about rejection, if applicable |
Payment Transfer Attributes
Each payment request can include one or more transfers with the following attributes:
| Attribute | Type | Description |
|---|---|---|
| id | integer | The unique identifier of the transfer |
| created_at | datetime | When the transfer was created |
| created_by_id | integer | The ID of the user who created the transfer |
| requested_transfer_date | date | The requested date for the transfer |
| payment_status | string | The current status of the transfer |
| rejection_code | string | Code indicating reason for rejection, if applicable |
| rejection_message | string | Detailed message about rejection, if applicable |
| booking_date | date | The date the transfer was booked |
| booking_reference | string | Reference number for the booking |
| amount | decimal | The transfer amount |
| currency_code | string | The currency code of the transfer |
| exchange_rate | decimal | The exchange rate used |
| creditor_reference | string | Reference for the creditor |
Relationships
| Relationship | Type | Description |
|---|---|---|
| transfers | [PaymentTransfer] | The transfers included in this payment request |
| transfers[].debtor | [BankAccount, BusinessPartner] | The debtor’s bank account and business partner details |
| transfers[].creditor | [BankAccount, BusinessPartner] | The creditor’s bank account and business partner details |
| transfers[].reconciliation_entries | [PaymentReconciliationEntry] | Reconciliation entries for the transfer |
| transfers[].account_entries | [PaymentAccountEntry] | Account entries for the transfer |
Example Response
{
"id": 1,
"created_at": "2023-05-10T12:00:00Z",
"created_by_id": 1,
"client_account_id": 1,
"payment_type": "CREDIT_TRANSFER",
"payment_means": "SEPA",
"payment_status": "PENDING",
"rejection_code": null,
"rejection_message": null,
"transfers": [
{
"id": 1,
"created_at": "2023-05-10T12:00:00Z",
"created_by_id": 1,
"requested_transfer_date": "2023-05-11",
"payment_status": "PENDING",
"rejection_code": null,
"rejection_message": null,
"booking_date": null,
"booking_reference": null,
"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": []
}
]
}
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.
- The payment request will be processed according to the specified payment_type and payment_means.
- Each transfer in the request can have its own status and rejection information.
- 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.