dbis_core-lite/docs/api/reference.md

API Documentation

Authentication

All API endpoints (except /api/auth/login) require authentication via JWT token in the Authorization header:

Authorization: Bearer <token>

Endpoints

Authentication

POST /api/auth/login

Operator login.

Request Body:

{
  "operatorId": "string",
  "password": "string",
  "terminalId": "string" (optional)
}

Response:

{
  "token": "string",
  "operator": {
    "id": "string",
    "operatorId": "string",
    "name": "string",
    "role": "MAKER" | "CHECKER" | "ADMIN"
  }
}

POST /api/auth/logout

Operator logout.

Headers: Authorization: Bearer <token>

Response:

{
  "message": "Logged out successfully"
}

GET /api/auth/me

Get current operator information.

Headers: Authorization: Bearer <token>

Response:

{
  "id": "string",
  "operatorId": "string",
  "name": "string",
  "role": "MAKER" | "CHECKER" | "ADMIN"
}

Payments

POST /api/payments

Initiate payment (Maker role required).

Headers: Authorization: Bearer <token>

Request Body:

{
  "type": "CUSTOMER_CREDIT_TRANSFER" | "FI_TO_FI",
  "amount": 1234.56,
  "currency": "USD" | "EUR" | "GBP" | "JPY",
  "senderAccount": "string",
  "senderBIC": "string",
  "receiverAccount": "string",
  "receiverBIC": "string",
  "beneficiaryName": "string",
  "purpose": "string" (optional),
  "remittanceInfo": "string" (optional)
}

Response:

{
  "paymentId": "string",
  "status": "PENDING_APPROVAL",
  "message": "Payment initiated, pending approval"
}

POST /api/payments/:id/approve

Approve payment (Checker role required).

Headers: Authorization: Bearer <token>

Response:

{
  "message": "Payment approved and processing",
  "paymentId": "string"
}

POST /api/payments/:id/reject

Reject payment (Checker role required).

Headers: Authorization: Bearer <token>

Request Body:

{
  "reason": "string" (optional)
}

Response:

{
  "message": "Payment rejected",
  "paymentId": "string"
}

GET /api/payments/:id

Get payment status.

Headers: Authorization: Bearer <token>

Response:

{
  "paymentId": "string",
  "status": "string",
  "amount": 1234.56,
  "currency": "USD",
  "uetr": "string" | null,
  "ackReceived": false,
  "settlementConfirmed": false,
  "createdAt": "2024-01-01T00:00:00Z"
}

GET /api/payments

List payments.

Headers: Authorization: Bearer <token>

Query Parameters:

• limit (optional, default: 50)
• offset (optional, default: 0)

Response:

{
  "payments": [
    {
      "id": "string",
      "payment_id": "string",
      "type": "string",
      "amount": 1234.56,
      "currency": "USD",
      "status": "string",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 10
}

Reconciliation

GET /api/reconciliation/daily

Generate daily reconciliation report (Checker role required).

Headers: Authorization: Bearer <token>

Query Parameters:

• date (optional, ISO date string, default: today)

Response:

{
  "report": "string (formatted text report)",
  "date": "2024-01-01"
}

GET /api/reconciliation/aging

Get aging items (Checker role required).

Headers: Authorization: Bearer <token>

Query Parameters:

• days (optional, default: 1)

Response:

{
  "items": [
    {
      "id": "string",
      "payment_id": "string",
      "amount": 1234.56,
      "currency": "USD",
      "status": "string",
      "created_at": "2024-01-01T00:00:00Z",
      "aging_reason": "string"
    }
  ],
  "count": 5
}

Health Check

GET /health

Health check endpoint.

Response:

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00Z"
}

Error Responses

All endpoints may return error responses:

{
  "error": "Error message"
}

Status codes:

• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 500 - Internal Server Error

Payment Status Flow

1. INITIATED - Payment created by Maker
2. PENDING_APPROVAL - Awaiting Checker approval
3. APPROVED - Approved by Checker
4. COMPLIANCE_CHECKING - Under compliance screening
5. COMPLIANCE_PASSED - Screening passed
6. LEDGER_POSTED - Funds reserved in ledger
7. MESSAGE_GENERATED - ISO 20022 message created
8. TRANSMITTED - Message sent via TLS
9. ACK_RECEIVED - Acknowledgment received
10. SETTLED - Settlement confirmed
11. FAILED - Processing failed
12. CANCELLED - Rejected/cancelled