​

Transaction Lifecycle

Understanding the complete lifecycle of a transaction in the Paycrest protocol is crucial for building reliable integrations. This section explains each stage of the transaction process and what happens at each step.

​

Overview

A transaction in the Paycrest protocol follows a well-defined lifecycle from order creation to final settlement. Each stage has specific requirements, validations, and outcomes that ensure reliable and compliant payment processing.

​

Transaction Stages

​

1. Order Creation

The transaction lifecycle begins when a sender creates a payment order.

​

Order Parameters

Required Fields:

• Amount: Transaction amount in stablecoins
• Token: Stablecoin type (USDT, USDC, etc.)
• Network: Blockchain network (Base, Polygon, etc.)
• Recipient: Bank account or wallet details
• Reference: Unique transaction identifier

Optional Fields:

• Rate: Exchange rate (if not using market rate)
• Memo: Payment purpose/narration
• Return Address: Address for refunds if needed

​

Validation Process

​

Order States

• initiated: Order initiated via API (before Gateway creation)
• pending: Order awaiting provider assignment
• processing: Order being processed by provider
• cancelled: Order cancelled by sender or system
• fulfilled: Order fulfilled by provider
• validated: Order validated and ready for settlement
• settled: Order fully completed on blockchain
• expired: Order expired because no transfer was made to the receive address within the time limit

​

2. Provider Assignment

Once an order is created, aggregators work to assign it to suitable providers.

​

Assignment Criteria

Provider Selection Factors:

• Geographic Coverage: Provider supports recipient location
• Rate Competitiveness: Best available exchange rate
• Provider Rating: Historical performance and reliability
• Capacity: Provider has sufficient liquidity
• Compliance: Provider meets regulatory requirements

​

Assignment Process

​

Assignment States

• assigned: Order assigned to provider
• rejected: No suitable provider available
• retrying: Retrying assignment with different criteria

​

3. Payment Execution

Once assigned, the provider executes the payment to the recipient.

​

Execution Process

Provider Actions:

• Payment Initiation: Initiate payment through PSP
• Delivery Confirmation: Confirm payment delivery
• Settlement Reporting: Report successful settlement
• Compliance Reporting: Report for regulatory compliance

​

Execution Methods

​

Execution States

• processing: Payment being executed by provider
• fulfilled: Payment successfully delivered to recipient
• failed: Payment execution failed
• pending_confirmation: Awaiting delivery confirmation

​

4. Settlement

After successful payment execution, the transaction moves to settlement phase.

​

Settlement Process

Onchain Settlement:

• Token Transfer: Stablecoins transferred to provider
• Fee Distribution: Protocol fees distributed
• Settlement Confirmation: Blockchain confirmation
• Order Completion: Order marked as settled

​

Settlement Components

​

Settlement States

• settling: Settlement in progress
• settled: Settlement completed successfully
• settlement_failed: Settlement failed
• refunded: Order refunded to sender

​

Transaction Status Flow

​

Complete Status Flow

​

Alternative Flows

​

Failed Transaction Flow

​

Refund Flow

​

Timeframes and SLAs

​

Processing Timeframes

Standard Processing Times:

• Order Creation: < 30 seconds
• Provider Assignment: 1-5 minutes
• Payment Execution: 5-30 minutes
• Settlement: 1-10 minutes
• Total Transaction Time: 10-45 minutes

Factors Affecting Speed:

• Geographic Location: Distance between sender and recipient
• Payment Method: Bank transfer vs mobile
• Provider Capacity: Provider liquidity and processing speed
• Network Congestion: Blockchain network conditions
• Compliance Checks: Additional verification requirements

​

Service Level Agreements

Availability:

• API Uptime: 99.9% availability
• Order Processing: 99.5% success rate
• Settlement: 99.8% success rate
• Support Response: < 4 hours

Performance Metrics:

• API Response Time: < 200ms average
• Webhook Delivery: < 5 seconds
• Status Updates: Real-time
• Error Recovery: < 10 minutes

​

Error Handling

​

Common Error Scenarios

​

Order Creation Errors

Validation Errors:

• Invalid recipient information
• Insufficient sender balance
• Compliance check failures
• Rate calculation errors

Resolution:

• Correct recipient details
• Ensure sufficient balance
• Complete additional verification
• Use market rates

​

Provider Assignment Errors

Assignment Failures:

• No available providers
• Insufficient provider liquidity
• Geographic restrictions
• Compliance limitations

Resolution:

• Retry with different parameters
• Wait for provider capacity
• Check geographic restrictions
• Contact support for assistance

​

Payment Execution Errors

Execution Failures:

• Recipient account issues
• PSP processing errors
• Network connectivity issues
• Compliance rejections

Resolution:

• Verify recipient details
• Retry payment execution
• Check network connectivity
• Review compliance requirements

​

Error Recovery

​

Automatic Recovery

Built-in Recovery:

• Automatic retry mechanisms
• Alternative provider selection
• Graceful error handling
• Status notification

Manual Recovery:

• Support team intervention
• Manual order processing
• Refund processing
• Issue escalation

​

Refund Process

Automatic Refunds:

• Failed payment refunds
• Expired order refunds
• Compliance rejection refunds
• System error refunds

Manual Refunds:

• Customer service requests
• Dispute resolution
• Technical issue refunds
• Special circumstance refunds

​

Monitoring and Notifications

​

Real-time Monitoring

Order Tracking:

• Real-time status updates
• Progress notifications
• Error alerts
• Completion confirmations

Webhook Notifications:

• Order status changes
• Payment confirmations
• Error notifications
• Settlement confirmations

​

Notification Types

​

Best Practices

​

For Senders

Order Creation:

• Provide accurate recipient information
• Use appropriate exchange rates
• Monitor order status regularly
• Handle webhook notifications properly

Error Handling:

• Implement retry logic for failed orders
• Monitor for error notifications
• Contact support for persistent issues
• Maintain transaction logs

​

For Providers

Payment Execution:

• Execute payments promptly
• Provide accurate delivery confirmations
• Report compliance information
• Maintain audit trails

Quality Assurance:

• Monitor payment success rates
• Optimize processing times
• Maintain competitive rates
• Provide excellent support

​

For Aggregators

Order Management:

• Optimize provider assignment
• Monitor system performance
• Ensure compliance adherence
• Maintain service quality

System Operations:

• Monitor network health
• Optimize processing efficiency
• Maintain security standards
• Provide reliable infrastructure

Note: Understanding the transaction lifecycle helps participants build reliable integrations and provides transparency into the payment process. Each stage is designed to ensure secure, compliant, and efficient payment processing.