Skip to content

Conversation

@gustavovalverde
Copy link
Member

Add SecureTokenHold Functionality for Token-Based Pre-Authorization

Summary

This PR implements SecureTokenHold functionality in PyAzul, enabling pre-authorization (hold) transactions using saved payment tokens with full 3D Secure authentication support.

🚀 New Feature: SecureTokenHold

Core Implementation

  • SecureTokenHold model in pyazul.models.three_ds
  • Support for token-based hold transactions with 3D Secure authentication
  • Integration with existing DataVault token infrastructure
  • Compatible with manual capture workflows in payment providers

Key Capabilities

  • Pre-authorize payments using saved tokens without immediate capture
  • 3D Secure authentication for token hold transactions
  • Validation and error handling for secure payment processing
  • Flexible challenge flows supporting method notifications and challenges
  • Session management for complex 3DS authentication workflows

Model Features

  • Required fields: Store, Amount, DataVaultToken, OrderNumber, CardHolderInfo, ThreeDSAuth
  • Validated TrxType field (must be "Hold")
  • DataVaultToken format validation with UUID pattern
  • ForceNo3DS control ("0" or "1")
  • Optional fields: Itbis, CVC, CardNumber, CustomOrderId

🧪 Comprehensive Test Coverage

Unit Tests (8 test cases)

  • Model validation and serialization
  • Required field enforcement
  • Pattern validation for critical fields
  • Default value verification

Service Tests (5 test cases)

  • 3DS authentication workflows
  • Challenge and method notification handling
  • Error scenarios and edge cases
  • Complete token hold processing

Integration Tests (3 test cases)

  • Real API interaction with Azul servers
  • End-to-end token hold workflows
  • Session data management and validation

🎯 Use Cases

  • E-commerce pre-authorization: Hold funds at order time, capture at fulfillment
  • Subscription renewals: Authorize recurring payments using saved tokens
  • Manual review workflows: Pre-authorize high-value transactions for review
  • Inventory management: Hold payment while confirming product availability

🔧 Technical Details

  • Extends existing 3DS authentication framework
  • Compatible with current SecureSale and SecureTokenSale implementations
  • Follows established PyAzul patterns for async operations
  • Supports both frictionless and challenge-based 3DS flows

- Implement SecureTokenHold model for token-based pre-authorization transactions
- Add 3D Secure authentication support for token hold operations
- Include validation for required fields, TrxType patterns, and token formats
- Add complete test coverage with unit, service, and integration tests
- Support manual capture workflows for saved payment methods
- Enable pre-authorization using DataVault tokens with 3DS flows
@gustavovalverde gustavovalverde merged commit 2b025fb into main Jun 2, 2025
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant