The purpose of Riverty's Hosted Checkout product is to simplify integrations while delivering an exceptional user experience for customers. This solution was born out of the demand from our Partners and Merchants for a streamlined way to adopt the newest developments within Riverty's payment solutions. It also addresses Riverty's commitment to providing customers with a more human-centric payment experience.
This document first outlines the benefits of the Hosted Checkout solution for customers, partners and merchants. Then, it provides a comprehensive grasp of the Hosted Checkout process and offers guidance on effectively integrating this solution. After reading this document, please visit the Riverty Developer Portal for the most up-to-date information about technical specifics such as endpoints, mandatory fields, and error responses.
Through Hosted Checkout, we present a dedicated payment screen that seamlessly navigates customers through their payment journey by:
- Providing relevant details about the selected payment method
- Collecting required information not captured during the merchant's initial checkout process
- Communicating all required legal information
Riverty Hosted Checkout saves Merchants and Partners from having to make extensive modifications to their checkout flow. Merchants simply have to display the payment method title, tagline, and logo. Riverty does the rest.
Hosted Checkout directly addresses two primary consumer concerns: transparency and security.
- Highlighting Payment Method Advantages: The benefits of the selected payment method are clearly stated in simple language, ensuring consumers are well-informed.
- Removing Uncertainties: The order items are restated and the payment terms are clearly provided in simple terms. Providing a safety net for mis-clicks or other accidental purchases.
- Guided and Secure Information Sharing: The Hosted Checkout offers customers clear guidance in a secure environment to share required KYC information. This might encompass personal details not included in the merchant's initial checkout process.
The primary advantage of Hosted Checkout for our partners is a simplified merchant integration process. Hosted Checkout significantly reduces the need for payment method and country-specific checkout adjustments. Better yet, it provides this simplification while maintaining our existing robust protocols for payment authorization and secure customer authentication.
This smoother implementation experience is available for first-time integrating partners, partners already linked through our REST API, and partners who are transitioning from older API connections. This is achieved by the similarity Riverty designed into all connection types.
Integrating with the Hosted Checkout is forward thinking, granting partners access to the future enhancements that Riverty continually applies to its product offering. These enhancements encompass a spectrum of improvements, spanning from refining the user experience to introducing modern payment options to incorporating the most advanced risk management techniques like SCA (secure customer authentication).
For Merchants with a direct connection to Riverty, the advantages closely align with those outlined for our partners:
- Easy Implementation: no need to configure country and payment specific required fields
- Quick Access to Modernization: Riverty updates are automatically configured
- Seamless User Experience: no confusion around consumer required information and payment terms
Of course, the Hosted Checkout also leverages Riverty’s existing consumer-centric offerings, such as the Riverty mobile app and the MyRiverty consumer portal. This alignment allows your customers to easily manage their payments while clearly maintaining the prominence of your brand identity.
The payment procedure facilitated by the Hosted Checkout closely resembles the validation process available through our Authorize Payment endpoint. The primary distinctions are rooted in the reduced number of obligatory fields and the inclusion of the 'redirect' and 'Get Order' flows.
The sequence of actions for the Hosted Checkout experience is as follows:
- A customer selects products, proceeds to checkout, and initiates a purchase.
- Based on parameters such as order amount, currency, country, and language, the Riverty API fetches available payment methods for the customer.
- The merchant displays these payment options during checkout, from which the customer selects a Riverty payment method.
- Upon order confirmation, a payment request is directed to the Riverty API, resulting in a response with a 'redirectUrl'. This call should contain the final return URL for the customer's eventual return as ‘merchantUrl’.
- Example requests and responses: Hosted Checkout
- Upon redirect, a payment screen emerges, prompting the customer to input additional information (e.g. date of birth or SSN). This screen also displays order and payment details.
- Upon successful payment completion, the customer is redirected back to the provided ‘merchantURL’.
- The merchant then retrieves the order's status by making a GetOrder call using the order number.
- Example requests and responses: Get Order
- The GetOrder status response can manifest as follows:
- 'Accepted': This signifies a successful payment, enabling the merchant to proceed with order handling. Customers should be directed to the order success page.
- 'Cancelled' or 'Expired': In this instance, the payment has failed. The customer should be informed via the CustomerFacingMessage from the order response and guided back to checkout.
- 'Pending': This signifies an ongoing order process that might be awaiting further customer actions, such as verification through Strong Customer Authentication or if the customer has deviated from the process. Pending orders automatically expire after 15 minutes, requiring a new attempt with a new order number.
The variations primarily involve fewer required fields, redirection of customers to the Hosted Checkout, and subsequent steps for obtaining the order status.
Certain customer details, such as date of birth, are not required in the authorization call to the Hosted Checkout endpoint. This provides the merchant with two options:
- The consumer can enter any needed details into the Hosted Checkout directly
- If the merchant has previously collected some of the required consumer information, it can be provided by the merchant during the authorization call to avoid consumers have to re-enter data. This option is dynamic, meaning the merchant can provide the information they have and any missing information will be requested during Hosted Checkout. (This only applies to the fields listed below)
There is also no need to ask for any payment method specific data, this information will be collected in the payment screen of the Hosted Checkout.
Personal information that is not required for the authorization call when using the Hosted Checkout:
|customer → phone
|customer → mobilePhone
|Mobile phone number
|customer → birthDate
|Date of birth
|customer → identificationNumber
|Personal identification number like SSN
Payment method specific data which is not required is the following:
|payment → directDebit → bankAccount
|Bank Account Number (IBAN)
|customer → companyName
|Name of the company
|customer → identificationNumber
|Company identification number or organisation number
|payment → installment → profileNo
|Selected installment profile number
The response to an authorization request directed at the Hosted Checkout endpoint will result in a response with a "redirectUrl".
The partner or merchant is responsible for directing the consumer to this "redirectUrl" and to include a value "merchantUrl" in the payment request. The "merchantUrl" serves as the destination URL where the customer will be redirected to after completing the payment process.
The consumer will be redirected towards the given “merchantURL” when the payment process is completed. From here the partner or merchant should check the status of the order by sending a “Get Order” call towards the get order endpoint: Get Order. The orderNumber is a required field for this endpoint to get the correct response data. For more details, please check “Understanding the Hosted Checkout Process” above.