Riverty for API only

Add Riverty to an existing API only integration.

Accept Riverty payments using an existing API only integration.

Requirements

Requirement	Description
Integration type	Make sure that you have built an API-only integration.
Setup steps	Before you begin, add Riverty in your test Customer Area.

Process overview

When accepting a payment with Riverty:

Collect your shopper's details, and specify these in your /payments request.
Provide information about the purchased items in the lineItems object of your /payments request.
Use Riverty’s profile tracking technology to calculate the profile tracking ID, and specify this in your /payments request.
Capture the payment after the goods are sent. This triggers the invoice that the merchant sends to the shopper.

When using profile tracking

When making a Riverty payment, profile tracking is a requirement in DE, AT, CH. It is used for risk evaluation of shoppers.

Implement profile tracking by using a Riverty script that calculates a profile tracking ID for each shopper. Use the script in one of two ways:

Run the script when the shopper is on your checkout page.
The script collects data about the shopper’s device, the so-called profile tracking ID, to be able to predict scripted attacks. This data can be encrypted in a string which can be sent in the /payments request as deviceFingerprint.
You need a Riverty profileTrackingShopId for the profile tracking integration. Get this profileTrackingShopId from Riverty’s implementation support team via implementation_BNPL@riverty.com.
Redirect the shopper to a page hosted by Riverty that will run the script.
If the deviceFingerprint value is missing in the /payments request, the result of the transaction attempt might be redirectShopper (as explained below). You are to then redirect the shopper to a Riverty hosted page where the same profile tracking script is already implemented to ensure in the end the transaction is compliant with regulation.

To improve the customer experience and reduce the number of transactions that are redirected, it is advisable to run the script when the shopper is on your checkout page.

Build your payment form for Riverty

To show Riverty in your payment form, specify one of the following combinations in your /paymentMethods request:

Country/region	`countryCode`	`amount.currency`
Germany	DE	EUR
Austria	AT	EUR
Switzerland	CH	CHF
Netherlands	NL	EUR
Belgium	BE	EUR

To make a Riverty payment, you need to collect the following shopper details:

Name	Description
`firstName`	Shopper's first name.
`lastName`	Shopper's last name.
`dateOfBirth`	Shopper's date of birth.
`telephoneNumber`	Shopper's phone number.
`shopperEmail`	Shopper's email address.
`billingAddress`	The address where to send the invoice.
`deliveryAddress`	The address where the purchased goods should be delivered.

We provide a Riverty logo which you can use in your payment form. For more information, refer to Downloading logos.

Make a payment

Riverty uses profile tracking technology to detect and recognize internet access devices (e.g. PCs, smartphones, tablets, etc.) and to identify possible fraud attempts on your websites. Before making a payment you need to implement Riverty’s profile tracking integration. Send the calculated profile tracking ID when making a /payments request.

You need a Riverty client ID for the profile tracking integration. Get this client ID from your Adyen contact person or by reaching out to support@adyen.com.

From your server, make a /payments request:

Parameter	Required	Description
paymentMethod.type		The type of Riverty payment. Possible values: - riverty: Pay in 14. - riverty_account: Monthly Consolidated Invoice. - sepadirectdebit_riverty: Secure Direct Debit.
`paymentMethod.iban`		When the paymentMethod.type = sepadirectdebit_riverty provide the IBAN of the shopper.
deviceFingerprint		A string containing the shopper's calculated profile tracking ID.
shopperName.firstName		Shopper's first name. (B2B payments are currently not supported. Providing a business name here may result in a rejection.)
shopperName.lastName		Shopper's last name. (B2B payments are currently not supported. Providing a business name here may result in a rejection.)
telephoneNumber		Shopper's telephone number.
shopperEmail		Shopper's email address.
dateOfBirth		Shopper's date of birth, in format: YYYY-MM-DD
shopperIP		The shopper's IP address. Riverty uses this for risk checks.
billingAddress		The address where to send the invoice.
deliveryAddress		The address where the purchased goods should be delivered. If the shopper is using Riverty for the first time, the payment can be rejected if `deliveryAddress` is different from `billingAddress`, for risk reasons. If `deliveryAddress` is different from `billingAddress`, the following fields are required to identify the recipient at the delivery address: `deliveryAddress.firstName` and `deliveryAddress.lastName`.
lineItems		Price and product information about the purchased items. This is included on the invoice that Riverty sends to the shopper.

The /payments response contains:

Parameter	Description
`resultCode`	Use this to present the payment result to your shopper.
`pspReference`	Our unique reference for the payment.
`merchantReference`	Your `reference` from the /payments request.

Present the payment result

Use the resultCode that you received in the /payments response to present the payment result to your shopper.

The response to your /payments request depends on the shopper’s country. Some countries require strong customer authentication and potentially a manual order review performed by Riverty.

The resultCode values you can receive for Riverty are:

resultCode	Type of flow	Description	Action to take
Authorised	sync	The payment was successfully authorised.	Inform the shopper that the payment was successful. After the goods have been sent, you also need to capture the payment.
Refused	sync	The payment was refused by Riverty.	Ask the shopper to try the payment again using a different payment method.
redirectShopper	async	The shopper must be redirected to a page of Riverty where additional risk verification(s) will be performed.	When the shopper is redirected back to the URL specified in the `returnUrl` of the /payments request, use a /payments/details request to find the outcome of this event. The most likely scenario is definitive, meaning the shopper either completed the flow successfully or not. In rare scenarios, the status will still be pending, as the verification process has been stepped up to the Manual Order Review process.

redirectShopper

In the /payments response, note the action object. This contains the information needed to redirect the shopper.

Handle the redirect

To complete the payment, redirect the shopper to the action.url returned in the /payments response.

When using the HTTP GET method:
For security reasons, when displaying the redirect in the app, we recommend that you use SFSafariViewController for iOS or Chrome Custom Tabs for Android, instead of WebView objects. Also refer to the security best practices for WebView.
After the shopper is redirected back to your website, check the payment result by making a POST /payments/details request, specifying:
- details: the object that contains the URL-decoded redirectResult returned when the shopper was redirected back to your site.

Capture the payment

After the goods have been sent, you also need to capture the payment. All Riverty payments must be manually captured, even if you have enabled automatic capture for other payment methods. Capturing the payment is what triggers the invoice to be sent to the shopper and starts the payment schedule. If you do not manually capture the payment within 30 days, the authorization will expire.

Partial captures

To partially capture a Riverty payment, specify in your /payments/{paymentPspReference}/captures request:

Parameter	Description
`amount`	The amount that the shopper should pay.
`lineItems`	Price and product information for the items that the shopper should pay for. You only need to specify `lineItems` if you are sending a partial capture, not if you are sending a full capture. The sum of the `lineItems` must match the amount declared in the capture call, otherwise Adyen will add a dummy `lineItems` entry to account for the difference.

Only specify the items that you are capturing. Any unclaimed amount that is left after partially capturing a payment should be manually cancelled.

To set up multiple partial captures, contact our Support Team. Multiple partial captures will create a new invoice for each capture.

The following example shows how to make a partial capture request if the shopper only kept item #1 of the order.

The following response is returned:

Manually cancel any amount that remains after partially capturing a payment.

If a part of the authorized amount has been captured, simply sending an empty /payments/{paymentPspReference}/cancels request releases the remaining balance (without having to specify the lineItems remaining that need to be canceled).

To set up multiple partial captures, contact our Support Team. Multiple partial captures will create a new invoice for each capture.

Refunds and cancellations

If you have not captured a Riverty payment, you can cancel it. If you have captured the payment and you want to return the funds to the shopper, you need to refund it.

As with captures, you don’t need to specify lineItems in the refund request if you are doing a full refund. To partially refund a Riverty payment, specify in your /payments/{paymentPspReference}/refunds request:

Parameter	Description
`amount`	The amount that is refunded to the shopper.
`lineItems`	Price and product information for the items that the shopper should pay for. The sum of the `lineItems` needs to match the amount declared in the refund call. If they do not match, Adyen will add a dummy `lineItem` entry to account for the difference.
`capturePspReference`	Specify which capture needs to be refunded when doing partial refunds. If not specified, the last capture will be chosen automatically, whether that was the intended capture to be refunded or not.

Only specify the items that you are refunding the money for.

The following example shows how to make a partial refund for item #1 of the above order.

The following response is returned:

The pspReference in the response is the reference of the refund itself.

Test and go live

To test Riverty, submit a request to add Riverty in your test Customer Area.

Riverty provides detailed error codes, recommendations on how to test some of the most common scenarios as well as a comprehensive list of market specific test data.

Test redirect flow

To test the redirect flow, provide firstName : Risky and lastName : SCA-H in the /payments request.

Go-live requirements

Riverty requires you to display Terms & Conditions as well as data protection guidelines in your checkout for the shopper to approve before making the payment. See Riverty's documentation for details.