riverty logo


Hosted Fields

Why Hosted Fields is Interesting

Hosted Fields is a solution that lets merchants offer Riverty at checkout without collecting sensitive information themselves.

The solution involves a special text entry box (or any other standard HTML data entry field) that collects data directly to Riverty’s servers, from within the merchant’s website/app. The merchant receives only a proprietary unique ID (nonce). This can be used to identify the customer in calls to the Riverty eCommerce API, but not to resolve the customer’s Personally Identifiable Information. This allows the merchant to avoid the obligations and risks that stem from handling sensitive data.

The solution creates a text entry box in the merchant’s website / app that is an iFrame to Riverty’s servers. Any data entered into this field by the customer is visible only to Riverty’s servers, and not to the merchant. The fields are displayed by the merchant’s website/app, but hosted by Riverty’s servers.


Hosted Fields are designed to collect the customer’s Personally Identifiable Information (name, email, national ID number, address, etc.).

The merchant wants to minimize the amount of PII handled by their systems. However, this information is required by Riverty for its credit/risk checks and to positively identify the customer for invoicing.

The merchant’s customer signup (or checkout) includes a transparently embedded iFrame of a text entry box (or other HTML entry field). The iFrame is hosted on Riverty’s Hosted Fields Server. When the customer submits the form, the contents of the Hosted Field are sent directly from the customer’s device to Riverty’s server, and never pass through the merchant’s systems.

Instead, the merchant receives a nonce – a unique string that can be used as a replacement for the customer’s PII in the Authorize call to the Riverty Payment Methods API. The Payment Methods API takes the nonce and sends it to the Hosted Fields Server, which provides the original data in response over a secure backend connection.

You can use multiple Hosted Fields in one webform. If they are all part of a single Authorize call, the merchant will receive a single nonce in return, and all the collected data will be associated with that nonce.


The solution includes the following components on Riverty’s end:

ID Service:

  • Takes the merchant’s API key
  • Issues an authentication token that can be used with the Hosted Fields Server

Hosted Fields Server:

  • Takes the customer’s authentication token
  • Returns the iFrame code (Hosted Fields Client Library) for the PII field
  • Takes the data that was entered into the hosted PII field
  • Returns the nonce

The nonce can be used for subsequent Riverty eCommerce API calls, as part of the Checkout Customer block. If the nonce is provided, the identificationNumber is optional.

The nonce can be used only with the same merchant API key as the one that was used to generate it. Otherwise, the eCommerce API will reject the call.

The nonce can be used only for a single Authorize call. Each checkout must be conducted with a new nonce.