Payment Sources

Payment sources define the methods and accounts through which payments are received from customers. Each payment source represents a specific payment channel (e.g., bank transfer, credit card, cash) and is linked to a financial account for proper accounting integration.

Overview

Payment sources are essential for tracking where payments come from and ensuring they are posted to the correct accounts in your financial system. When a payment is received, it must be associated with a payment source that determines how the payment is recorded in the general ledger.

Payment Source Types

The system supports the following payment source types:

• BankTransfer - Direct bank transfers and wire payments
• CreditCard - Credit card payments
• DebitCard - Debit card payments
• Cash - Cash payments
• Check - Check payments
• DirectDebit - Direct debit/SEPA payments
• PayPal - PayPal payments
• Other - Other payment methods

Endpoints

List Payment Sources

GET /payment-sources

Returns a list of all payment sources. Supports OData query parameters for filtering and sorting.

Query Parameters:

• $filter - OData filter expression (e.g., isActive eq true)
• $orderby - Sort order (e.g., name asc)
• $top - Number of records to return
• $skip - Number of records to skip
• $count - Include total count in response

Example Request:

GET /payment-sources?$filter=isActive eq true&$orderby=name asc

Example Response:

{
  "value": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "code": "BANK-001",
      "name": "Main Bank Account",
      "description": "Primary bank account for student payments",
      "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "sourceType": "BankTransfer",
      "isActive": true,
      "isDefault": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "createdById": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "updatedAt": "2024-01-20T14:22:00Z",
      "updatedById": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
    }
  ],
  "@odata.count": 1
}

Get Payment Source by ID

GET /payment-sources/{id}

Retrieves a single payment source by its unique identifier.

Path Parameters:

• id (UUID, required) - The payment source ID

Example Request:

GET /payment-sources/3fa85f64-5717-4562-b3fc-2c963f66afa6

Example Response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code": "BANK-001",
  "name": "Main Bank Account",
  "description": "Primary bank account for student payments",
  "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sourceType": "BankTransfer",
  "isActive": true,
  "isDefault": true,
  "createdAt": "2024-01-15T10:30:00Z",
  "createdById": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "updatedAt": "2024-01-20T14:22:00Z",
  "updatedById": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

Create Payment Source

POST /payment-sources

Creates a new payment source.

Request Body:

{
  "code": "CC-001",
  "name": "Credit Card Processor",
  "description": "Stripe credit card payments",
  "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sourceType": "CreditCard",
  "isActive": true,
  "isDefault": false
}

Response: 201 Created

{
  "id": "8e9b7c2a-1234-5678-9abc-def012345678",
  "code": "CC-001",
  "name": "Credit Card Processor",
  "description": "Stripe credit card payments",
  "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sourceType": "CreditCard",
  "isActive": true,
  "isDefault": false,
  "createdAt": "2024-01-25T09:15:00Z",
  "createdById": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "updatedAt": null,
  "updatedById": null
}

Update Payment Source

PUT /payment-sources/{id}

Updates an existing payment source.

Path Parameters:

• id (UUID, required) - The payment source ID

Request Body:

{
  "code": "CC-001",
  "name": "Credit Card Processor - Updated",
  "description": "Stripe and PayPal credit card payments",
  "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sourceType": "CreditCard",
  "isActive": true,
  "isDefault": false
}

Response: 200 OK

Delete Payment Source

DELETE /payment-sources/{id}

Deletes a payment source. Only payment sources with no associated payments can be deleted.

Path Parameters:

• id (UUID, required) - The payment source ID

Response: 204 No Content

Response Schema

Field	Type	Description
id	UUID	Unique identifier
code	string	Payment source code (e.g., "BANK-001")
name	string	Payment source name
description	string	Optional description
accountId	UUID	Associated financial account ID
sourceType	enum	Payment source type (BankTransfer, CreditCard, etc.)
isActive	boolean	Whether the payment source is active
isDefault	boolean	Whether this is the default payment source
createdAt	datetime	Creation timestamp
createdById	UUID	ID of user who created the record
updatedAt	datetime	Last update timestamp
updatedById	UUID	ID of user who last updated the record

Business Rules

1. Unique Codes: Payment source codes must be unique across the system
2. Default Source: Only one payment source can be marked as default
3. Active Accounts: The associated account must be active and of type Asset
4. Deletion: Payment sources cannot be deleted if they have associated payments
5. Audit Trail: All create and update operations are tracked with user IDs and timestamps

Common Use Cases

Finding Active Payment Sources

GET /payment-sources?$filter=isActive eq true

Getting the Default Payment Source

GET /payment-sources?$filter=isDefault eq true

Filtering by Source Type

GET /payment-sources?$filter=sourceType eq 'BankTransfer'

Integration Notes

• Payment sources must be configured before payments can be recorded
• Each payment source is linked to a financial account for proper GL posting
• The default payment source is automatically selected when creating new payments
• Inactive payment sources cannot be used for new payments but remain visible for historical records