Data flow

This page walks the bytes through a single end-to-end payment, from the merchant''s API call to the signed webhook.

End-to-end sequence

sequenceDiagram
    autonumber
    actor C as Customer
    participant M as Merchant
    participant P as pay/api :4000
    participant DB as Postgres
    participant S as pay/settlement
    participant N as chain :8545
    participant W as pay/webhooks
    participant H as Merchant endpoint

    C->>M: scan QR (EIP-681)
    M->>P: POST /v1/invoices
    P->>P: auth (HMAC)
    P->>P: rate limit + idempotency
    P->>DB: nextval(invoice_deriv_seq)
    P->>P: derive deposit address
m/44'/60'/0'/0/index
    P->>DB: INSERT invoice
    P-->>M: 201 deposit_address + QR

    C->>N: eth_sendRawTransaction
    N-->>S: new block (polled 1.5s)
    S->>DB: match by deposit_address
    S->>N: getTransactionReceipt
    S->>DB: status = PAID
    S->>W: queue payment.detected

    loop until 2xx
        W->>H: POST webhook
x-babyfx-signature
        H-->>W: response
    end

    Note over S: confirmations advance
    S->>DB: status = CONFIRMED at threshold
    S->>S: sweep ? merchant.settlement_address
    S->>N: eth_sendRawTransaction
    S->>DB: sweep_status = SWEPT

Where each piece lives

Failure modes and recovery