What is partial payment on XRPL?
Last updated:
Partial payments are a specialized transaction type on the XRP Ledger that allows payments to deliver less than the specified destination amount without failing. This feature is critical for cross-currency transactions where exact conversion rates may be uncertain or liquidity is limited, but it has been historically exploited to defraud exchanges, making proper implementation crucial.
Partial payments use the tfPartialPayment flag in the Flags field of a Payment transaction. When this flag is set, the transaction succeeds if it delivers any amount up to the destination Amount, rather than requiring exact delivery. The DeliveredAmount metadata field shows the actual amount received, which may be less than the Amount specified.
The primary legitimate use case for partial payments is cross-currency transactions on the decentralized exchange. When converting between currencies, market liquidity and order book depth affect the conversion rate. Without partial payments, a transaction might fail if it cannot deliver the exact destination amount due to slippage or insufficient liquidity. Partial payments allow the transaction to complete, delivering the maximum possible amount.
For example, if you want to send approximately 100 EUR but aren't certain the exact XRP-to-EUR conversion rate at execution time, you could send a partial payment with a destination amount of 100 EUR. If only 95 EUR worth of XRP can be converted due to liquidity, the transaction succeeds delivering 95 EUR rather than failing completely.
The SendMax field works with partial payments to limit the maximum source amount consumed. This protects senders from excessive conversion costs. A partial payment might specify Amount (destination) of 100 USD with SendMax of 50 XRP. The transaction will deliver up to 100 USD while consuming at most 50 XRP, succeeding even if it delivers less than 100 USD.
The major security concern with partial payments is the potential for exploiting systems that don't check delivered amounts correctly. The infamous "partial payment exploit" affected several cryptocurrency exchanges between 2018 and 2019. Attackers would send partial payments with large Amount values but small delivered amounts, while vulnerable exchange systems credited accounts based on the Amount field rather than actual delivery.
For instance, an attacker might send a partial payment specifying Amount of 1,000,000 XRP but with SendMax of only 100 XRP. If the exchange's deposit processing looked only at the Amount field, the attacker's account would be credited with 1,000,000 XRP while they only sent 100 XRP. The attacker could then withdraw real XRP, defrauding the exchange.
Preventing partial payment exploits requires checking the delivered_amount field in transaction metadata rather than the Amount field in the transaction specification. For transactions after 2014, the delivered_amount field provides the authoritative amount delivered. For older transactions, calculations must account for partial payment logic.
Exchanges and payment processors should reject incoming partial payments entirely unless they have specific business reasons to accept them. Most deposit processing has no legitimate need for partial payments - users should send exact amounts. Rejecting all partial payments eliminates the exploit vector entirely.
Developers integrating XRPL payment processing should implement multiple safeguards including checking transaction flags for tfPartialPayment, validating delivered amounts against expected amounts, alerting on any discrepancies, and rejecting partial payments in deposit processing. The XRPL documentation provides specific guidance on safe handling.
Partial payments remain valuable for applications requiring flexible cross-currency transactions. Decentralized exchange interfaces, payment bridges, and liquidity aggregators benefit from partial payment functionality. However, these specialized use cases require careful implementation by developers who understand the security implications.
The partial payment feature demonstrates a broader principle in XRPL development: powerful features require careful implementation. The protocol provides sophisticated functionality enabling complex financial operations, but developers must understand each feature's security characteristics and implement appropriate safeguards.