[FEAT]: Allow USERS and ORGANIZATIONS to make payment using PAYSTACK

[sir-mills]

Description:

Implement payment functionality using Stripe to allow both individual users and organizations to make payments through our platform. This feature would handle the entire payment process, including initiating the payment and processing it.

Acceptance Criteria

The API should be accessible at POST /api/v1/payments/initiate
Endpoint is accessible only to authenticated users.
Only users with appropriate permissions can initiate payments.
Sanitize and validate all input data to prevent injection attacks.
Data is transmitted over HTTPS, and sensitive information is handled securely.
Write unit and integration tests for the payments logic.
Provide clear and comprehensive documentation for the endpoint, including request and response formats, error codes, and usage examples.
Request Examples:

POST /api/v1/payments/initiate [PROTECTED]

Request Body:

{
   "payer_type" : "user" | "organization",  // Type of the payer (e.g., user or organization)
   "payer_id" : "[email protected]",
   "amount":  49.99,
   "currency" : "NGN"
}

Response Example:

Success Response:

Status Code: 200 OK

Response Body:

{ "payment_id" : "abc_123", // Unique identifier for the payment "status" : "pending", // Status of the payment (initial status) "payment_url" : "https://example.com/checkout?paymentId=pay_abc123" // URL to complete the payment }
Failure Responses:

Validation Error:

Status Code: 400 Bad Request

Response Body:

{ "error" : "Bad Request", "message" : "Validation error: amount must be a positive number", "status_code" : 400 }
Authentication Error:

Status Code: 401 Unauthorized

Response Body:

{ "error" : "Unauthorized", "message" : "Authentication required", "status_code" : 401 }
Authorization Error:

Status Code: 403 Forbidden

Response Body:

{ "error": "Forbidden", "message" : "You do not have permission to initiate this payment", "status_code" : 403 }
Server Error:

Status Code: 500 Internal Server Error

Response Body:

{ "error": "Internal Server Error", "message": "An unexpected error occurred. Please try again later.", "status_code" : 500 }
Data Validation

Input Validation:

Confirm that all fields are provided and valid.
Example: If user_id is invalid or missing, return a 400 status code with an error message.
{ "error" : "Bad Request", "message" : "Validation error: user_id must be provided", "status_code" : 400 }
Authentication and Authorization

Authentication:

Verify that the user is authenticated before allowing access to the endpoint.
Example: Use middleware to check for a valid authentication token.
Authorization:

Ensure that only authorized users can make payments.
Example: Check user roles or permissions to confirm authorization.
Error Handling

Error Responses:

Define error responses for common failure scenarios.
Example: If Stripe credentials are invalid, return a 500 status code with an error message.
{ "error" : "Payment Initialization Failed", "message" : "Failed to initialize payment with paystack: Invalid API key", "status_code" : 502 }
Documentation

API Documentation:

Ensure that API documentation is updated to include details about the new endpoint, request/response formats, error handling, and authentication requirements.

Testing Requirements

Unit Tests:

Write unit tests to validate input data and payment logic.
Integration Tests:

Ensure end-to-end functionality is tested with integration tests.