payment-information-validator

A simple NodeJs API that validates credit card information and charge amount. This repository is written in vanilla Javascript and low level NodeJs modules with no external libraries. Here's what you can do with the API:

• Validate credit card details: card number, cvv2, expiration date, email and phone number. JSON and XML supported.
• Authorize requests using the popular HMAC hash algorithm.
• A helper endpoint to get the correct hash to use in the validation step.

Getting Started

You need to have Node and npm installed on your machine to run this code locally. The latest versions of both are recommended.

Installation

You can clone this repository using the command below:

git clone https://github.com/onubrooks/payment-information-validator.git

And run the the project like this:

npm run start

Usage

Authorization

This API uses bearer token authorization. To make a successful request, a HMAC hash signature must be generated and used as the bearer token for the request. The hash is a HMAC signature of your payload and a private key. For convenience, this can be generated by computing the HMAC hash of the payload you are about to send using the private key: i-love-node-js. An endpoint has been provided to assist with this task, make a POST request to:

localhost:5000/api/get-hash

Ensure to use the exact payload and content-type header you will use to make the validation request.

Get Hash Example

curl --location --request POST 'localhost:5000/api/get-hash' \
--data-raw '{
    "email": "hello@example.org",
    "card_number": "374245455400126",
    "cvv2": "123",
    "expiration_date": "07/2021",
    "phone_number": "08090909090",
    "charge_amount": "5000"
}'

Get Hash Response

Below is a sample HMAC hash that is sent as a response:

{
    "status": "success",
    "hash": "d29b79b005beb0b1fbc5fa61167fc0d7fa5c0f0b8ef0b3e2db0c52148194368fa53ac655508b55e9fd3afafb48a957122f2dfeb8f8461ca0cdb7e6283575930d"
}

Validate Card Details

This is the main endpoint that this API was created for. Make a request as follows to localhost:5000/api/validate-card:

curl --location --request POST 'localhost:5000/api/validate-card' \
--data-raw '{
    "email": "hello@example.org",
    "card_number": "374245455400126",
    "cvv2": "123",
    "expiration_date": "07/2021",
    "phone_number": "08090909090",
    "charge_amount": "5000"
}'

Sample JSON Payload

The following is a sample JSON payload to be validated:

{
    "email": "hello@example.org",
    "card_number": "374245455400126",
    "cvv2": "123",
    "expiration_date": "07/2021",
    "phone_number": "08090909090",
    "charge_amount": "5000"
}

Sample XML Payload

The following is a sample XML payload to be validated:

<root>
    <email>hello@example.org</email>
    <card_number>374245455400126</card_number>
    <cvv2>123</cvv2>
    <expiration_date>07/2021</expiration_date>
    <phone_number>08090909090</phone_number>
    <charge_amount>5000</charge_amount>
</root>

Note: The top level tag in your XML must be named root in order for the data to be parsed correctly.

Validate Details Response

A successful request/response cycle, when all fields satisfy the validation rules, looks like this:

{
    "valid": true,
    "message": "Validation passed successfully"
}

Validate Details Response Unauthorized

{
    "status": "Unauthorized",
    "message": "Request authentication failed"
}

When validation fails, the response is sent in the following format:

{
    "valid": false,
    "message": "Validation failed for some fields",
    "errors": [
        {
            "key": "card_number",
            "valid": false,
            "message": "invalid credit card number"
        },
        {
            "key": "cvv",
            "valid": false,
            "message": "cvv must be 3 or 4 numeric characters long"
        },
        {
            "key": "email",
            "valid": false,
            "message": "email is invalid"
        },
        {
            "key": "phone_number",
            "valid": false,
            "message": "phone number must be 11 numeric characters long or have the international format"
        }
    ]
}

Note that all validation errors detected is returned in the errors array of the response.

Validations

All fields below are required. In addition, these are the validations the API provides:

1. card_number: must be a valid credit card number based on Luhn's Algorithm.

2. cvv2: must be a valid cvv2 number, having 3 or 4 digits.

3. expiration_date: must be a valid date in the format mm/yyyy, must be higher than the current date.

4. email: must be a valid email format.

5. phone_number: must be a valid phone number with 11 digits, or international format xxx-xxx-xxxx. Parenthesis () are allowed in the first group.

6. charge_amount: amount must be a non-negative integer greater than zero.

Errors and Status Codes

These are the expected status codes and their meanings:

1. 200: ok. This means a successful request.

2. 401: Unauthorized. This occurs when authentication fails, due to invalid authorization header or none given.

3. 403: Forbidden. The request was understood but due to some constraints rejected by the server. Usually an empty payload would cause this to happen.

4. 404: Not found. This means the endpoint/resource requested was not found on the server.

5. 500: Internal server error. This indicates that an unexpected error was encountered on the server.

Supported Data Formats

1. JSON: this is the default and expected format for the data to be sent to the API.

2. XML: this format is also supported to send the payload to the API.

Questions

For questions or clarifications, please contact the author at abahonuh@gmail.com or find out other works at onubrooks.