Hosted Checkout


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.

Example of Hosted Checkout

Hosted Checkout 1.png

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.

Benefits for Customers, Partners, and Merchants

Customer Benefits

Hosted Checkout directly addresses two primary consumer concerns: transparency and security.

  1. Highlighting Payment Method Advantages: The benefits of the selected payment method are clearly stated in simple language, ensuring consumers are well-informed.
  2. 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.
  3. 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.

Partner Benefits

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).

Merchant Benefits

For Merchants with a direct connection to Riverty, the advantages closely align with those outlined for our partners:

  1. Easy Implementation: no need to configure country and payment specific required fields
  2. Quick Access to Modernization: Riverty updates are automatically configured
  3. 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.

Understanding the Hosted Checkout Process

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.

Hosted Checkout 3.png

The sequence of actions for the Hosted Checkout experience is as follows:

  1. A customer selects products, proceeds to checkout, and initiates a purchase.
  2. Based on parameters such as order amount, currency, country, and language, the Riverty API fetches available payment methods for the customer.
  3. The merchant displays these payment options during checkout, from which the customer selects a Riverty payment method.
  4. 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’.
  5. 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.
  6. Upon successful payment completion, the customer is redirected back to the provided ‘merchantURL’.
  7. The merchant then retrieves the order's status by making a GetOrder call using the order number.
  8. 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.

How to Integrate the Hosted Checkout

The Hosted Checkout process closely mirrors the flow of direct integration as described on Get Available Payment Methods and Authorize Payment.

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:

  1. The consumer can enter any needed details into the Hosted Checkout directly
  2. 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.

Difference in Required Fields

Personal information that is not required for the authorization call when using the Hosted Checkout:

Field Description
customer → phone Phone number
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 Methods Field Description
Direct Debit payment → directDebit → bankAccount Bank Account Number (IBAN)
B2B Invoice customer → companyName Name of the company
customer → identificationNumber Company identification number or organisation number
Installments payment → installment → profileNo Selected installment profile number

Redirecting Customers

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.

Get Order Status Afterwards

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.



Change in how requests towards Hosted Checkout endpoint are handled. There is no authorisation call, but a request call that responds with either a ‘redirectUrl’ or a validation error.


Initial version