Hosted Checkout

Introduction

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.

Example of Hosted Checkout

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

You can seamlessly integrate the Hosted Checkout using either the:

• Direct payment method integration
• Integration via a payment selection page.

Opting for the direct payment method integration offers greater flexibility by allowing you to display payment methods individually during checkout, eliminating an additional step in the process.

On the other hand, integration via the payment selection page is more standardized, making it easier to implement. With this approach, only one Riverty payment method appears in the checkout, requiring the consumer to select their preferred payment method within the Hosted Checkout interface.

Both integrations 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.

Integrate Hosted Checkout per payment method

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.
   • More information on the Get Available Payment Methods: Get Available Payment Methods
   • Example requests and responses: Available Payment Methods
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’.
   • Example requests and responses: Hosted Checkout
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.
   • Example requests and responses: Get Order
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.

Integrate Hosted Checkout with a payment selection page

Integrating Hosted Checkout with a payment selection page follows a sequence of actions similar to integration per payment method. However, there are some distinctions:

1. Instead of displaying specific payment methods in the checkout, a single generic Riverty payment method is presented to the consumer.
2. The request towards the hosted checkout utilizes a different endpoint (/api/v3/hosted-checkout/payment-methods). While this request can include a selection of payment methods that the merchant or partner wishes to display to the customer, it is not mandatory.
3. If there are multiple payment methods available for the consumer, they will encounter a payment selection page. This page allows them to select their preferred payment method. However, if only one payment method is available, the payment selection page is skipped, and the consumer is directed straight to the payment page for that specific method.

Differences between the Hosted Checkout vs. direct API integration

The hosted checkout is aimed to make the integration more easily and generic, so that less payment and country specific changes are needed.

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.

Enhance Order Status Timing with Webhook Utilization

To enhance the timing of order status retrieval, we provide the option to include a webhook URL in the initial request for obtaining the hosted checkout page. Refer to our API reference for specific parameter details regarding this field. The webhook URL should be accessible to Riverty to facilitate a POST request with the following structure:

{
  "orderNo": "12345"
}

This webhook serves as a notification that the order has transitioned to a final status, prompting the merchant to execute a GetOrder request to retrieve the accurate final status.

In the absence of using this webhook, we recommend the following timing guidelines:

• Trigger the GetOrder request when the customer is redirected back to the merchant return URL.
• If the customer does not return within one minute, automatically trigger the GetOrder request.
• While the order status remains "Pending," continue sending GetOrder calls at 30-second intervals.
• If 15 minutes elapse without an update, the order status will automatically transition to "Expired."

Availability and Functionality

Countries and Payment Methods

Hosted Checkout is accessible across all countries where we operate, featuring 14-day invoicing and Consolidated Invoice options. Direct Debit is exclusively offered in Germany, Austria, and the Netherlands. Additionally, Pay in 3 is exclusively available in the Netherlands.

Country	14-Day Invoice	Consolidated Invoice	Direct Debit	Pay-in-3
Austria	✔	✔	✔
Belgium	✔	✔
Denmark	✔	✔
Finland	✔	✔
Germany	✔	✔	✔
Netherlands	✔	✔	✔	✔
Norway	✔	✔
Sweden	✔	✔
Switzerland	✔	✔

Additional Services

In addition to supporting various payment methods, Hosted Checkout also provides additional services such as Strong Customer Authentication, Profile Tracking, and Idempotency. Importantly, no further development is required to utilize these services.

Strong Customer Authentication

SCA, outlined on this page, is designed to enhance security by reducing fraud in online payments, thereby fostering consumer trust. SCA is seamlessly integrated into Hosted Checkout without necessitating additional development. Following order confirmation on the payment page, consumers may encounter an additional authentication step depending on the country-specific eID method used. Once authenticated, consumers are directed to the provided merchantUrl in the original request.

Profile Tracking

Profile Tracking, detailed on this page, serves to identify and track internet access devices (e.g., PCs, smartphones, tablets) to detect potential fraudulent activities. Hosted Checkout automatically activates Profile Tracking for applicable countries, ensuring compliance with relevant legal regulations.

Idempotency

Idempotency enhances system resilience by allowing API calls to be repeated until a satisfactory response is received in case of message loss during transmission. Authorize requests from Hosted Checkout inherently utilize Idempotency, bolstering the resilience of payment integrations.