Payment Methods and Recurring Payments API

This document provides information about the Payment Methods and Recurring Payments API endpoints in the UBU Finance backend.

Payment Methods Endpoints

List Payment Methods

Retrieves a list of payment methods with optional filtering.

Endpoint: GET /api/payments/methods

Query Parameters:

Parameter	Type	Description
method_id	UUID	Filter by payment method ID
method_name	string	Filter by method name
method_type	string	Filter by method type
is_active	boolean	Filter by active status (true/false)

Response:

{
  "items": [
    {
      "method_id": "550e8400-e29b-41d4-a716-446655440004",
      "method_name": "Bank Transfer",
      "method_type": "electronic",
      "description": "Direct bank-to-bank transfer",
      "is_active": true,
      "created_at": "2025-01-01T12:00:00Z",
      "updated_at": "2025-01-01T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10,
  "pages": 1
}

Get Payment Method

Retrieves details of a specific payment method.

Endpoint: GET /api/payments/methods/{method_id}

Path Parameters:

Parameter	Type	Description
method_id	UUID	The ID of the payment method to retrieve

Response:

{
  "method_id": "550e8400-e29b-41d4-a716-446655440004",
  "method_name": "Bank Transfer",
  "method_type": "electronic",
  "description": "Direct bank-to-bank transfer",
  "is_active": true,
  "created_at": "2025-01-01T12:00:00Z",
  "updated_at": "2025-01-01T12:00:00Z"
}

Create Payment Method

Creates a new payment method.

Endpoint: POST /api/payments/methods

Request Body:

{
  "method_name": "Credit Card",
  "method_type": "card",
  "description": "Credit card payment processing"
}

Response:

{
  "method_id": "550e8400-e29b-41d4-a716-446655440006",
  "method_name": "Credit Card",
  "method_type": "card",
  "description": "Credit card payment processing",
  "is_active": true,
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-15T12:00:00Z"
}

Update Payment Method

Updates an existing payment method.

Endpoint: PUT /api/payments/methods/{method_id}

Path Parameters:

Parameter	Type	Description
method_id	UUID	The ID of the payment method to update

Request Body:

{
  "method_name": "Credit Card (Updated)",
  "description": "Updated credit card payment processing",
  "is_active": true
}

Response:

{
  "method_id": "550e8400-e29b-41d4-a716-446655440006",
  "method_name": "Credit Card (Updated)",
  "method_type": "card",
  "description": "Updated credit card payment processing",
  "is_active": true,
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-15T12:10:00Z"
}

Recurring Payments Endpoints

List Recurring Payments

Retrieves a list of recurring payments with optional filtering.

Endpoint: GET /api/payments/recurring

Query Parameters:

Parameter	Type	Description
recurring_id	UUID	Filter by recurring payment ID
payer_id	UUID	Filter by payer ID
payee_id	UUID	Filter by payee ID
source_account_id	UUID	Filter by source account ID
destination_account_id	UUID	Filter by destination account ID
payment_method_id	UUID	Filter by payment method ID
status	string	Filter by payment status
frequency	string	Filter by payment frequency
min_amount	decimal	Filter by minimum amount
max_amount	decimal	Filter by maximum amount
currency	string	Filter by currency code
created_after	datetime	Filter by creation date (after)
created_before	datetime	Filter by creation date (before)
next_payment_after	datetime	Filter by next payment date (after)
next_payment_before	datetime	Filter by next payment date (before)

Response:

{
  "items": [
    {
      "recurring_id": "550e8400-e29b-41d4-a716-446655440005",
      "reference_number": "REC-12345",
      "payer_id": "550e8400-e29b-41d4-a716-446655440010",
      "payee_id": "550e8400-e29b-41d4-a716-446655440011",
      "amount": 500.00,
      "currency": "RWF",
      "payment_method": "bank_transfer",
      "source_account_id": "550e8400-e29b-41d4-a716-446655440002",
      "destination_account_id": "550e8400-e29b-41d4-a716-446655440003",
      "description": "Monthly rent payment",
      "frequency": "monthly",
      "status": "active",
      "start_date": "2025-02-01",
      "end_date": "2025-12-31",
      "next_payment_date": "2025-02-01",
      "created_at": "2025-01-15T12:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10,
  "pages": 1
}

Get User Recurring Payments

Retrieves a list of recurring payments for a specific user with optional filtering.

Endpoint: GET /api/payments/recurring/user/{user_id}

Path Parameters:

Parameter	Type	Description
user_id	UUID	The ID of the user

Query Parameters:

Parameter	Type	Description
recurring_id	UUID	Filter by recurring payment ID
source_account_id	UUID	Filter by source account ID
destination_account_id	UUID	Filter by destination account ID
payment_method_id	UUID	Filter by payment method ID
status	string	Filter by payment status
frequency	string	Filter by payment frequency
min_amount	decimal	Filter by minimum amount
max_amount	decimal	Filter by maximum amount
currency	string	Filter by currency code
created_after	datetime	Filter by creation date (after)
created_before	datetime	Filter by creation date (before)
next_payment_after	datetime	Filter by next payment date (after)
next_payment_before	datetime	Filter by next payment date (before)

Response:

{
  "items": [
    {
      "recurring_id": "550e8400-e29b-41d4-a716-446655440005",
      "reference_number": "REC-12345",
      "payer_id": "550e8400-e29b-41d4-a716-446655440010",
      "payee_id": "550e8400-e29b-41d4-a716-446655440011",
      "amount": 500.00,
      "currency": "RWF",
      "payment_method": "bank_transfer",
      "source_account_id": "550e8400-e29b-41d4-a716-446655440002",
      "destination_account_id": "550e8400-e29b-41d4-a716-446655440003",
      "description": "Monthly rent payment",
      "frequency": "monthly",
      "status": "active",
      "start_date": "2025-02-01",
      "end_date": "2025-12-31",
      "next_payment_date": "2025-02-01",
      "created_at": "2025-01-15T12:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10,
  "pages": 1
}

Get Recurring Payment

Retrieves details of a specific recurring payment.

Endpoint: GET /api/payments/recurring/{recurring_id}

Path Parameters:

Parameter	Type	Description
recurring_id	UUID	The ID of the recurring payment to retrieve

Response:

{
  "recurring_id": "550e8400-e29b-41d4-a716-446655440005",
  "reference_number": "REC-12345",
  "payer_id": "550e8400-e29b-41d4-a716-446655440010",
  "payee_id": "550e8400-e29b-41d4-a716-446655440011",
  "amount": 500.00,
  "currency": "RWF",
  "payment_method": "bank_transfer",
  "source_account_id": "550e8400-e29b-41d4-a716-446655440002",
  "destination_account_id": "550e8400-e29b-41d4-a716-446655440003",
  "description": "Monthly rent payment",
  "frequency": "monthly",
  "status": "active",
  "start_date": "2025-02-01",
  "end_date": "2025-12-31",
  "next_payment_date": "2025-02-01",
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-15T12:00:00Z"
}

Create Recurring Payment

Creates a new recurring payment.

Endpoint: POST /api/payments/recurring

Request Body:

{
  "user_id": "550e8400-e29b-41d4-a716-446655440010",
  "amount": 500.00,
  "currency": "RWF",
  "payment_method": "bank_transfer",
  "source_account_id": "550e8400-e29b-41d4-a716-446655440002",
  "destination_account_id": "550e8400-e29b-41d4-a716-446655440003",
  "description": "Monthly rent payment",
  "frequency": "monthly",
  "start_date": "2025-02-01",
  "end_date": "2025-12-31"
}

Response:

{
  "recurring_id": "550e8400-e29b-41d4-a716-446655440005",
  "reference_number": "REC-12345",
  "payer_id": "550e8400-e29b-41d4-a716-446655440010",
  "payee_id": "550e8400-e29b-41d4-a716-446655440011",
  "amount": 500.00,
  "currency": "RWF",
  "payment_method": "bank_transfer",
  "source_account_id": "550e8400-e29b-41d4-a716-446655440002",
  "destination_account_id": "550e8400-e29b-41d4-a716-446655440003",
  "description": "Monthly rent payment",
  "frequency": "monthly",
  "status": "active",
  "start_date": "2025-02-01",
  "end_date": "2025-12-31",
  "next_payment_date": "2025-02-01",
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-15T12:00:00Z"
}

Update Recurring Payment

Updates an existing recurring payment.

Endpoint: PUT /api/payments/recurring/{recurring_id}

Path Parameters:

Parameter	Type	Description
recurring_id	UUID	The ID of the recurring payment to update

Request Body:

{
  "amount": 550.00,
  "description": "Updated monthly rent payment",
  "end_date": "2026-01-31"
}

Response:

{
  "recurring_id": "550e8400-e29b-41d4-a716-446655440005",
  "reference_number": "REC-12345",
  "payer_id": "550e8400-e29b-41d4-a716-446655440010",
  "payee_id": "550e8400-e29b-41d4-a716-446655440011",
  "amount": 550.00,
  "currency": "RWF",
  "payment_method": "bank_transfer",
  "source_account_id": "550e8400-e29b-41d4-a716-446655440002",
  "destination_account_id": "550e8400-e29b-41d4-a716-446655440003",
  "description": "Updated monthly rent payment",
  "frequency": "monthly",
  "status": "active",
  "start_date": "2025-02-01",
  "end_date": "2026-01-31",
  "next_payment_date": "2025-02-01",
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-15T12:10:00Z"
}

Cancel Recurring Payment

Cancels an existing recurring payment.

Endpoint: DELETE /api/payments/recurring/{recurring_id}

Path Parameters:

Parameter	Type	Description
recurring_id	UUID	The ID of the recurring payment to cancel

Response:

{
  "recurring_id": "550e8400-e29b-41d4-a716-446655440005",
  "status": "cancelled",
  "updated_at": "2025-01-15T12:15:00Z"
}

Security Considerations

• All Payment Methods and Recurring Payments API endpoints are protected by authentication
• Sensitive operations require appropriate permissions
• All requests are logged for audit purposes
• IP whitelisting is enforced for payment operations
• Rate limiting is applied to prevent abuse
• Account lockout is triggered after multiple failed payment attempts

For more information on security features, see the Security Overview.