Overview
UniPayment provides a seamless invoice-based payment solution, enabling merchants to accept payments via digital currencies, cards, and other e-wallets. This guide covers key aspects of invoice integration, including invoice payment flow, statuses, expiration handling, and notifications.
Invoice Payment Flow
The invoice payment process involves multiple interactions between the Client, Website/CRM, Gateway, and Cashier components. The following steps outline the invoice payment flow:
Client initiates checkout or deposit – The client attempts to make a payment on the merchant's website or CRM.
Invoice creation – The merchant's system requests an invoice creation from the payment gateway.
Client redirection to cashier – The client is redirected to the cashier via the provided
invoice_url, where they can complete the payment.Payment completion – The client completes the payment using cryptocurrency, a card, or an alternative payment method (APM).
Post-payment handling:
5-1. Redirect client to merchant website – Upon successful payment, the client is redirected back to the merchant's website.
5-2. Send notification – The payment gateway sends a status notification via
notify_urlto update the merchant's system.
This process ensures that merchants receive real-time updates about the payment while providing a seamless user experience. Failed payment attempts are logged in the merchant dashboard, allowing the customer to retry payment attempts until the invoice expires.
Invoice Statuses
An invoice in UniPayment progresses through different statuses during its lifecycle. Understanding these statuses is crucial for proper integration and handling of payment workflows.
1. New
The initial state of an invoice, applicable to all payment methods (e.g., cryptocurrencies, cards, Skrill, Neteller).
The invoice remains in this state until a payment attempt is made.
2. Paid
Indicates that payment has been received and matches the invoice amount.
Payment evaluation is performed before transitioning to the next stage.
3. Confirmed
Payment has been validated and is ready for order fulfillment by the merchant.
4. Complete
The payment process is fully finalized, and the merchant’s account has been credited.
This is a terminal state for successful transactions.
5. Expired
The invoice has exceeded its payment window without receiving a valid payment.
Default expiration times:
Digital currency payments: 20 minutes (configurable in the payment application).
Card payments: 1 day.
After expiration, an additional 30-minute observation window applies.
6. Invalid
Payment was initiated and processed but encountered an issue during settlement.
The transaction remains incomplete and cannot be credited.
Key Differences Between Invoice Payments and Card Transactions
Unlike traditional card transactions, where a failed payment attempt results in an immediate failure status, invoices allow multiple payment attempts until expiration. This is particularly relevant for cases where customers retry payments due to errors or insufficient funds.
Card Acquirer Transactions
A single payment attempt per transaction.
If payment fails, the transaction is considered complete (failed state).
The customer must initiate a new payment if they wish to retry.
Invoice Transactions
Customers can attempt payment multiple times before the invoice expires.
Payment failures do not result in an immediate failure state for the invoice.
All payment attempts are logged in the merchant’s console dashboard for review.
The invoice remains active until it expires or is completed.
Since invoices allow multiple attempts, it is not necessary to explicitly track failed payments at the invoice level. The merchant can review failed attempts through the dashboard.
Invoice Expiration Handling
Each invoice has a predefined expiration time:
Crypto currency payments: Expire after 20 minutes (configurable in the payment app).
Card payments: Expire after 1 day.
After expiration, an additional 30-minute observation window applies, allowing merchants to handle potential delayed payment updates.
Invoice Status Notifications
UniPayment provides real-time status updates through notify_url, allowing merchants to synchronize their local order management system.
Notification Best Practices
Use notify_url for status updates
Merchants should rely on notify_url for invoice status updates instead of polling.
The invoice status will be automatically updated and sent to the merchant’s system.
Handle missed notifications with periodic status checks
While notify_url provides real-time updates, network issues can sometimes cause notifications to be lost.
It is recommended to periodically check the status of invoices that are neither expired nor complete to ensure proper synchronization.
Avoid excessive polling
Frequent polling can increase API load and is not an efficient way to track invoice status.
Instead, use event-driven updates via notify_url for optimal performance.
By following these guidelines, merchants can ensure a smooth integration and efficient payment processing using UniPayment’s invoice system.