Foreign Exchange Integration Guide

Business Architecture and Funds Flow

In the DogPay ecosystem, a foreign exchange transaction is essentially an asset swap between two balanceId entities. The diagram below uses the transfer from a crypto wallet to a VA as an example.

graph LR
    A["Crypto Wallet<br/>balanceId: A"] -- "Sell Currency (e.g., USDT)" --> FX{"DogPay FX Engine"}
    FX -- "Buy Currency (e.g., USD)" --> B["Virtual Account (VA)<br/>balanceId: B"]

Core Integration Flowchart

Since the FX business currently does not support asynchronous Webhook notifications, integrators must follow an active polling logic to ensure a closed-loop business process:

graph TD
    Start[Start FX Integration] --> FetchID[1. Call Get Balance List API to get balanceId]
    FetchID --> Quote[2. Request Quote /fx/quote]
    
    Quote --> Result[Obtain quoteId & Real-time Rate]
    Result --> Valid{Within Validity Period?}
    
    Valid -- No --> Quote
    Valid -- Yes --> Trade[3. Create Order /fx/trade/order]
    
    Trade --> Poll[4. Active Polling & Verification]
    Poll --> OrderDetail[Query FX Order Details]
    Poll --> BalanceCheck[Check Wallet/VA Balance Changes]
    
    OrderDetail --> Success[Funds Transfer Completed]
    BalanceCheck --> Success

Detailed Integration Steps

📘

Core Concept: Account Balance Identifier (balanceId)

The system recognizes the balanceId as the unique credential for identifying fund accounts during all FX transactions. Please note that the interface parameters require the balance ID rather than the Crypto Wallet ID or the Virtual Account ID.

Step 1: Prepare Account Balance Identifier

Before initiating any transaction, you must obtain the balanceId for both the source and destination accounts.

• Unified Query Path: Please use the Get Balance List API for unified retrieval.
• Matching Logic:
  • To transfer from a crypto wallet, find the record with type cw in the returned list and extract its balanceId.
  • To transfer from a Virtual Account, find the record with type va_group and extract its balanceId.
• Note: The Crypto Wallet detail and VA detail APIs currently only return balance values and do not include the balanceId.

Step 2: Request Foreign Exchange Quote

Call the Request Foreign Exchange Quote API.

• Quote Locking: The system returns a quoteId and an expireTime.
• Tenor Restriction: Currently, only the T0 (Same-day settlement) tenor is supported.

Step 3: Create Foreign Exchange Trade Order

Within the quote validity period, call the Create Foreign Exchange Trade Order API to execute the conversion.

• Mandatory Parameters: You must accurately provide the sellAccount and buyAccount balanceId obtained in Step 1.
• External Reference: Provide your unique externalOrderNo to facilitate subsequent idempotency checks.

Step 4: Status Query and Balance Verification

As there are no asynchronous Webhooks, it is recommended to confirm fund arrival through a dual-verification approach:

• Order Dimension: Poll the Get Foreign Exchange Trade Order Details API to monitor the final settlement status.
• Asset Dimension: Poll the Get Balance List API or related detail APIs to observe real-time balance fluctuations.

Risk and Responsibility

🚧

Settlement Responsibility Reminder

Once an FX trade order is successfully created, the system will immediately attempt to lock and transfer funds from the source account. Before calling the order API, please ensure that the source account (sellAccount) has a sufficient available balance, as balance insufficiency will cause the operation to fail.