Transaction Lifecycle

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

​

Overview

A payment order 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 order routing and fulfillment.

​

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 provider
• 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. Order Fulfillment

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

​

Fulfillment Process

Provider Actions:

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

​

Fulfillment Methods

​

Fulfillment Statuses

• pending: Payment being executed by provider
• success: Payment successfully delivered to recipient
• failed: Order fulfillment failed

​

4. Settlement

After successful payment order fulfillment, the transaction moves to settlement phase.

​

Settlement Process

Onchain Settlement:

• Stablecoin Transfer: Stablecoins transferred to provider (offramp) or recipient (onramp)
• Fee Distribution:
  • Provider fees
  • Protocol fees
• Settlement Confirmation: Blockchain confirmation
• Order Completion: Order marked as settled

​

Settlement Components

​

Settlement States

• validated: Order validated and ready for settlement
• settled: Settlement completed successfully
• refunded: Order refunded to sender

​

Transaction Status Flow

​

Complete Status Flow

​

Alternative Flows

​

Expired Transaction Flow

​

Refund Flow

​

Timeframes and SLAs

​

Processing Timeframes

Standard Processing Times:

• Order Processing: < 30 seconds (creation → validation)
• Settlement: +15 seconds (onchain settlement)
• Total Transaction Time: ~1-2 minutes
• Auto-Refund: If not completed within 5 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
• Provider Reassignment: Failed validation may trigger reassignment (extends processing time)

​

Service Level Agreements

Availability (Beta):

• API Uptime: 99.9% availability
• Order Processing: ~80% success rate (beta phase)
• Settlement: ~100% success rate (beta phase)
• Support Response: < 48 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

​

Order Fulfillment Errors

Execution Failures:

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

Resolution:

• Verify recipient details
• Retry order fulfillment
• 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

Order Fulfillment:

• 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