Handle exception scenarios
The Payments v.3 API endpoints are in beta and may change as we enhance the product. See Migrate crypto payments from v.1 for background on this project.
The final step is to build in handling for exceptions that may occur in the payment flow. The types of webhooks are covered on the Receive Payment Notifications page, but the following guides provide a more detailed explanation of the scenarios.
As cryptocurrency payments are push payments rather than pull ones, BVNK cannot control when and how much cryptocurrency BVNK will receive to complete the customer's payment.
Generally, exception scenarios are caused by user error, hidden or unpredictable fee amounts from the sending exchange, or slow blockchain processing speeds.
Overpayments, underpayments, and late payments all collapse into one mechanism: the payin still reaches a terminal status (COMPLETED in almost every case), but carries a labels[] array that tells you which exception occurred:
OVER: the customer sent more than the requested amount.UNDER: the customer sent less than the requested amount.LATE: funds arrived after the payment had already expired.
If the exception triggered an automatic refund, the payin also carries a relatedPayments[] entry pointing at the payout that was created to return the difference. There are three payment exception scenarios that need to be considered and handled by merchants:
Handle overpayments
The Payments v.3 API endpoints are in beta and may change as we enhance the product. For the concepts this guide builds on, see Payments API v.3.
Handle underpayments
The Payments v.3 API endpoints are in beta and may change as we enhance the product. See Migrate crypto payments from v.1 for background on this project.
Handle late payments
The Payments v.3 API endpoints are in beta and may change as we enhance the product. See Migrate crypto payments from v.1 for background on this project.
Refund payments
The Payments v.3 API endpoints are in beta and may change as we enhance the product. See Migrate crypto payments from v.1 for background on this project.