XCHNG Payment & Settlement API

Overview

Our payment system provides a complete solution for wallet funding, in-app transactions, and instant settlements through webhook-based notifications. The system is built on robust payment gateway integrations that ensure secure, reliable, and immediate fund transfers.

System Architecture

Components

Payment Flow Process

1. Wallet Funding

Steps:

1. User selects amount to fund wallet
2. Application generates payment request via Payment Gateway API
3. User completes payment through gateway's secure interface
4. Payment gateway processes transaction
5. Upon successful payment:
   • Gateway sends webhook notification to our system
   • System verifies webhook signature and authenticity
   • User wallet is credited immediately
   • User receives confirmation notification

Supported Methods:

• Wire Transfer (USD)
• ACH (USD)
• Other payment methods as configured in gateway

Settlement Process

Instant Settlement via Webhooks

Timeline:

• Webhook received: < 1 second after payment success
• Validation & processing: < 2 seconds
• Settlement execution: Immediate (synchronous)
• Total time: < 5 seconds from payment to settlement

Webhook Events:

API Reference

Payment Initiation API

POST /api/v1/payments/initiate
Content-Type: application/json
Authorization: Bearer {api_key}

{
  "amount": 100.00,
  "currency": "USD",
  "customer_id": "cust_xyz789",
  "payment_method": "wire_usd",
  "metadata": {
    "purpose": "wallet_funding"
  }
}

Webhook Endpoint

POST /api/webhooks/payment-gateway
Content-Type: application/json
X-Gateway-Signature: {signature}

{
  "event": "payment.success",
  "data": {...}
}

Webhook Payload Example

{
  "event": "payment.success",
  "transaction_id": "txn_abc123xyz",
  "customer_id": "cust_xyz789",
  "amount": 100.00,
  "currency": "USD",
  "payment_method": "wire_usd",
  "timestamp": "2025-11-28T10:30:00Z",
  "signature": "sha256_hash_signature"
}

Security & Compliance

Webhook Security

• Signature Verification - All webhooks are verified using HMAC SHA-256
• IP Whitelisting - Only accept webhooks from gateway's verified IPs
• Idempotency - Duplicate webhooks are detected and ignored
• Timeout Protection - Webhooks must be received within configurable timeframe

Transaction Security

• Encrypted Communication - All API calls use TLS 1.3
• API Key Rotation - Regular rotation of authentication credentials
• Audit Logging - Complete transaction trail for compliance
• PCI DSS Compliance - Payment data handled according to standards

Compliance Certifications

Integration Requirements

For Product Owners

• Valid account with supported payment gateway
• API credentials (provided by us)
• Bank account for settlement (configured in gateway)
• Webhook endpoint URL (if custom notifications needed)

Settlement Configuration

• Default: Instant settlement on successful payment
• Frequency: Per-transaction (immediate)
• Currency: USD (expandable)
• Methods: Wire, ACH, and gateway-supported methods

Getting Started

Benefits Summary