Revolut Merchant Payment Management System (Backend API)

A production-ready RESTful API backend built with Node.js, Express, TypeScript, and MongoDB (Mongoose). This payment management system simulates core Revolut Merchant API capabilities, including payment order creation, payment processing simulation, status lookups, refund management, and transaction history tracking.

---

🔗 Project Links

• Live API Endpoint (Vercel): https://codebyanas-payment-management.vercel.app
• GitHub Repository: https://github.com/codebyanas/payment-management-system

---

📌 Key Features

• TypeScript Architecture: Strong typing for Request/Response handlers, Mongoose schemas, and domain interfaces.
• PCI DSS Compliant Data Modeling: Storing non-sensitive payment metadata only (e.g., card brand, last 4 digits) without persisting sensitive raw card details.
• Configurable API Key Authentication: Middleware supporting dynamic enforcement of API Key authorization via environment variables (ENFORCE_API_AUTH).
• Serverless & Cloud Ready: Configured for seamless deployment on Vercel with automated build workflows.

---

🛠️ Postman Dynamic Environment Setup

To test seamlessly across environments, the API uses a dynamic {{backend_url}} variable in Postman. This allows switching instantly between Localhost (http://localhost:5000) and the Live Vercel Production URL (https://codebyanas-payment-management.vercel.app).

---

🚀 API Endpoints Overview

Method	Endpoint	Description	Auth Required
POST	/api/payments/create	Initialise a new payment order session	Configurable
POST	/api/payments/process/:orderId	Simulate Revolut API payment execution	Configurable
GET	/api/payments/status/:orderId	Retrieve complete order & payment status	Configurable
POST	/api/payments/refund/:orderId	Process full or partial order refund	Configurable
GET	/api/payments/history	Retrieve full transaction & order history	Configurable

---

🧪 Detailed API Endpoint Documentation

1. Create a Payment Order

Initialises a new checkout session, generates mock Revolut tokens, and stores the order in MongoDB with a PENDING state.

• Endpoint: POST /api/payments/create
• Headers: Content-Type: application/json

Request Body:

{
  "amountMinor": 10000,
  "currency": "GBP",
  "merchantOrderRef": "ORD-2026-005"
}

Response (201 Created):

{
  "success": true,
  "data": {
    "revolutOrderId": "b170fa46-9ac3-4052-8361-2ace15e61f87",
    "revolutPublicToken": "token_28811168-6d3a-4a7d-afab-842306f7d4eb",
    "merchantOrderRef": "ORD-2026-005",
    "amountMinor": 10000,
    "currency": "GBP",
    "status": "PENDING",
    "_id": "6a7c790a7598240b6968ac0e",
    "createdAt": "2026-08-12T13:45:46.145Z",
    "updatedAt": "2026-08-12T13:45:46.145Z"
  }
}

Postman Execution:

---

2. Process Payment

Simulates payment execution for an existing order ID, updates order state to COMPLETED, and saves PCI-compliant card metadata in the payments collection.

• Endpoint: POST /api/payments/process/:orderId
• Headers: Content-Type: application/json

Request Body:

{
  "paymentMethodType": "card",
  "cardBrand": "visa",
  "cardLastFour": "4242"
}

Response (200 OK):

{
  "success": true,
  "message": "Payment processed successfully",
  "data": {
    "_id": "66b1234567890abcdef12345",
    "orderId": "6a7c790a7598240b6968ac0e",
    "revolutPaymentId": "pay_998877665544332211",
    "paymentMethodType": "card",
    "cardBrand": "visa",
    "cardLastFour": "4242",
    "state": "COMPLETED",
    "createdAt": "2026-08-12T13:48:10.000Z",
    "updatedAt": "2026-08-12T13:48:10.000Z"
  }
}

Postman Execution:

---

3. Get Payment Status

Retrieves full details of a specific order along with all associated payment and refund records.

• Endpoint: GET /api/payments/status/:orderId

Response (200 OK):

{
  "success": true,
  "data": {
    "order": {
      "_id": "6a7c790a7598240b6968ac0e",
      "revolutOrderId": "b170fa46-9ac3-4052-8361-2ace15e61f87",
      "merchantOrderRef": "ORD-2026-005",
      "amountMinor": 10000,
      "currency": "GBP",
      "status": "COMPLETED"
    },
    "payments": [
      {
        "_id": "66b1234567890abcdef12345",
        "cardBrand": "visa",
        "cardLastFour": "4242",
        "state": "COMPLETED"
      }
    ],
    "refunds": []
  }
}

Postman Execution:

---

4. Process Refund

Initiates a partial or full refund for an order in COMPLETED status, updates order status to REFUNDED, and logs a record in the refunds collection.

• Endpoint: POST /api/payments/refund/:orderId
• Headers: Content-Type: application/json

Request Body:

{
  "refundAmountMinor": 10000
}

Response (200 OK):

{
  "success": true,
  "message": "Refund processed successfully",
  "data": {
    "refund": {
      "_id": "66c99887766554433221100",
      "originalOrderId": "6a7c790a7598240b6968ac0e",
      "revolutRefundId": "ref_112233445566778899",
      "refundAmountMinor": 10000,
      "currency": "GBP",
      "status": "COMPLETED"
    },
    "orderStatus": "REFUNDED"
  }
}

Postman Execution:

---

5. Get Payment History

Retrieves historical logs for all payment orders, payments, and refunds stored in the database.

• Endpoint: GET /api/payments/history

Response (200 OK):

{
  "success": true,
  "count": 1,
  "data": [
    {
      "_id": "6a7c790a7598240b6968ac0e",
      "merchantOrderRef": "ORD-2026-005",
      "amountMinor": 10000,
      "currency": "GBP",
      "status": "REFUNDED"
    }
  ]
}

Postman Execution:

---

⚙️ Environment Variables Setup

Create a .env file in the root directory based on the following layout:

PORT=5000
MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/merchant-api

# API Key Security Toggle (Set 'true' to enforce x-api-key check)
ENFORCE_API_AUTH=false
MERCHANT_API_KEY=sk_test_YOUR_API_KEY_HERE

---

🔐 API Key Authentication Logic

• Disabled Mode (ENFORCE_API_AUTH=false): Endpoints accept requests seamlessly without auth headers.
• Enabled Mode (ENFORCE_API_AUTH=true): Endpoints validate requests against the x-api-key header.

Header Example:

x-api-key: sk_test_YOUR_API_KEY_HERE

---

🛠️ Local Development Installation

1. Clone Repository:

   git clone [https://github.com/codebyanas/payment-management-system.git](https://github.com/codebyanas/payment-management-system.git)
   cd payment-management-system

2. Install Dependencies:

   npm install

3. Run Development Server:

   npm run dev

4. Build Project:

   npm run build