Requested amount & currency

This document describes the updated functionality in the Payment SDK, specifically the getDepositAddress and getDepositUrl methods, which now support two additional optional parameters: requestedAmount and requestedCurrency. These parameters allow clients to specify a desired deposit amount and currency. When enabled in the developer settings, deposits are matched against these requests, and callbacks are sent regardless of whether a match occurs.

---

Overview

The SDK now supports requestedAmount and requestedCurrency as optional parameters when generating deposit addresses or URLs. When matching is enabled in the developer settings, incoming deposits are compared against these requests using provided exchange rates (up to 2 decimal places). A callback is always sent to the client’s backend:

• Matched Deposits: Include requestedAmount, requestedCurrency, and exchangeRate.

• Unmatched Deposits: Exclude these fields but still notify of the deposit event.

New Parameters

• requestedAmount: The desired deposit amount (string format, e.g., "100").

• requestedCurrency: The desired currency for the deposit (e.g., USDT, ETH, TRX).

Matching Behavior

• Matching is optional and must be enabled in the developer settings.

• When enabled, deposits are matched against requests based on requestedAmount, requestedCurrency, and exchange rates.

• Matching is performed up to 2 decimal places.

• Callbacks are sent for all deposits, with additional data included only for matched requests.

---

Deposit Matching Configuration

Enabling Matching

• Matching is disabled by default.

• Enable it in the Developer Settings page of the payment gateway dashboard.

• When enabled, deposits are compared against deposit requests using requestedAmount, requestedCurrency, and exchange rates.

Matching Logic

• Deposits are converted to the requestedCurrency using the provided exchange rates.

• The converted amount is compared to requestedAmount (up to 2 decimal places).

• A callback is sent for every deposit, with additional fields included only if a match is found.

Example Exchange Rates

1. Deposit Request 1:

   • requestedAmount: "100"

   • requestedCurrency: USDT

   • exchangeRate: { TRX: 0.1, ETH: 0.01 }

   • Matching: 10 TRX (10 × 0.1 = 1 USDT) or 100 ETH (100 × 0.01 = 1 USDT).

2. Deposit Request 2:

   • requestedAmount: "200"

   • requestedCurrency: USDT

   • exchangeRate: { TRX: 0.2, ETH: 0.02 }

   • Matching: 1000 TRX (1000 × 0.2 = 200 USDT) or 10000 ETH (10000 × 0.02 = 200 USDT).

Scenario

• Deposit: 10 TRX

• Result: Matches Deposit Request 1 (10 × 0.1 = 1 USDT, within 2 decimal places). Callback includes requestedAmount, requestedCurrency, and exchangeRate.

• Deposit: 15 TRX

• Result: No match. Callback is sent without requestedAmount, requestedCurrency, or exchangeRate.

---

Best Practices

• Use referenceId to correlate deposits with specific orders or requests.

• Specify requestedAmount as a string to avoid floating-point precision issues.

• Test matching logic with various deposit amounts and currencies in a testnet environment.

• Handle both matched and unmatched callback payloads appropriately in your backend.

---

Error Handling

• KeyCreationFailure: Thrown if address generation fails on the network.

• UnHealthyKey: Thrown if differential consensus checks fail.

• Use the SDK’s logger to capture and debug errors.