[FEATURE] Add support for PIX (Instant Payments) operations

[guibranco]

Description

We need to add support for PIX (instant payments) operations to our gateway library written in C#. PIX is a payment method widely used in Brazil for instant transfers and payments. This feature will enhance our gateway library by integrating PIX functionalities, allowing users to process PIX payments seamlessly.

Problem Statement

• Current Issue: The current gateway library does not support PIX operations, which limits its functionality for users who need to process instant payments.
• Impact: Adding PIX support will enable users to handle instant payments and transfers more efficiently, meeting the needs of Brazilian markets and expanding the library's usability.

Proposed Solution

• Implement PIX Operations:

  • Add functionality to handle various PIX operations, such as creating a PIX payment request, checking the status of a PIX payment, and handling payment callbacks.
  • Follow the functionality documentation available at MaxiPago PIX Documentation for reference.

• Create Unit Tests:

  • Develop unit tests to ensure that each PIX operation is implemented correctly and handles various scenarios, including success, failure, and edge cases.

• Develop Integration Tests:

  • Implement integration tests to verify that the PIX operations work correctly when integrated with the actual payment systems and services.
  • Use mock services or test environments provided by PIX gateways for testing.

Implementation Steps

1. Review PIX Documentation:

   • Study the PIX functionality documentation provided by MaxiPago to understand the required operations and integration points.

2. Add PIX Support to Gateway Library:

   • Implement methods and classes to handle PIX operations such as payment requests, status checks, and callbacks.
   • Ensure the implementation follows the guidelines and requirements specified in the documentation.

   public class PixPaymentService
   {
      public async Task<PaymentResponse> CreatePaymentAsync(PixPaymentRequest request)
      {
          // Implementation code here
      }
   
      public async Task<PaymentStatus> CheckPaymentStatusAsync(string paymentId)
      {
          // Implementation code here
      }
   
      // Additional methods for PIX operations
   }

3. Develop Unit Tests with XUnit:

   • Write unit tests for the new PIX functionalities, ensuring they cover various scenarios and edge cases.
   • Use NSubstitute to mock dependencies and isolate the components being tested.

   public class PixPaymentServiceTests
   {
      private readonly PixPaymentService _service;
   
      public PixPaymentServiceTests()
      {
          _service = new PixPaymentService();
      }
   
      [Fact]
      public async Task CreatePayment_ShouldReturnSuccess()
      {
          // Arrange
          var request = new PixPaymentRequest { /* Set request details */ };
   
          // Act
          var response = await _service.CreatePaymentAsync(request);
   
          // Assert
          Assert.NotNull(response);
          Assert.True(response.IsSuccess);
      }
   }

4. Implement Integration Tests:

   • Set up integration tests to verify the interaction between the gateway library and the PIX payment system.
   • Use WireMock or similar tools to simulate PIX responses if direct integration is not possible.

   public class PixPaymentIntegrationTests : IClassFixture<IntegrationTestFixture>
   {
      private readonly IntegrationTestFixture _fixture;
   
      public PixPaymentIntegrationTests(IntegrationTestFixture fixture)
      {
          _fixture = fixture;
      }
   
      [Fact]
      public async Task CreatePaymentIntegration_ShouldWork()
      {
          // Arrange
          var request = new PixPaymentRequest { /* Set request details */ };
   
          // Act
          var response = await _fixture.Service.CreatePaymentAsync(request);
   
          // Assert
          Assert.NotNull(response);
          Assert.Equal("Success", response.Status);
      }
   }

5. Test and Validate:

   • Execute unit and integration tests to ensure that PIX operations are functioning correctly.
   • Review test results and refine implementations as needed.

6. Documentation:

   • Update the library documentation to include information about the new PIX operations.
   • Provide usage examples, configuration details, and integration instructions.

Additional Notes

• Ensure that the PIX implementation adheres to security best practices and handles sensitive data appropriately.
• Coordinate with stakeholders to confirm that the PIX features meet business and technical requirements.