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

1

Parameter Validation

Validate all required fields are present and properly formatted
2

Sender Verification

Verify sender KYC status and account validity
3

Recipient Validation

Validate recipient information and delivery method
4

Compliance Check

Perform AML/CFT screening and risk assessment
5

Rate Calculation

Calculate optimal exchange rate if not specified

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

1

Provider Discovery

Identify all providers supporting the currency pair
2

Rate Comparison

Compare rates from all available providers
3

Capacity Check

Verify provider has sufficient liquidity
4

Quality Assessment

Evaluate provider reliability and performance
5

Final Selection

Select optimal provider based on criteria

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

Bank Transfer

  • Direct bank account deposit
  • SWIFT/SEPA transfers
  • Real-time payments
  • Batch processing

Mobile

  • M-Pesa transfers
  • Airtel Money
  • MTN Mobile Money
  • Other mobile wallets

Digital Wallets

  • PayPal transfers
  • Digital banking apps
  • E-wallet services
  • Prepaid cards

Crypto Wallets

  • Stablecoin transfers
  • Multi-signature wallets
  • Hardware wallet support
  • DeFi wallet integration

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

Token Settlement

  • Stablecoin transfer to provider
  • Gas fee optimization
  • Multi-signature security
  • Settlement confirmation

Fee Distribution

  • Provider fees
  • Protocol fees

Compliance Settlement

  • Regulatory reporting
  • Audit trail completion
  • Compliance attestation
  • Record retention

Order Completion

  • Final status update
  • Webhook notification
  • Receipt generation
  • Analytics update

Settlement States

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

Transaction Status Flow

Complete Status Flow

1

initiated

Order initiated via API
2

pending

Awaiting provider assignment
3

processing

Order being processed by provider
4

fulfilled

Order fulfilled by provider
5

validated

Order validated and ready for settlement
6

settled

Transaction completed successfully

Alternative Flows

Expired Transaction Flow

1

initiated

Order initiated via API
2

expired

Order expired - receive address did not receive stablecoin within time limit

Refund Flow

1

initiated

Order initiated via API
2

pending

Awaiting provider assignment
3

processing

Order being processed by provider
4

cancelled

Order cancelled by provider
5

refunded

Funds refunded to sender

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

Status Updates

  • Order creation confirmation
  • Provider assignment notification
  • Order fulfillment updates
  • Settlement confirmation

Error Notifications

  • Validation error alerts
  • Processing failure notifications
  • Compliance rejection alerts
  • System error notifications

Completion Notifications

  • Successful payment confirmations
  • Settlement completion alerts
  • Receipt generation
  • Analytics updates

System Notifications

  • Maintenance announcements
  • Service updates
  • Security alerts
  • Performance notifications

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
Understanding the transaction lifecycle helps participants build reliable integrations and provides transparency into the order routing process. Each stage is designed to ensure secure, compliant, and efficient order coordination.
Beta Status: Paycrest is currently in beta phase. Success rates, processing times, and feature availability may evolve as the protocol matures. We’re actively working to improve reliability and performance based on real-world usage.