Download the PHP package hostme/nimiq-payment-validator without Composer

Nimiq Payment Validator

nimiq-payment-validator is a PHP library designed to interact seamlessly with the Nimiq cryptocurrency network, with a particular focus on transaction validation. Whether you're building an application that requires precise payment handling or integrating Nimiq transactions into your existing system, the library provides the tools you need to ensure accurate and reliable transaction processing.

Table of Contents

1. Features
2. Installation
3. Configuration
4. Usage
   • Validating a Transaction
   • Handling Payment Results
5. Payment States
6. Payment Strategies
   • PaidStrategy
   • OverpaidStrategy
   • UnderpaidStrategy
7. API Gateway
   • Default: NimiqWatchApiGateway
   • Custom API Gateways
8. Examples
   • Basic Transaction Validation
   • Customizing Payment Strategies
9. Testing
10. Contributing

Features

• Transaction Validation: Verify the integrity and correctness of Nimiq transactions.
• Payment State Determination: Automatically categorize transactions into states such as PAID, OVERPAID, UNDERPAID, FAILED, or NOT_FOUND based on defined strategies and thresholds.
• Flexible Strategies: Utilize default payment strategies or define custom ones to suit your application's needs.
• Extensible API Gateways: Interact with the Nimiq network using the default NimiqWatch API or integrate other gateways as required.
• Comprehensive Logging: Track and log transaction validation processes for monitoring and debugging.
• Unit Tested: Ensures reliability with extensive PHPUnit test coverage.

Installation

Install via Composer:

Configuration

Configure library by setting up the API gateway, receiver address, and payment thresholds. The library uses the NimiqWatchApiGateway by default but allows for customization.

Setting Up the Default API Gateway

Customizing Payment Thresholds and Strategies

You can customize the thresholds for overpaid and underpaid transactions and define custom payment strategies.

Usage

Validating a Transaction

Use the validateTransaction method to validate a transaction by its hash and expected amount.

Handling Payment Results

The PaymentResult object provides both the payment state and an optional message to explain the state.

Payment States

The library categorizes transaction validation results into the following states:

• PAID: The transaction amount exactly matches the expected amount.
• OVERPAID: The transaction amount exceeds the expected amount but does not exceed the defined overpaid threshold.
• UNDERPAID: The transaction amount is less than the expected amount but does not fall below the defined underpaid threshold.
• FAILED: The transaction amount exceeds the overpaid or underpaid thresholds, or other validation failures occur.
• NOT_FOUND: The transaction hash does not correspond to any transaction in the network.

PaymentState Class

Payment Strategies

The library utilizes a strategy pattern to determine the payment state based on transaction details and predefined thresholds. The library includes three default strategies:

PaidStrategy

Description: Identifies transactions where the received amount exactly matches the expected amount.

OverpaidStrategy

Description: Identifies transactions where the received amount exceeds the expected amount but does not exceed the defined overpaid threshold.

UnderpaidStrategy

Description: Identifies transactions where the received amount is less than the expected amount but does not fall below the defined underpaid threshold.

Note: Ensure that the logic within the matches method aligns with your application's requirements. The current implementation marks a transaction as OVERPAID or UNDERPAID only if the overpaid or underpaid amount is within the defined thresholds. Transactions exceeding these thresholds are marked as FAILED.

API Gateway

The library interacts with the Nimiq network through API gateways. By default, it uses the NimiqWatchApiGateway, but you can integrate custom gateways as needed.

Default: NimiqWatchApiGateway

Description: Utilizes the NimiqWatch API to fetch transaction details based on transaction hashes.

Implementation:

Parameters:

• network: 'main' or 'test' to specify the Nimiq network.
• apiDomain: Optional custom API domain. Defaults based on the network.
• httpClient: An instance of GuzzleHttp\ClientInterface.
• rateLimit: Optional rate limit in milliseconds between requests. Default is 1000 ms.

Custom API Gateways

To integrate a custom API gateway, implement the ApiGatewayInterface:

Usage:

Examples

Basic Transaction Validation

Customizing Payment Strategies

Testing

Library comes with comprehensive PHPUnit tests to ensure reliability and correctness. To run the tests:

1. Install Development Dependencies:

   Ensure that development dependencies are installed via Composer:

2. Run PHPUnit:

   Execute the test suite using PHPUnit:

3. View Coverage Report (Optional):

   To generate a code coverage report:

   Open the generated coverage/index.html in your browser to view the detailed report.

Test Structure:

• Model Tests: Verify the integrity of model classes (Transaction, PaymentState, PaymentResult).
• Strategy Tests: Ensure each payment strategy correctly identifies transaction states based on amounts and thresholds.
• PaymentStateComputer Tests: Confirm that the payment state computer accurately determines the payment state using defined strategies.
• API Gateway Tests: Mock API responses to test the behavior of API gateways under various scenarios.
• TransactionValidator Tests: Validate the end-to-end transaction validation process, including handling of different payment states and error conditions.

Contributing

Contributions are welcome! Whether it's reporting a bug, suggesting a feature, or submitting a pull request, your input helps improve it.