1. Home
2. Payment methods
3. Alternative Payment Methods
4. Riverty

1. Introduction

This documentation informs you on the integration and use of the Riverty (Direct Debits and Open invoice) payment method.

Integration for new transactions must be done with e-Commerce. Maintenance on existing transactions is supported in the back office and via DirectLink and Batch.

If you perform refunds on iDEAL transactions with Direct Debits NL, you won't be able to use Direct Debits via Riverty (and vice versa).

2. Integration with Hosted Payment Page

You need to send some additional parameters with each order. This can only be done via a POST request.

2.1 Standard Worldline fields

The following parameters can or must be submitted for every transaction:

Field	Description	Format	Mandatory
AMOUNT	Total amount of the order (VAT included), multiplied by 100 (to avoid decimal issues), so 1.00 x 100 --> 100	N	Y
CURRENCY	Alpha ISO code of the currency (EUR, GBP, CHF, etc.)	AN, 3	Y
LANGUAGE	Client Localised Language (nl_NL, nl_BE, fr_FR, etc.) If not submitted, the default language used is English.	AN, 5	N
OPERATION	Defines the type of request, overriding the Default operation code	Values: RES / SAL	N
ORDERID	Your unique order reference	AN, 40	Y
PSPID	Your unique identifier on our system	AN, 30	Y

2.2 Invoicing and delivery data

The following parameters can or must be submitted with each order for Riverty:

Field	Description	Format	Mandatory
CIVILITY	Invoicing title (M/V)	AN, 10	Y
ECOM_BILLTO_POSTAL_NAME_FIRST	Invoicing first name	AN, 35	Y
ECOM_BILLTO_POSTAL_NAME_LAST	Invoicing last name	AN, 35	Y
OWNERADDRESS	Invoicing street name	AN, 35	Y
ECOM_BILLTO_POSTAL_STREET_NUMBER	Invoicing street number	AN, 10	Y
OWNERZIP	Invoicing ZIP/postcode	AN, 10	Y
OWNERTOWN	Invoicing city	AN, 25	Y
OWNERCTY	Invoicing country code (BE, FR, NL, DE etc.)	AN, 2	Y
EMAIL	Invoicing email address	AN, 50	Y
OWNERTELNO	Invoicing telephone number	AN, 30 (Riverty accepts max. 10)	Y
ECOM_SHIPTO_POSTAL_NAME_PREFIX	Delivery name prefix (Mr, Miss, etc.)	AN, 10	N
ECOM_SHIPTO_POSTAL_NAME_FIRST	Delivery first name	AN, 35	Y
ECOM_SHIPTO_POSTAL_NAME_LAST	Delivery last name	AN, 35	Y
ECOM_SHIPTO_POSTAL_STREET_LINE1	Delivery address	AN, 35	Y
ECOM_SHIPTO_POSTAL_STREET_NUMBER	Delivery street number	AN, 10	Y
ECOM_SHIPTO_POSTAL_POSTALCODE	Delivery ZIP/postcode	AN, 10	Y
ECOM_SHIPTO_POSTAL_CITY	Delivery city	AN, 25	Y
ECOM_SHIPTO_POSTAL_COUNTRYCODE	Delivery country code (BE, FR, NL, DE etc.)	AN, 2	Y
ECOM_SHIPTO_ONLINE_EMAIL	Delivery email address	AN, 50	N
ECOM_SHIPTO_DOB	Delivery customer's date of birth	dd/mm/yyyy	Y
DATEIN	Delivery date and time	mm/dd/yyyy hh:mm:ss	N
ORDERSHIPMETH	Delivery method	AN, 25	N
ORDERSHIPCOST	Delivery cost, excluding VAT Amount multiplied by 100	N, 10	N
ORDERSHIPTAX	Delivery tax amount Amount multiplied by 100	N	N
ORDERSHIPTAXCODE	Delivery tax code (e.g. 19%)	N, 10	N
Extra parameters for B2B
REF_CUSTOMERREF	Chamber of Commerce number (KVK)	AN, 20	Y
ECOM_SHIPTO_COMPANY	Delivery company	AN, 50	Y
ECOM_SHIPTO_TVA	VAT number	AN, 20	Y
REF_CUSTOMERID	Customer number	AN, 17	N
COSTCENTER	Company department	AN, 20	N

2.3 Order data

The following parameters can or must be submitted with each order for Riverty:

Field	Description	Format	Mandatory
ITEMIDx	Item identification (replace "x" with a number to send multiple items: ITEMID1, ITEMID2, etc.)	AN, 15	Y
ITEMNAMEx	Item name (replace "x" with a number to send multiple items: ITEMNAME1, ITEMNAME2, etc.)	AN, 40	Y
ITEMPRICEx	Item price (replace "x" with a number to send multiple items: ITEMPRICE1, ITEMPRICE2, etc.)	N, 15	Y
ITEMQUANTx	Item quantity (replace "x" with a number to send multiple items: ITEMQUANT1, ITEMQUANT2, etc.)	N, 15	Y
ITEMCATEGORYx	Item category (replace "x" with a number to send multiple items: ITEMCATEGORY1, ITEMCATEGORY2, etc.)	AN, 50	N
ITEMVATCODEx	Item VAT code (replace "x" with a number to send multiple items: ITEMVATCODE1, ITEMVATCODE2, etc.)	percentage	Y
TAXINCLUDEDX	If "1" is sent as the value for this parameter, the ITEMPRICEX is considered to include VAT, and our system will not calculate the VAT for the item. This feature is recommended as it avoids any issues when rounding off the order line totals. (replace X with a number to send multiple items: TAXINCLUDED1, TAXINCLUDED2, etc.)	N: 1	N

Note: The total amount should be multiplied by 100 in order to avoid any confusion over the decimal separator. However, this technique in NOT implemented at detail level, where the decimal separator should be included and should always be a full stop "." This allows the merchant to submit amounts with more than 2 decimals if he wishes.

Ascending order of line item details for SHA calculation Please take into account that as from 10 line item details the order of the parameters for the SHA calculation may differ from what is expected on your system's side. Where for the calculation of the SHA we normally stress that all parameters should be sorted alphabetically, a "logical" ascending order is put in place for the line item details: - Ascending order: 1, 2, 3, 4, 5, 6, 7, etc. - Alphabetical order: 1, 10, 11, 2, 3, 4, etc. (NOT applied)

2.4 Example

The following form simulates an Riverty transaction with all required fields.

Please ensure you replace the PSPID value with your own value, and calculate your SHA signature accordingly.

<form id="form1" method="POST" action="https://ogone.test.v-psp.com/ncol/test/orderstandard.asp"> <!-- standard Worldline fields --> <input type="text" name="ORDERID" value ="order123"/><br/> <input type="text" name="AMOUNT" value ="1309"/><br/> <input type="text" name="LANGUAGE" value="nl_NL"/><br/> <input type="text" name="PSPID" value="[yourpspid]"/><br/> <input type="text" name="CURRENCY" value="EUR"/><br/> <!-- Invoicing Information --> <input type="text" name="CIVILITY" value ="M"/><br/> <input type="text" name="ECOM_BILLTO_POSTAL_NAME_FIRST" value ="John"/><br/> <input type="text" name="ECOM_BILLTO_POSTAL_NAME_LAST" value ="Doe"/><br/><br/> <input type="text" name="OWNERADDRESS" value ="test street"/><br/> <input type="text" name="ECOM_BILLTO_POSTAL_STREET_NUMBER" value ="66"/><br/> <input type="text" name="OWNERZIP" value ="3000 AA"/><br/> <input type="text" name="OWNERTOWN" value ="Rotterdam"/><br/> <input type="text" name="OWNERCTY" value ="NL"/><br/> <input type="text" name="OWNERTELNO" value ="0302333459"/><br/> <input type="text" name="EMAIL" value ="john@doe.com"/><br/> <!-- Delivery Information --> <input type="text" name="ECOM_SHIPTO_DOB" value ="08/10/1940"/><br/> <input type="text" name="ECOM_SHIPTO_POSTAL_NAME_FIRST" value ="John"/><br/> <input type="text" name="ECOM_SHIPTO_POSTAL_NAME_LAST" value ="Doe"/><br/><br/> <input type="text" name="ECOM_SHIPTO_POSTAL_STREET_LINE1" value ="postal street"/><br/> <input type="text" name="ECOM_SHIPTO_POSTAL_STREET_NUMBER" value ="66"/><br/> <input type="text" name="ECOM_SHIPTO_POSTAL_POSTALCODE" value ="3000 AA"/><br/> <input type="text" name="ECOM_SHIPTO_POSTAL_CITY" value ="Rotterdam"/><br/> <input type="text" name="ECOM_SHIPTO_POSTAL_COUNTRYCODE" value ="NL"/><br/> <input type="text" name="ECOM_SHIPTO_ONLINE_EMAIL" value ="john@doe.com"/><br/> <!-- order details, item 1 --> <input type="text" name="ITEMID1" value ="1"/><br/> <input type="text" name="ITEMNAME1" value ="first item"/><br/> <input type="text" name="ITEMPRICE1" value ="12.10"/><br/> <input type="text" name="ITEMQUANT1" value ="1"/><br/> <input type="text" name="ITEMVATCODE1" value ="21%"/><br/> <input type="text" name="TAXINCLUDED1" value ="1"/><br/> <!-- order details, item 2 --> <input type="text" name="ITEMID2" value ="2"/><br/> <input type="text" name="ITEMNAME2" value ="Shipping costs"/><br/> <input type="text" name="ITEMPRICE2" value ="1.21"/><br/> <input type="text" name="ITEMQUANT2" value ="1"/><br/> <input type="text" name="ITEMVATCODE2" value ="21%"/><br/> <input type="text" name="TAXINCLUDED2" value ="1"/><br/> <!-- B2B parameters (if applicable) --> <input type="text" name="REF_CUSTOMERREF" value ="12345"/><br/> <input type="text" name="ECOM_SHIPTO_COMPANY" value ="MyCompany"/><br/> <input type="text" name="ECOM_SHIPTO_TVA" value ="123456789"/><br/> <input type="text" name="REF_CUSTOMERID" value ="0123456789"/><br/> <input type="text" name="COSTCENTER" value = "Finance"/><br/> <!-- don't forget your SHA-IN signature! --> SHASIGN<input type="text" name="SHASIGN" value="[your SHA-IN signature]"/><br/> <input type="submit" value="submit"/> </form>

3. Transaction feedback

3.1 Order details

All order details can be viewed in your Worldline account, via the Operations menu, using the "View transactions" link.

At the bottom of the order details, you see the items and VAT (in this example the shopping costs are included as an item):

3.2 Errors

In the event of an error, a specific error code (parameter NCERROR) will be returned. The merchant can optionally use this input to enhance his feedback on how the customer can correct or complete his input.

The following table contains a non-exhaustive list of possible errors:

Error code	Description
50001220	Invalid Customer Phone number
50001221	Invalid postal code format
50001222	Name / Last name missing
50001223	Name / Last name format invalid
50001224	Missing Customer Phone number
50001225	Name / Last name format invalid

4. Refunds

In order to perform refund operations, please ensure you have the "Refund" option available on your account. If in doubt, please contact our Sales team.

When you look at a transaction, click on the "Advanced" button at the bottom of the screen, which will reveal the refunding options.

If you click on "Refund", our system will show a detail screen in which you can specify the items to be refunded.

By default, the Quantity column contains the order quantities, which means that if you don't change the values, the whole order will be refunded (once you click "Submit").

In order to partially refund a transaction, adapt the quantities accordingly, or use the "Delete" button for each item in order to prevent certain items from being refunded.

Note that the "VAT incl." column indicates whether or not the respective amounts include VAT.

Click "Submit" to confirm the refund.

Important If you use the ORDERSHIPCOST field for shipping costs, you will not be able to refund these. Instead you should set the shipping costs as an order item, as in the above example. Then you will have the possibility to refund it as any other item of the order.

5. Maintenance

5.1 DirectLink

Maintenance operations (refunds and captures) can be performed via DirectLink.

Note: You must have the Worldline DirectLink option activated in your Worldline account in order to use this feature. Please contact our Sales team for more information about this product.

Please note that a maintenance using line item details (or ITEM parameters) must always be done using the POST method (hidden form), not the GET method (data in the URL).

5.1.1 Data

The following fields can or must be submitted with each maintenance operation request:

Field	Description	Format	Mandatory
AMOUNT	Total amount to be refunded, including VAT.	N	Y
CURRENCY	Transaction currency (EUR, CHF, USD, GBP, etc.)	AN, 3	Y
OPERATION	Operation to be performed. RFD = Partial refund RFS = (Last) Partial or Full refund For a full list of possible operations, please refer to the Parameter Cookbook in your Worldline account.	AN, 3	N
ORDERID	Your unique order reference (optional if PAYID is sent)	AN, 30	Y
PAYID	Our payment reference, which was sent to you after the initial transaction (optional if ORDERID is sent)	N	Y
PSPID	Your unique identifier on our system	AN, 30	Y
PSWD	The user's password	AN, 20	Y
USERID	User performing the maintenance. This is needed for security reasons. The user needs to have API privileges (cf. the User Manager documentation for more details)	AN, 20	Y

Field	Description	Format	Mandatory
ITEMIDX	Item identification (replace X with a number to send multiple items: ITEMID1, ITEMID2, etc.)	AN, 15	Y
ITEMNAMEX	Item name (replace X with a number to send multiple items: ITEMNAME1, ITEMNAME2, etc.)	AN, 30	Y
ITEMPRICEX	Item price (replace X with a number to send multiple items: ITEMPRICE1, ITEMPRICE2, etc.)Multiplied by 100 (unlike the original submission)	N	Y
ITEMQUANTX	Item quantity (replace X with a number to send multiple items: ITEMQUANT1, ITEMQUANT2, etc.)	N	Y
ITEMVATCODEX	Item VAT code (replace X with a number to send multiple items: ITEMVATCODE1, ITEMVATCODE2, etc.)	Percentage	Y
TAXINCLUDEDX	If this field equals 1, then the ITEMPRICEX is considered to include VAT, and our system will not calculate the VAT for the item. If this field is equal to 0 (or left blank, or not sent) our system will calculate the VAT for the item based on the ITEMVATCODEX This feature is intended to avoid any issues when rounding off the order line totals.(replace X with a number to send multiple items: TAXINCLUDED1, TAXINCLUDED2, etc.) (replace X with a number to send multiple items: TAXINCLUDED1, TAXINCLUDED2, etc.)	0 or 1	N

5.1.2 Example

<form action="https://ogone.test.v-psp.com/ncol/test/maintenancedirect.asp" method="post"> <input type="text" name="PSPID" value="[your pspid]"/><br/> <input type="text" name="USERID" value="[username]"/><br/> <input type="text" name="PSWD" value="[password]"/><br/> <input type="text" name="PAYID" value="[payid] "/><br/> <input type="text" name="ORDERID" value="[order id]"/><br/> <input type="text" name="AMOUNT" value="119"/><br/> <input type="text" name="OPERATION" value="RFD"/><br/> <input type="text" name="CURRENCY" value="EUR"/><br/> <input type="text" name="ITEMID1" value="1"/><br/> <input type="text" name="ITEMNAME1" value="first item"/><br/> <input type="text" name="ITEMPRICE1" value="119"/><br/> <input type="text" name="ITEMQUANT1" value="1"/><br/> <input type="text" name="ITEMVATCODE1" value="19%"/><br/> <input type="text" name="TAXINCLUDED1" value="1"/><br/> <input type="submit" name="submit" value="submit"/> </form>

Note: The SHA Signature is not required for maintenance operations.

A test page for DirectLink is available here: https://ogone.test.v-psp.com/ncol/test/testdm.asp?details=1

OHL;[your pspid];[your password];;[your username]; OHF;[file name];MTR;RFD;1; MTR;EUR;;;;;;;[PAYID];RFD;;;;[your pspid];;1;;;;;;;;;;;;;;;;;;119; DET;1;2;first item;119;1;19%;;;;;;;; OTF;

Partial maintenance: Please note that the given example applies in exactly the same way to partial/multiple maintenance operations. This means that also the line item details are mandatory in e.g. partial refund requests.

For more information, go to DirectLink.

5.2 Batch

Maintenance operations (refunds, captures) can be done via Batch.

Note: You must have the Worldline Batch option activated in his Worldline account in order to use this feature. Please contact our Sales team for more information about this product.

5.2.1 Data

The following information should be sent along with each batch file:

Login information: OHL

Position	Field	Format
1	Fixed value: 'OHL'. This indicates that the line contains login information	/
2	PSPID, the merchant's unique identifier on our platform	AN, 30
3	The API user's password	AN, 20
4	(leave empty)
5	The API username	AN, 20

File information: OHF

Position	Field	Format
1	Fixed value: 'OHF'. This indicates that the line contains file information	/
2	Name of the submitted file	AN, 50
3	Fixed value: 'MTR'. This indicates that a maintenance operation is being performed on an existing transaction	/
4	Operation Code: RFD = Partial refund RFS = (Last) Partial or Full refund	AN, 3
5	Number of Transactions affected by the current file	N

Transaction information: MTR

Position	Field	Format
1	Fixed value: 'MTR'. This indicates that the line contains transaction information	/
2	Currency	AN, 3
3-8	(leave empty)
9	PAYID, the unique reference generated and provided by our system in the initial transaction feedback	N
10	Operation Code: RFD = Partial refund RFS = (Last) Partial or Full refund	AN, 3
11-13	(leave empty)
14	PSPID, the merchant's unique identifier on our platform
15	(leave empty)
16	Number of detail lines for the current transaction	N
17-33	(leave empty)
34	Amount of the Operation, multiplied by 100	N

Line Details: DET

Position	Field	Format
1	Fixed value: 'DET'. This indicates that the line contains a detail line	/
2	Quantity	N
3	Item ID	AN, 15
4	Item name	AN, 30
5	Item unit price, Multiplied by 100 to avoid rounding off issues	N
6	Indicates whether the price is: 1 includes VAT or 0 excludes VAT	AN, 1
7	VAT rate, in the form of a percentage (including the % symbol) This is required, even if the amount includes VAT	N%
8-15	(leave empty)

End of File: OTF

Position	Field	Format
1	Fixed value: 'OTF'. This indicates that it is the last line of the file	/

5.2.2 Example

OHL;[your pspid];[your password];;[your username]; OHF;[file name];MTR;RFD;1; MTR;EUR;;;;;;;[PAYID];RFD;;;;[your pspid];;1;;;;;;;;;;;;;;;;;;119; DET;1;2;first item;119;1;19%;;;;;;;; OTF;

Partial maintenance: Please note that the given example applies in exactly the same way to partial/multiple maintenance operations. This means that also the line item details are mandatory in e.g. partial refund requests.

For more information, go to Batch.