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 have a unique Merchant Payment ID. Merchant must update this ID for each payment attempt, regardless of its success. For each payment attempt Volume Component emits event, merchant must implement an event handler/listener to ensure that a new, unique Merchant Payment ID value is provided for the Volume Component. Detailed description of Volume Component events can be found in their dedicated section for each of them (SDKs). Recommended way of generating new Merchant Payment ID is to generate it from the backend system and store to be able to match it later whenever webhook notification will be sent from Volume with the same Merchant Payment ID. When payment will be initialized with a non-unique value, Payer will be redirected to merchant callback 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