Payment Workflow

🗺️ 1. Sequence Diagram

Below is the standard end-to-end integration workflow for DogPay's Web3 acquiring:

sequenceDiagram
    autonumber
    
    participant U as End User (User)
    participant M as Merchant System (Merchant)
    participant D as DogPay Gateway
    participant C as Blockchain Network

    Note over U, D: Phase 1: Order Creation & Checkout Display
    U->>M: 1. Initiate checkout request on merchant side
    
    M->>D: 2. [Optional] Get supported currency and chain configs
    Note right of M: GET /open-api/v1/pay/currency-config
    
    M->>D: 3. Create payment order
    Note right of M: POST /open-api/v1/pay
    D-->>M: Return order details and hosted checkout link (payUrl)
    
    M->>U: 4. Display payment link to user (via redirect/iframe/QR code)
    
    Note over U, C: Phase 2: User Payment & On-chain Broadcast
    U->>C: 5. User transfers funds via Web3 wallet scan or contract call
    
    Note over D, M: Phase 3: On-chain Monitoring & Status Flow
    C-->>D: 6. Detect transaction in mempool (Tx Unconfirmed)
    Note over D: System Update: waitAmountOnChain increases
    
    D-->>M: 7. Order status update notification (Webhook)
    Note right of M: Event: pay.transaction.update
    
    C-->>D: 8. Transaction reaches safe block confirmations (Tx Confirmed)
    Note over D: System Update: doneAmountOnChain increases, status changes to completed
    
    D-->>M: 9. Payment final completion notification (Webhook)
    Note right of M: Event: pay.transaction
    
    M-->>U: 10. Merchant backend releases goods and displays success page on frontend
    
    Note over D, M: Phase 4: Fund Settlement
    D->>D: 11. Funds settled and credited to the merchant's Crypto Wallet

⚙️ 2. Order State Machine

To accurately track the order lifecycle, your system needs to map and understand the following three types of status fields returned by DogPay:

📌 2.1 Main Status (`status`)

This is the core indicator determining the ultimate success or failure of the order. Merchants must strictly rely on this status for order fulfillment.

Status Value	Description	Recommended Action
`pending`	Processing: The order is created and waiting for payment, or the user's on-chain transaction is awaiting block confirmations.	Do not ship/release. Prompt the user to wait on the frontend.
`completed`	Completed: On-chain funds have reached the required block confirmations, and the amount matches successfully.	Safe to ship/release service.
`failed`	Failed: The order failed due to various reasons (e.g., payment timeout).	Terminate the transaction or guide the user to place a new order.

📌 2.2 Process Status (`processStatus`)

Used as an auxiliary indicator to determine the specific sub-stage of the order.

Status Value	Description
`pending`	The default initial state.
`cancelled`	The order was actively cancelled.
`timeout`	The order exceeded the `expireTime` set during creation and is now invalid.
`combine_completed`	Multiple transactions were combined to fulfill the order (e.g., the user made two separate transfers that totaled the required order amount).

📌 2.3 Settlement Status (`settleStatus`)

Indicates whether the funds for this order have been credited to your merchant Crypto Wallet.

Status Value	Description
`unsettled`	Unsettled: The order might still be processing, or it was paid successfully but internal system reconciliation is not yet complete.
`settled`	Settled: Funds have been safely added to your DogPay Wallet balance. You can call the `/crypto-wallet/transactions/withdraw` endpoint at any time to withdraw funds on-chain.

⛓️ 3. On-Chain Amount Confirmation

Due to the nature of blockchain networks, a transaction takes time from broadcast to final confirmation (e.g., Ethereum might take minutes, while Tron is faster). To allow your frontend to display real-time progress, we provide the following two fields in the order details:

waitAmountOnChain: The network has detected the user's broadcasted transfer, but it has not yet reached the safe number of block confirmations. At this point, the funds are not absolutely safe (there is a very low risk of rollback or double-spending).
doneAmountOnChain: The transaction is permanently finalized on the blockchain. The order's status will only transition to completed when doneAmountOnChain is greater than or equal to the required order amount.

⚠️
Best Practice Warning
Do not execute delivery/fulfillment actions simply because waitAmountOnChain is greater than 0. You MUST use the receipt of a Webhook notification indicating status = completed as the sole trigger for releasing goods or services.

🗺️ 1. Sequence Diagram

⚙️ 2. Order State Machine

📌 2.1 Main Status (status)

📌 2.2 Process Status (processStatus)

📌 2.3 Settlement Status (settleStatus)

⛓️ 3. On-Chain Amount Confirmation

Best Practice Warning

📌 2.1 Main Status (`status`)

📌 2.2 Process Status (`processStatus`)

📌 2.3 Settlement Status (`settleStatus`)