Payment Lifecycle Webhooks

This guide explains the payment lifecycle in the Cryptofuse system and how webhooks notify your application about status changes.

Overview

When processing cryptocurrency payments, your application will receive webhook notifications at key points in the payment lifecycle. The Cryptofuse system sends webhook notifications when a payment changes status, allowing you to update your business systems accordingly.

Webhook Flow

1. User initiates payment to an address provided by Cryptofuse
2. Cryptofuse monitors the blockchain and detects transactions
3. Your application receives notifications about payment status changes

Standard Webhook Format

All payment webhooks follow a standardized format:

{
  "event": "payment_status_update",
  "transaction_id": "85d93267-b4ce-4f61-97b8-28e9c3915d9b",
  "status": "confirming",
  "timestamp": "2025-05-18T10:28:15Z",
  "data": {
    // Detailed payment data...
  }
}

Note: For backward compatibility, the legacy event type deposit_received is still supported, but new integrations should use the standardized event type payment_status_update.

Payment Status Lifecycle

A payment in Cryptofuse progresses through the following statuses:

Status	Description	When to Expect	Is Optional?
pending	Initial state, waiting for payment	When payment is created	No
partially_paid	Some funds received, but less than expected	When partial payment is detected	Yes (only if partial payment occurs)
confirming	Full payment received, waiting for blockchain confirmations	When payment is detected on blockchain	No (if payment is made)
confirmed	Payment confirmed with required confirmations	When enough confirmations are received	Yes (depends on configuration)
completed	Payment fully processed and complete	After final processing	No (if payment is made)
failed	Payment processing failed due to technical issues	Rare, only in case of blockchain issues	Yes (only if issues occur)
expired	Payment time window has elapsed without payment	After expiry_time has passed	Yes (only if user doesn't pay)

Webhook Payload Structure

When your application receives a webhook notification for a payment, it will have this complete structure:

{
  "event": "payment_status_update",
  "transaction_id": "85d93267-b4ce-4f61-97b8-28e9c3915d9b",
  "status": "confirming",
  "timestamp": "2025-05-18T10:28:15Z",
  "data": {
    "transaction_id": "85d93267-b4ce-4f61-97b8-28e9c3915d9b",
    "status": "confirming",
    "price_amount": 100.00,
    "price_currency": "USD",
    "pay_amount": 100.00,
    "pay_currency": "USDTARB",
    "paid_amount": 100.00,
    "remaining_amount": 0.00,
    "blockchain_address": "0x3d7f28Ac63E8e94ED1754F497D11507C176a978F",
    "blockchain": "ARB",
    "token": "USDT",
    "created_at": "2025-05-18T10:24:32Z",
    "updated_at": "2025-05-18T10:28:15Z",
    "transaction_hash": "0x7a5b94df63c2d8bd83aa3ee3a15d72cdb36ae90ab49451426a85c0345014f8b4",
    "confirmations": 3,
    "payment_history": [
      {
        "deposit_id": "c60d4a7b-a67c-4563-a5e1-34fde7dbf7a3",
        "amount": "100.00",
        "transaction_hash": "0x7a5b94df63c2d8bd83aa3ee3a15d72cdb36ae90ab49451426a85c0345014f8b4",
        "confirmations": 3,
        "timestamp": "2025-05-18T10:28:15Z"
      }
    ]
  }
}

Payment History

The payment_history array contains information about individual deposits received for this transaction. This is particularly useful for scenarios where partial payments are made or multiple deposits are received for a single transaction.

Each payment history entry includes:

Field	Description
deposit_id	Unique UUID v4 identifier for this deposit
amount	Amount received in this deposit
transaction_hash	Blockchain transaction hash
confirmations	Number of blockchain confirmations
timestamp	When the deposit was received

Partial Payment Example

For a $100 payment that is paid in multiple transactions, you might receive several webhooks:

First payment ($90):

{
  "event": "payment_status_update",
  "transaction_id": "85d93267-b4ce-4f61-97b8-28e9c3915d9b",
  "status": "partially_paid",
  "timestamp": "2025-05-18T10:28:15Z",
  "data": {
    "transaction_id": "85d93267-b4ce-4f61-97b8-28e9c3915d9b",
    "status": "partially_paid",
    "price_amount": 100.00,
    "price_currency": "USD",
    "pay_amount": 100.00,
    "pay_currency": "USDTARB",
    "paid_amount": 90.00,
    "remaining_amount": 10.00,
    "blockchain_address": "0x3d7f28Ac63E8e94ED1754F497D11507C176a978F",
    "blockchain": "ARB",
    "token": "USDT",
    "created_at": "2025-05-18T10:24:32Z",
    "updated_at": "2025-05-18T10:28:15Z",
    "transaction_hash": "0x7a5b94df63c2d8bd83aa3ee3a15d72cdb36ae90ab49451426a85c0345014f8b4",
    "confirmations": 3,
    "payment_history": [
      {
        "deposit_id": "c60d4a7b-a67c-4563-a5e1-34fde7dbf7a3",
        "amount": "90.00",
        "transaction_hash": "0x7a5b94df63c2d8bd83aa3ee3a15d72cdb36ae90ab49451426a85c0345014f8b4",
        "confirmations": 3,
        "timestamp": "2025-05-18T10:28:15Z"
      }
    ]
  }
}

Second payment ($10), completing the transaction:

{
  "event": "payment_status_update",
  "transaction_id": "85d93267-b4ce-4f61-97b8-28e9c3915d9b",
  "status": "confirming",
  "timestamp": "2025-05-18T10:35:47Z",
  "data": {
    "transaction_id": "85d93267-b4ce-4f61-97b8-28e9c3915d9b",
    "status": "confirming",
    "price_amount": 100.00,
    "price_currency": "USD",
    "pay_amount": 100.00,
    "pay_currency": "USDTARB",
    "paid_amount": 100.00,
    "remaining_amount": 0.00,
    "blockchain_address": "0x3d7f28Ac63E8e94ED1754F497D11507C176a978F",
    "blockchain": "ARB",
    "token": "USDT",
    "created_at": "2025-05-18T10:24:32Z",
    "updated_at": "2025-05-18T10:35:47Z",
    "transaction_hash": "0x8e3d45f1a2c9b07d694c2f83e68de631c7ab29a4e57d9148b782f5db761cd2e1",
    "confirmations": 2,
    "payment_history": [
      {
        "deposit_id": "c60d4a7b-a67c-4563-a5e1-34fde7dbf7a3",
        "amount": "90.00",
        "transaction_hash": "0x7a5b94df63c2d8bd83aa3ee3a15d72cdb36ae90ab49451426a85c0345014f8b4",
        "confirmations": 8,
        "timestamp": "2025-05-18T10:28:15Z"
      },
      {
        "deposit_id": "72f83a1e-95b0-48d7-b7a3-1c567de9a24f",
        "amount": "10.00",
        "transaction_hash": "0x8e3d45f1a2c9b07d694c2f83e68de631c7ab29a4e57d9148b782f5db761cd2e1",
        "confirmations": 2,
        "timestamp": "2025-05-18T10:35:47Z"
      }
    ]
  }
}

Final webhook when transaction is completed:

{
  "event": "payment_status_update",
  "transaction_id": "85d93267-b4ce-4f61-97b8-28e9c3915d9b",
  "status": "completed",
  "timestamp": "2025-05-18T10:41:23Z",
  "data": {
    "transaction_id": "85d93267-b4ce-4f61-97b8-28e9c3915d9b",
    "status": "completed",
    "price_amount": 100.00,
    "price_currency": "USD",
    "pay_amount": 100.00,
    "pay_currency": "USDTARB",
    "paid_amount": 100.00,
    "remaining_amount": 0.00,
    "blockchain_address": "0x3d7f28Ac63E8e94ED1754F497D11507C176a978F",
    "blockchain": "ARB",
    "token": "USDT",
    "created_at": "2025-05-18T10:24:32Z",
    "updated_at": "2025-05-18T10:41:23Z",
    "transaction_hash": "0x8e3d45f1a2c9b07d694c2f83e68de631c7ab29a4e57d9148b782f5db761cd2e1",
    "confirmations": 12,
    "payment_history": [
      {
        "deposit_id": "c60d4a7b-a67c-4563-a5e1-34fde7dbf7a3",
        "amount": "90.00",
        "transaction_hash": "0x7a5b94df63c2d8bd83aa3ee3a15d72cdb36ae90ab49451426a85c0345014f8b4",
        "confirmations": 15,
        "timestamp": "2025-05-18T10:28:15Z"
      },
      {
        "deposit_id": "72f83a1e-95b0-48d7-b7a3-1c567de9a24f",
        "amount": "10.00",
        "transaction_hash": "0x8e3d45f1a2c9b07d694c2f83e68de631c7ab29a4e57d9148b782f5db761cd2e1",
        "confirmations": 12,
        "timestamp": "2025-05-18T10:35:47Z"
      }
    ]
  }
}

Handling Different Payment Statuses

Your application should handle these status updates appropriately:

Pending

• Show the payment address to the user
• Display QR code for easy payment
• Show countdown timer until expiry time

Partially Paid

• Inform the user that additional funds are needed
• Show the remaining amount to be paid (remaining_amount field)
• Extend the expiry time if your business logic allows

Confirming

• Inform the user that their payment has been received and is being confirmed
• Show the number of confirmations received and required
• You may choose to process the order at this stage if your risk tolerance allows

Confirmed

• Inform the user that their payment has been confirmed
• You can safely process the order at this stage
• Show the transaction details for transparency

Completed

• Process the order/payment as successful
• Send confirmation to the customer
• Fulfill the order or provide access to the purchased services

Failed (Rare)

• Inform the user that there was a technical issue with their payment
• Provide support contact information
• Offer the option to try again with a new payment address

Expired

• Inform the user that the time window for payment has passed
• Provide options to create a new payment or contact support
• Clean up any pending orders in your system

Verifying Webhook Signatures

All webhooks include an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body. Always verify this signature to ensure the webhook is authentic:

import hmac
import hashlib
from flask import request

def verify_signature(payload, signature, secret):
    computed_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(computed_signature, signature)

# In your webhook handler
@app.route('/webhook', methods=['POST'])
def webhook_handler():
    signature = request.headers.get('X-Webhook-Signature')
    payload = request.get_data().decode('utf-8')
    
    if not verify_signature(payload, signature, 'your_webhook_secret'):
        return 'Invalid signature', 403
    
    # Process webhook
    data = request.json
    # ...
    
    return 'OK', 200

Best Practices

1. Handle Idempotency: Webhooks may be sent multiple times - use deposit_id to detect duplicates
2. Process Asynchronously: Respond to webhooks quickly (200 OK) and process the data asynchronously
3. Verify Signatures: Always verify webhook signatures before processing
4. Track Payment History: Use the payment_history array to reconcile payments, especially for partial payments
5. Handle All Status Values: Ensure your application handles all possible transaction status values
6. Implement Timeouts: Have fallback processes in case webhooks aren't received (system monitoring)
7. Error Handling: Implement proper error handling and logging for webhook processing

Testing Webhooks

You can test webhook handling using the built-in testing tools or by creating test transactions with small amounts. For local development, use tunneling tools like ngrok to receive webhooks on your development machine.

For more information on general webhook implementation, see the Implementing Webhook Callbacks guide and the Webhook Reference documentation.

Common Integration Scenarios

E-Commerce Integration

For e-commerce platforms:

1. Create a payment when the user checks out
2. Display the payment address on the order confirmation page
3. Update the order status based on webhook notifications
4. Send confirmation email when payment is completed
5. Automatically mark orders as cancelled if payment expires

Gaming/Service Platform Integration

For gaming or service platforms:

1. Create a payment when the user requests to deposit funds
2. Show the payment address in the user's account dashboard
3. Credit the user's account when payment is completed
4. Track partial payments for large deposits
5. Provide detailed payment history for customer support

For detailed implementation examples, see our Implementing Webhook Callbacks guide or contact our support team.