Skip to main content

Federation

Federation connects independent TrexWallet deployments through partner applications, DNS verification, payment orders, and webhook-based crediting.

How It Works​

Each partner connection is represented by an application record:

  1. Project owner registers a partner application in the security admin panel
  2. Domain ownership is verified through DNS TXT _itbuild.<domain>
  3. Admin enables Approved + Federation and capability flags per partner
  4. Outbound credentials (outboundPkey, outboundAppId) are stored for calls to the remote partner

DNS Verification​

sequenceDiagram
    participant Owner as Project owner
    participant A as Project A
    participant DNS as DNS zone
    participant B as Project B

    Owner->>B: Create partner app record
    B-->>Owner: TXT instruction: v=ibf1; pid=...; app=...
    Owner->>DNS: Publish _itbuild.domain TXT
    Owner->>B: verify_domain / verify_app_domain
    B->>DNS: Resolve TXT
    B-->>Owner: Domain verified

Features​

Cross-Project Payments​

Federation does not introduce a separate payment protocol. Instead:

  • Project A calls POST /payorders/v1/put_payment_order?app_id=... on project B using outboundPkey.
  • The user is redirected to the partner's universal /pay?code=… page.
  • After successful payment, the partner webhook triggers credit on project A.
  • TrexWallet records FederationCredit (tx_type=26).

Inbound Webhook Credit​

Incoming partner events are processed through:

  • POST /auth/v1/app/federation_webhook
  • capability checks: Federation, FederationWallet, FederationChat
  • POST /private/v1/federation_credit in TrexWallet

Payment Method Aggregation​

Projects can offer partner payment methods by creating the order remotely and redirecting the user to the partner's universal /pay?code=… URL.

Net Debt Accounting​

FederationWallet (-16) is the source wallet for federation credit, not the destination wallet:

  • source = FederationWallet (-16)
  • destination = partner owner wallet / mapped recipient wallet
  • balance on -16 represents net debt to federation partners

Typical Flow​

sequenceDiagram
    participant AppA as Project A integration
    participant B as Partner Project B
    participant User as User
    participant GatewayA as Project A gateway
    participant WalletA as Project A wallet

    AppA->>B: put_payment_order(app_id=outboundAppId, pkey=outboundPkey)
    B-->>AppA: code=PAY-XXXXX
    AppA->>User: Redirect to partner /pay?code=PAY-XXXXX
    User->>B: Complete payment
    B->>GatewayA: federation_webhook
    GatewayA->>WalletA: federation_credit
    WalletA-->>User: Balance credited

Admin / Configuration Touchpoints​

  • Partner applications: registration, DNS verification, and capability flags
  • Federation Outbound: outboundPkey and outboundAppId for remote calls