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 Pagina di pagamento ospitata
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.) |
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 |
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 |
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. |
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 nostro team di vendita. |
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 nostro team di vendita 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.
|
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 |
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 nostro team di vendita 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:
|
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:
|
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.
Domande frequenti
- L’affiliazione richiede all'acquirente o alla banca una settimana circa. Ovviamente, se l'affiliazione è già attiva, l'attivazione richiede solo qualche giorno.
- Alcuni metodi di pagamento richiedono controlli aggiuntivi prima di poter essere attivati, ad esempio in caso di 3-D Secure, richiesto direttamente a VISA o MasterCard (e non all'acquirente)
Un acquirente è un'istituzione finanziaria che elabora i pagamenti effettuati con determinate carte di credito e debito. L'acquirente è responsabile della parte finanziaria dell'elaborazione della transazione, mentre Worldline è responsabile di quella tecnica. In altre parole, senza acquirente il denaro non viene trasferito al conto bancario.
Per ogni metodo di pagamento che si desidera aggiungere, occorre un contratto di accettazione con un acquirente. Per chiedere informazioni sugli acquirenti più adatti per la propria attività e la propria zona, ci contatti per favore. Se si conoscono gli acquirenti con cui si desidera lavorare, basta semplicemente selezionarli dall'elenco a discesa quando si aggiunge un metodo di pagamento all'account.
Possiamo occuparcene noi? Full Service consente di attivare molti metodi di pagamento locali contemporaneamente e in diversi paesi, con un solo contratto. Se si eseguono transazioni internazionali, può essere il modo ideale per accettare pagamenti da tutta Europa. Consente di evitare lunghe pratiche amministrative e di aumentare anche i ricavi, grazie all'offerta di più metodi di pagamento.
Scopri di più su Ingenico Full Service qui e contattandoci.