💳 Valex

📌 Description

Valex is a voucher card API responsible for creating, reloading, activating, as well as processing purchases.

🗒️ Contents

• 💳 Valex

  • 📌 Description

  • 🗒️ Contents

  • 🚧 Status

  • 🧰 Built With

  • 🧭 API Reference

    Endpoints

    • CARDS
      • Create Card
        • Request
        • Response
      • Activate Card
        • Request
        • Response
      • Block Card
        • Request
        • Response
      • Unblock Card
        • Request
        • Response
      • Recharge Card
        • Request
        • Response
      • Get Card Statement
        • Response
    • PAYMENTS
      • POS Payment
        • Request
        • Response

  • ⚙️ How to Run

    • Cloning the Application
    • Environment Variables
    • Running Locally
    • Running on Docker

  • 🔍 Testing the Application

    • Locally
    • Docker

🚧 Status

🧰 Built With

🧭 API Reference

CARDS

Create Card

• Companies can create a voucher card for their employee;
• The company is authenticated using their apikey;

POST /cards

Request

Headers	Type	Description
x-api-key	string	must be a valid apikey

Body	Type	Description
type	string	"education", "health", "groceries", "transport", "restaurants"
employeeId	number	must be an integer

{
  "type": "education",
  "employeeId": 1
}

Response

Body	Code	Description
json	201	Created
json	409	Conflict, user already has a card with the chosen type
json	400	Bad Request, request body is invalid
json	404	Not Found, company or employee not found

{
  "id": 1,
  "cardholderName": "USER A NAME",
  "expirationDate": "11/27",
  "number": "9832 0653 1213 3591",
  "securityCode": "118",
  "type": "education"
}

Activate Card

• Employees can activate their voucher card by setting a password;
• The card id is passed as a param;
• The card cannot be expired;
• The card must not be already active;

PATCH /cards/:id/activate

Request

Body	Type	Description
password	string	must only contain four numbers
securityCode	string	must only contain three numbers

{
  "password": "1234",
  "securityCode": "118"
}

Response

Body	Code	Description
empty	200	OK
json	400	Bad Request, request body is invalid
json	401	Unauthorized, wrong security code
json	404	Not Found, card not found
json	422	Unprocessable Entity, the card is expired or the card is already active

Block Card

• Employees can block their cards;
• The card id is passed as a param;
• The card cannot be expired;
• The card must be active and cannot be already blocked;

PATCH /cards/:id/block

Request

Body	Type	Description
password	string	must only contain four numbers

{
  "password": "1234"
}

Response

Body	Code	Description
empty	200	OK
json	400	Bad Request, request body is invalid
json	401	Unauthorized, wrong password
json	404	Not Found, card not found
json	422	Unprocessable Entity, the card is expired or the card is not active or the card is already blocked

Unblock Card

• Employees can unblock their cards;
• The card id is passed as a param;
• The card cannot be expired;
• The card must be active and cannot be already unblocked;

PATCH /cards/:id/unblock

Request

Body	Type	Description
password	string	must only contain four numbers

{
  "password": "1234"
}

Response

Body	Code	Description
empty	200	OK
json	400	Bad Request, request body is invalid
json	401	Unauthorized, wrong password
json	404	Not Found, card not found
json	422	Unprocessable Entity, the card is expired or the card is not active or the card is already unblocked

Recharge Card

• Companies can recharge their employee's cards;
• The card id is passed as a param;
• The company is authenticated using their apikey;
• The card cannot be expired or blocked;
• The card must be active;

POST /cards/:id/recharge

Request

Headers	Type	Description
x-api-key	string	must be a valid apikey

Body	Type	Description
amount	number	must be an integer greater than zero

{
  "amount": 1000
}

Response

Body	Code	Description
json	201	Created
json	400	Bad Request, request body is invalid
json	404	Not Found, card not found or company not found
json	422	Unprocessable Entity, the card is expired or the card is not active or the card is blocked

{
  "id": 1,
  "amount": 1000,
  "cardId": 1,
  "timestamp": "03/11/2022"
}

Get Card Statement

• The employee can get the card statement (balance, recharges and payments);
• The card id is passed as a param;

GET /cards/:id/statement

Response

Body	Code	Description
json	200	OK
json	404	Not Found, card not found

{
  "balance": 100,
  "recharges": [
    {
      "id": 1,
      "amount": 1000,
      "cardId": 1,
      "timestamp": "03/11/2022"
    }
  ],
  "payments": [
    {
      "id": 1,
      "amount": 900,
      "cardId": 1,
      "business": {
        "id": 1,
        "name": "Hewlett Packard Enterprise - Reichel Group",
        "type": "education"
      },
      "timestamp": "03/11/2022"
    }
  ]
}

PAYMENTS

POS Payment

• Employees can buy on POS using their voucher card;
• The POS business type must be the same as the voucher card type;
• The card must be active and cannot be blocked or expired;
• The card must have sufficient balance;

POST /payments/pos

Request

Body	Type	Description
cardId	number	must be an integer
password	string	must only contain four numbers
businessId	number	must be an integer
amount	number	must be an integer greater than zero

{
  "cardId": 1,
  "password": "1234",
  "businessId": 1,
  "amount": 900
}

Response

Body	Code	Description
json	201	Created
json	400	Bad Request, request body is invalid
json	401	Unauthorized, wrong password
json	404	Not Found, card not found or business not found
json	422	Unprocessable Entity, the card is expired or the card is not active or the card is blocked, insufficient balance

⚙️ How to Run

Cloning the Application

1. Clone the application to your machine:

   git clone https://github.com/akiraTatesawa/valex.git

2. Navigate to the application dir:

   cd valex/

3. Install the dependencies:

   npm i

Environment Variables

1. Set up a .env.development file on the root of the project following the example on .env.example:

   • PORT: The port where the node app is going to run;
   • POSTGRES_USERNAME: Your postgres username;
   • POSTGRES_PASSWORD: Your postgres password;
   • POSTGRES_HOST: Your postgres host;
   • POSTGRES_PORT: The port where postgres is running;
   • POSTGRES_DATABASE: The name of the database;
   • DATABASE_URL: The URL of the postgres database;
   • CRYPTR_SECRET: The secret key used for encrypting data;

2. The postgres related variables are going to change depending on whether you are going to run the app locally or on docker;

Running Locally

1. Run the prisma migration command:

   npm run dev:migrate

2. Run the prisma db seed command:

   npm run dev:seed

3. Run the application and have fun!

   npm run dev

Running on Docker

1. Run the postgres command:

   npm run dev:postgres

2. Run the node app docker command:

   npm run dev:docker

3. On another terminal, run the seed command:

   npm run dev:docker:seed

4. Have fun!

🔍 Testing the Application

Locally

1. Set up a .env.test file following the .env.example model;

2. Run the testing command:

   npm run test

Docker

1. Set up a .env.test file following the .env.example model;

2. If you are running the dev application, drop it with the following command:

   npm run dev:docker:down

3. Create the postgres testing container:

   npm run test:postgres

4. Run the docker testing command:

   npm run test:docker

5. After the test, drop the testing containers:

   npm run test:docker:down