Riverty offers consolidated Invoice payment option for consumers who regularly make small purchases. Consolidated Invoice bundles smaller purchases into one single invoice and ideal for marketplaces, recurring loyal customers as well as perfect match for mobility (including parking, ride sharing etc). The payment term starts from the date on which the consolidated invoice is issued, usually at the beginning of the month connected to the salary schedule of consumers. Each order added is evaluated separately, added to the customer account statement over the period, and consolidated into one invoice at the end of that period.
For merchants that provide parking services to their customers, Riverty offers a Consolidated Invoice with Direct Debit payment option, streamlining the payment process for both the merchant and the consumer. This solution is designed to bundle multiple small parking transactions into a single, easy-to-manage invoice. By utilizing Direct Debit, one payment is automatically debited from the customer's bank account on the due date, ensuring timely and hassle-free transactions. This not only simplifies financial management for customers by reducing the number of individual payments they need to track but also ensures a steady and reliable cash flow for merchants. The Consolidated Invoice with Direct Debit is particularly beneficial for businesses in the mobility sector, including parking, as it enhances customer satisfaction through convenience and efficient payment processing.
To successfully use the Consolidated Invoice product, customers begin their journey with authorization and the completion of the penny drop verification process. Penny drop is a secure method used to confirm the validity of a bank account, ensuring seamless future direct debit withdrawals. Riverty uses the information from this process to facilitate future direct debit withdrawals.
Once the penny drop verification is completed and the customer passes Riverty's risk check, all purchases made over the course of a month are aggregated into a single consolidated invoice. At the start of the next month, the customer will receive this monthly invoice and be notified about the upcoming direct debit payment withdrawal from their bank account.
If the direct debit payment fails, Riverty notifies the customer, requesting manual payment of the outstanding amount, which may include any associated chargeback fees. Should the customer miss the payment deadline, Riverty sends multiple reminders to encourage timely payment and to avoid the initiation of the debt collection process.
Upon successful direct debit withdrawal from the customer's bank account, Riverty proceeds with the settlement process, ensuring that the merchant receives the funds.
Consolidated Invoice can be listed at the merchant checkout just like any other payment method allowed by the merchant. When the customer decides on Consolidated Invoice.
There are some requirements dictated by the Dutch BNPL Code of Conduct which is a voluntary code that is followed by Riverty and the other major BNPL providers in the Netherlands. The code explains how BNPL providers will treat their customers and merchants including what levels of information and service each can expect from their respective providers.
Merchants also need to play their role in informing our mutual customers of their obligations to pay on time in order to avoid additional fees. The code requires merchants to add a standard text to their check out either before, during or after the choice of BNPL provider. The disclaimer should be added in the local language (Dutch). An English version is provider for developer information only. Please check the link for examples how present Riverty at checkout.
English
''You must be at least 18+ to use this service. If you pay on time, you will avoid additional charges and ensure that you can use [Riverty's] services again in the future. By continuing, you accept the Terms and Conditions and confirm that you have read the Privacy Statement and Cookie Statement.''
Dutch
"Je moet minimaal 18+ zijn om deze dienst te gebruiken. Als je op tijd betaalt, voorkom je extra kosten en zorg je dat je in de toekomst nogmaals gebruik kunt maken van de diensten van [Riverty]. Door verder te gaan, accepteer je de Algemene Voorwaarden en bevestig je dat je de Privacyverklaring en Cookieverklaring hebt gelezen."
Merchants need to add the specific payment related information to their checkout process to ensure transparency and compliance with banking regulations. The authorization notice informs customers that they are consenting to Riverty GmbH initiating a debit from their bank account, making them aware of and agreeing to the transaction. The exact text to include to the checkout:
Dutch:
Hierbij geef je toestemming aan (A) Riverty om je bank opdracht te geven een bedrag van je rekening af te schrijven. Ook geef je toestemming aan (B) je bank om dit bedrag af te schrijven van je rekening in overeenstemming met de opdracht van Riverty. Indien je het niet eens bent met de afschrijving, heb je het recht om deze binnen 8 weken na de betaaldatum terug te boeken in overeenstemming met de voorwaarden van je bank. Je rechten worden verder toegelicht in een verklaring die je kunt krijgen bij je bank.
English:
You herewith authorise (A) Riverty GmbH to send instructions to your bank to debit your account and (B) your bank to debit your account in accordance with the instructions from Riverty. As part of your rights, you are entitled to a refund from your bank under the terms and conditions of your agreement with your bank. A refund must be claimed within 8 weeks starting from the date on which your account was debited. Your rights are explained in a statement that you can obtain from your bank.
Be sure to sign up for a Riverty Merchant Portal Account or request access from Riverty implementation team member. Individual transactions are managed through the Merchant Portal, along with access to many other features like financial reports and branding.
You can receive a Test Authorization Key from your Merchant Portal Account or from a Riverty Implementation Team member.
Before starting, it's important to take the following steps:
To achieve optimal results, the following API calls must be integrated into client ecosystem according to best practices:
The registration of the customer occurs during the Authorize Payment call. This is a mandatory step for all transactions, transferring all consumer information to Riverty's system. This call activates Riverty's Risk engine, which verifies the provided information and determines if the customer qualifies for the parking/transaction. The authorization response indicates whether Riverty accepts the consumer. For more details, refer to the comprehensive API documentation. Endpoint: /api/v3/checkout/authorize
API request consists of 3 objects:
{
"order": {
"items": [
{
"imageUrl": "",
"quantity": 1,
"productId": "1",
"vatAmount": 0,
"productUrl": "",
"vatPercent": 0,
"description": "Customer Registration",
"netUnitPrice": 0.01,
"grossUnitPrice": 0.01,
"additionalInformation": "Customer Number Registration"
}
],
"number": "custom{{ORDER_NUMBER}}",
"currency": "EUR",
"totalNetAmount": 0.01,
"totalGrossAmount": 0.01
},
"payment": {
"type": "ConsolidatedInvoice"
},
"customer": {
"email": "{{customerEmail}}",
"address": {
"street": "{{customerStreetName}}",
"postalCode": "{{customerZipCode}}",
"countryCode": "{{customerCountryCode}}",
"postalPlace": "{{customerState}}",
"streetNumber": "5",
"streetNumberAdditional": "1"
},
"lastName": "{{customerLastname}}",
"riskData": {
"ipAddress": "{{customerIP}}",
"existingCustomer": false,
"customerIndividualScore": "1"
},
"salutation": "Mr",
"mobilePhone": "{{customerPhoneNumber}}",
"customerCategory": "Person",
"conversationLanguage": "{{customerConversationLanguage}}"
},
"deliveryCustomer": null
}
Riverty will then respond with a customer number assigned: _"customerNumber": "116501 _ that needs to be stored and mapped to the specific customer on client side.
{
"outcome": "Accepted",
"checkoutId": "0a745033-ec3b-4a1e-936f-c68c993ca67e",
"reservationId": "52404b03-16a0-4f49-9eea-73430acb46dc",
"customerNumber": "AP000154781",
"expirationDate": "2024-08-28"
}
In case customer is rejected ("outcome": "Rejected"), it is recommended to direct customer to alternative payment method. In addition, in response Riverty will supply customer facing message that can be shown to the customer. You can find more information about other errors encountered after authorization here.
{
"outcome": "Rejected",
"customer": {
"lastName": "LASTNAME",
"firstName": "Reject",
"addressList": [
{
"street": "Street",
"postalCode": "12345",
"countryCode": "NL",
"postalPlace": "FARSTA",
"streetNumber": "1"
}
]
},
"checkoutId": "0a745033-ec3b-4a1e-936f-c68c993ca67e",
"reservationId": "52404b03-16a0-4f49-9eea-73430acb46dc",
"riskCheckMessages": [
{
"code": "200.901",
"type": "BusinessError",
"message": "Negative Customer Score",
"actionCode": "OfferSecurePaymentMethods",
"customerFacingMessage": "Unfortunately, the payment method is currently not available. Please select another payment method."
}
]
}
In case customer was registered successfully, the client should now save the consumer data together with the assigned customerNumber for a real live parking session. Therefore the partner now void 1 cent order done during the authorization call. Here you can find more about void API specification and also learn about possible void call responses. Endpoint: /api/v3/orders/{orderNumber}/voids
{
"cancellationDetails": {
"items": [
{
"imageUrl": "",
"quantity": 1,
"productId": "1",
"vatAmount": 0,
"productUrl": "",
"vatPercent": 0,
"description": "Customer Registration",
"netUnitPrice": 0.01,
"grossUnitPrice": 0.01,
"additionalInformation": "Customer Number Registration"
}
],
"currency": "EUR",
"totalNetAmount": 0.01,
"totalGrossAmount": 0.01
}
}
After obtaining the customer number and voiding authorization, the next step is the penny drop process. The purpose of penny drop is to securely retrieve the customer's IBAN number while minimizing the risk of typographical errors. During the penny drop flow a customer performs a payment of 0.01 € (or in Belgium 0.02€) as a means of authentication. By performing this micro payment Riverty receives information about the customer and their bank details to verify their identity with. For example, to validate if an IBAN really belongs to a specific customer. After completing the payment the charged amount is deducted. Customers complete this payment through iDEAL (NL) or Bancontact (BE). When the time comes, we will use this verified IBAN to execute direct debit charges. API specification can be found here.
For successful request such fields as "countryCode", "conversationLanguage", "riskData" needs to be passed. Endpoint: /api/v3/customers/{{customerNumber}}/direct-debit.
{
"IBAN": "",
"riskData": {
"customerSince": "",
"existingCustomer": false,
"numberOfTransactions": 0
},
"countryCode": "NL",
"conversationLanguage": "{{customerConversationLanguage}}"
}
Riverty will provide a link in the response. The client needs to add to the link query parameter (should be url-encoded) which is a page where client wants to direct the user after IBAN validation process. For instance, the link might look like this: https://bank-account.bnpl-pt.riverty.io/bank-account/3237f09b40b9408dbadbccb8d556e8f2?merchantUrl=https://client.nl/
{
"outcome": "Pending",
"redirectUrl": "https://bank-account.bnpl-pt.riverty.io/bank-account/3237f09b40b9408dbadbccb8d556e8f2",
"registrationID": "3237f09b40b9408dbadbccb8d556e8f2",
"redirectUrlExpirationTime": "2024-05-31T06:49:03Z"
}
After customer registered and IBAN is validated, parking session can start. During each new parking session additional risk validation will be done on Riverty side. When customer starts parking, client needs to send authorize request with customer number.
API request consists of 3 objects:
{
"order": {
"items": [
{
"imageUrl": "{{productImageUrl}}",
"quantity": 1,
"productId": "1",
"vatAmount": "{{serviceVAT}}",
"productUrl": "",
"vatPercent": 21,
"description": "Parking fee for {{serviceUserLicencePlate}} in area {{serviceUserAreaName}}",
"netUnitPrice": "{{servicePrice}}",
"grossUnitPrice": "{{servicePriceGross}}",
"additionalInformation": "Initial customer parking amount"
}
],
"number": "{{ORDER_PREFIX}}_{{TESTID}}_{{ORDER_NUMBER}}",
"currency": "EUR",
"invoiceNumber": null,
"totalNetAmount": "{{servicePrice}}",
"merchantImageUrl": "{{merchantURL}}",
"totalGrossAmount": "{{servicePriceGross}}",
"parentTransactionReference": null
},
"payment": {
"type": "ConsolidatedInvoice",
"recurringDirectDebit": {
"bankCode": null,
"bankAccount": null,
"mandateReference": null,
"contractAcceptedDate": null,
"directDebitAgreement": "useexisting"
}
},
"customer": {
"email": "{{customerEmail}}",
"address": {
"street": "{{customerStreetName}}",
"postalCode": "{{customerZipCode}}",
"countryCode": "{{customerCountryCode}}",
"postalPlace": "{{customerState}}",
"streetNumber": "5",
"streetNumberAdditional": 1
},
"lastName": "{{customerLastname}}",
"riskData": {
"ipAddress": "{{customerIP}}",
"customerIndividualScore": "1"
},
"birthDate": "{{customerBirthDate}}",
"firstName": "{{customerFirstname}}",
"salutation": "Mr",
"customerNumber": "{{customerNumber}}",
"customerCategory": "Person",
"conversationLanguage": "{{customerConversationLanguage}}"
},
"deliveryCustomer": null
}
In case the start parking authorization call was rejected, it is recommended to direct customer to the prepaid payment option.
In case real parking deviates for the parking user initiated, for example, it was longer or it was shorter. Client can update the parking order with new information. More about the API call and possible responses can be found here. Endpoint: /api/v3/orders/{orderNumber}/updateOrder.
{
"updateOrderSummary": {
"items": [
{
"imageUrl": "{{productImageUrl}}",
"quantity": 1,
"productId": "1",
"vatAmount": 6.39,
"productUrl": "",
"vatPercent": 19,
"description": "Extended Parking",
"netUnitPrice": 33.61,
"grossUnitPrice": 40,
"additionalInformation": "Extended Parking Amount"
}
],
"totalNetAmount": 33.61,
"totalGrossAmount": 40
}
}
When parking is finished, capture request should be sent. Capture request should include the most up-to-date information about the parking session including its start _"serviceStart" _and end "serviceEnd" time. In addition, in "specification" object, client can specify additional details about the parking session. Information supplied in this call will be shown to the customer in the invoice. You can find overview of the API call following the page:https://docs.riverty.com/bnpl/api_reference/capture_payment.
{
"orderDetails": {
"items": [
{
"type": "DigitalArticle",
"groupId": "Parking Fee",
"imageUrl": "{{productImageUrl}}",
"quantity": 1,
"productId": "1-{{serviceUserCurrentCountry}}-256-544546",
"vatAmount": "{{serviceVAT}}",
"productUrl": "",
"serviceEnd": "{{ServiceEndTime}}",
"vatPercent": 21,
"description": "Parking fee for {{serviceUserLicencePlate}} in area {{serviceUserAreaName}}, start from {{ServiceStartTime}} to {{ServiceEndTime}}",
"netUnitPrice": " {{servicePrice}}",
"serviceStart": "{{ServiceStartTime}}",
"specification": {
"areaCode": "0123",
"areaName": "{{serviceUserAreaName}}",
"operator": "Operator name",
"footNotes": "[2 3]",
"serviceUser": "{{serviceUserFirstname}} {{serviceUserLastname}}",
"licensePlate": "{{serviceUserLicencePlate}}",
"serviceUserPhone": "{{serviceUserPhoneNo}}"
},
"grossUnitPrice": "{{servicePriceGross}}",
"additionalInformation": "Parking under item"
}
],
"currency": "EUR",
"invoiceNumber": null,
"totalNetamount": "{{servicePrice}}",
"merchantImageUrl": "{{merchantURL}}",
"totalGrossAmount": "{{servicePriceGross}}",
"parentTransactionReference": null
},
"invoiceNumber": "Capture_{{TESTID}}_{{ORDER_NUMBER}}"
}
In case any parking session needs to be refunded or not included to the customer monthly invoice, client can use refund API. More details can be found here. Endpoint: /api/v3/orders/{orderNumber}/refunds
{
"orderItems": [
{
"imageUrl": "",
"quantity": 1,
"productId": "1",
"vatAmount": 1.6,
"productUrl": "",
"vatPercent": 19,
"description": "Parking Discount",
"netUnitPrice": 8.4,
"specification": {
"areaCode": "6731",
"areaName": "{{serviceUserAreaName}}",
"operator": "Operator name",
"footNotes": "[2 3]",
"serviceUser": "{{serviceUserFirstname}} {{serviceUserLastname}}",
"licensePlate": "{{serviceUserLicencePlate}}",
"serviceUserPhone": "{{serviceUserPhoneNo}}"
},
"grossUnitPrice": 10,
"additionalInformation": "Discount Code"
}
],
"captureNumber": "Capture_{{TESTID}}_{{ORDER_NUMBER}}",
"creditNoteNumber": "Credit_{{TESTID}}_{{ORDER_NUMBER}}"
}
Settlement and reporting with the client will happen after invoice consolidation. There are reconciliation and accounting reports Riverty provides. More information can be found here.
Idempotency is the ability of an API to respond to a repeated, identical call with an identical response every time. This increases system resiliency: if a message is lost in transmission for any reason, the API call can be repeated until a successful response arrives. It can also be used to confirm that the API received and processed the call correctly.
Without idempotency, the eCom API will treat every incoming call as a distinct transaction. For example, if a non-idempotent Authorize call is received multiple times, then the eCom API will return a business error because that Order Number has already been used by that merchant. Idempotency is enabled for all clients in the eCom API and does not require any additional client configuration. However, it only works if the merchant includes an Idempotency Key in the API call. Without it, the call is treated as non-idempotent.
Idempotency is an important feature that should be seriously investigated by Riverty’s partners. For more information on Idempotency, go to the following page.
For more detailed information on the various error codes, please visit the following page.
Please note that in addition to the error code and action code, the partner will also receive a field reference that can help understand which field caused the error. For example, ‘400.004’-error with the action code "AskConsumerToReEnterData" and field reference "customer.mobilePhone". This indicates that the customer has entered a mobile phone number in an incorrect format, and that the customer must enter the phone number in the correct format.
These are human-readable, descriptive messages returned by the API for common business errors. They usually occur due to missing mandatory customer information or information provided in an incorrect format.
Important:
Do you find this page helpful?