See the detailed API documentation for more information.
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.
Through Hosted Checkout, we present a dedicated payment screen that seamlessly navigates customers through their payment journey by:
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.
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:
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.
You can seamlessly integrate the Hosted Checkout using either the:
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.
The sequence of actions for the Hosted Checkout experience is as follows:
Integrating Hosted Checkout with a payment selection page involves a process similar to integrating it per payment method, with a few key differences.
To enable the payment selection page, add an additional paymentSelection parameter to the root of the request directed towards the hosted checkout endpoint (/api/v3/hosted-checkout/request):
"paymentSelection": []
This parameter activates the payment selection page. If this parameter is left empty, the payment selection page will be displayed as long as multiple payment methods are available for the customer. If only one payment method is available, the customer will be directed straight to the specific payment method's page to streamline the process.
To control which payment methods are shown, extend the paymentSelection parameter with the desired payment method specifications.
For example, to display the "14/30-day invoice" and "Pay in 3" payment methods, use the following configuration:
"paymentSelection": [
{
"type": "Invoice"
},
{
"type": "PayinX"
}
]
The available payment methods to define are:
Invoice - 14/30 day invoiceConsolidatedinvoice - Consolidated InvoicePayinX - Pay in 3The payment method defined in authorizeRequest → payment → type will be shown as the default and first payment method. We recommend using Invoice as the default payment method.
Direct Debit has a unique approach since it is used in multiple payment methods. Therefore, Direct Debit can be configured with the following options:
For instance, to show both the 14-day invoice and Direct Debit as payment options, use this request configuration:
"paymentSelection": [
{
"type": "Invoice"
"directDebit": "Allowed"
}
]
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:
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:
| 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 |
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.
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:
GetOrder request when the customer is redirected back to the merchant return URL.GetOrder request.GetOrder calls at 30-second intervals.Hosted Checkout is accessible across all countries where we operate, featuring 14/30-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/30-Day Invoice | Consolidated Invoice | Direct Debit | Pay-in-3 | Fixed Installments | Campaign Invoice |
|---|---|---|---|---|---|---|
| Austria | ✔ | ✔ | ✔ | ✔ | ✔ | |
| Belgium | ✔ | ✔ | ✔ | |||
| Denmark | ✔ | ✔ | ✔ | ✔ | ||
| Finland | ✔ | ✔ | ✔ | ✔ | ||
| Germany | ✔ | ✔ | ✔ | ✔ | ✔ | |
| Netherlands | ✔ | ✔ | ✔ | ✔ | ✔ | |
| Norway | ✔ | ✔ | ✔ | ✔ | ||
| Sweden | ✔ | ✔ | ✔ | ✔ | ||
| Switzerland | ✔ | ✔ | ✔ |
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.
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, 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 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.
Do you find this page helpful?