Payment Identifiers
Volume's payment can be identified by three distinct identifiers:
- Payment ID
- Merchant Payment ID
- Payment Reference
These identifiers differ primarily in terms of who generates them, therefore ensures their uniqueness, and their specific use cases.
Payment ID
This is the primary identifier in Volume's payment system. It is automatically generated by Volume's backend when the payer clicks the "Pay" button in the Volume Component.
- Format: UUID
- Uniqueness: Guaranteed for each payment
Availability
- Via a webhook notification about the payment's success or failure
- It is also accessible in the Merchant Portal along with other payment details
Usage
The key feature of Payment ID is that, by fully controlling it, we can ensure it is always unique across all payments. It makes it ideal for ensuring reliable identification of each payment in communications between Volume and the merchant.
Merchant Payment ID
This identifier serves as a payment correlation ID from the merchant's perspective. It is input by the merchant into the Volume Component.
- Null values: Not permitted
- Uniqueness: Required to be unique
- Format: Alphanumeric characters only (letters and digits), up to 50 characters
Unlike the Payment ID, the Merchant Payment ID can be generated and stored upfront by the merchant's system.
Merchant Payment ID Regeneration
Each payment must be assigned a unique Merchant Payment ID. Merchants are required to generate and assign a new Merchant Payment ID for every payment attempt, regardless of whether the attempt is successful.
The Volume Component emits an event for each payment attempt. Merchants must implement an appropriate event handler or listener to ensure a new, unique Merchant Payment ID is generated and provided to the Volume Component at each occurrence.
A detailed description of Volume Component events is available in the SDK documentation under the respective event sections.
Recommended practice: Generate the Merchant Payment ID from your backend system and persist it, so it can be used later to correlate with webhook notifications sent from Volume referencing the same Merchant Payment ID.
If a payment is initialized with a non-unique Merchant Payment ID, the Payer will be redirected to the merchant callback URL with an error.
Availability
- Via a webhook notification about the payment's success or failure
- It is also accessible in the Merchant Portal along with other payment details
Usage
The Merchant Payment ID enables merchant to correlate payment information received via webhook with their internal systems. While Volume does not control its uniqueness across all payments, we ensure no two successful payments share the same Merchant Payment ID.
Payment Reference
Payment Reference is yet another payment identifier. What makes it different are scenarios in which it is available therefore useful. Since Payment Reference is an official payment attribute in banking systems, in most banks it will be visible in bank's system for each payment. This makes it the only payment identifier that allows us to correlate payment that Payer sees in the bank with Volume payment visible in our system.
- Uniqueness: Must be unique within Merchant's Application
- Format: Alphanumeric characters only (letters and digits), up to 18 characters
❗Important note on who is responsible for providing Payment Reference
Currently, for compatibility, Volume accept Payment References value provided by the merchant. However, we strongly recommend submitting a unique value in the Volume Component per each payment. The same regeneration mechanisms as for the Merchant Payment ID should be used to make sure that each payment has unique reference value. Merchant-provided Payment Reference will be deprecated in the future, and Volume will generate them. Payment Reference will still be available in the webhook notifications.
Availability
- Via a webhook notification about the payment's success or failure
- It is also accessible in the Merchant Portal along with other payment details