Authorize Payment
Place the Order
Astrid places the items into her Cart, and goes to the Checkout page. She sees Riverty as an option, and selects it.
When she clicks the Buy button, the shop sends a POST call to the AUTHORIZE endpoint of the Riverty eCommerce API. This call contains Astrid’s name, email, national ID number, and postal address; and the details of the items she is buying. The API responds with a confirmation.
Now a reservation exists in Riverty’s accounts, in the merchant’s name, for the purchase price. Before responding, Riverty has used the provided details to run a risk/credit check, and is happy to accept this invoice.
The API request contains the following blocks:
Payment
This determines the payment method, out of those offered by Riverty. Any method besides Invoice requires additional information; please see the detailed payment object documentation for further information.
Customer
This contains the customer’s personally identifiable information, including their postal address.
Mandatory fields depend on the country. Click here to see which fields are required for each country.
Order
This contains the details of the purchase:
- Number – this is a unique identifier for the order. It is provided by the merchant, and can be human-readable. Can contain letters, numbers, dashes, and underscores. Not case-sensitive.
- TotalGrossAmount – the full payable amount of the order. Sum of grossUnitPrice * quantity for all Order Items.
- TotalNetAmount
- Currency
- Items
Order.Items
Details of the items being purchased
For each order item, the following information is provided:
- ProductID – the unique identifier of the item in the invoice. Provided by the merchant. Can be equivalent to the merchant’s own SKU.
- Description – the name of the item, as it appears on the invoice line.
- ImageURL – the product image. Optional.
- GrossUnitPrice – the price for one unit of this item, including VAT.
- netUnitPrice – the price for one unit of this item, excluding VAT.
- vatPercent – the VAT rate for this item as a number (e.g. 19% VAT - "vatPercent": 19)
- vatAmount – provided as a currency value, not a percentage.
- Quantity – the amount of units of this item included in the purchase.
- Type – optional parameter used to identify items like digital downloads, shipping fees, etc. These are handled differently from normal items during refunds and for accounting purposes.
See the detailed API documentation for more information.
Frequently asked questions
Working with different order/reference numbers?
Different reference numbers may be used in the e-commerce/payment industries. To learn about our specific requirements for order/reference numbers, please refer to our dedicated References Explanation page.
What happens if authorizations(reservations) won't be captured?
Riverty classifies accepted authorizations as either "Reservations" or "Non-captured Orders". Without a follow-up action such as a VOID or Capture, Riverty will automatically cancel the order/reserved amount after 30-45 days.
Do I need to send the shipping address details?
If the client/webshop provides the option for customers to send their package to a specific shipping address, it is required to send this information to Riverty. Failure to do so may result in liability or financial damage in cases of fraud and will be on the client/webshops plate.
Do I need to send the address details of the webshop's click-and-collect location?
If a client or webshop offers a click-and-collect option for customers to collect their packages from a physical store location, they are required to send the address information of that store to Riverty. Failure to do so may result in liability or financial damages in cases of fraud, which will be the responsibility of the client or webshop.
Do I need to provide pick-up point address details?
If the client/webshop provides the option for customers to send their package to a pick-up point, it is required to send the pick-up point address to Riverty. Failure to do so may result in liability or financial damage in cases of fraud.
Can a customer send a package to an address outside of their country of residence?
Riverty's current policy does not allow orders with a billing address from one country and a shipping address from another country. We only allow shipping addresses within the same country where the billing address is located.
Do I need to implement the specific 'House Number Addition'- Field?
Riverty provides a specific field for entering house number additions. Depending on the address format of each country, we kindly request that you consider providing the house number addition in this field.
Although the "House Number Addition" field is not mandatory according to our API documentation, many addresses in various countries can have a house number addition, such as "2nd floor," "Box 1," or "-C." If this specific field is missing in the checkout, customers may add the addition in the house number field.
We have a smart algorithm in place, but it is still possible that house number and house number addition cannot be processed correctly.
For instance, a Belgian address consists of:
- Street Name: TESTSTREET
- House Number: 15
- House Number Addition: 2nd floor
- Postal Code: 2000
- City Name: Brussels
- Country Name: Belgium
Are Mail order/Telephone order (MOTO) transactions possible?
Riverty can only accept mail order/telephone order (MOTO) transactions from clients/partners who have signed the contract or addendum for MOTO processing. This is also known as the Riverty Call Center Setup, which involves whitelisting the client's call center or customer department IP address.
Request
{
"payment": {
"type": "Invoice"
},
"customer": {
"identificationNumber": "800119-3989",
"salutation": "Mrs",
"firstName": "Astrid",
"lastName": "Svensson",
"email": "astrid.svensson@example.com",
"customerCategory": "Person",
"address": {
"street": "Kungsgatan",
"streetNumber": "66",
"postalCode": "11122",
"postalPlace": "Stockholm",
"countryCode": "SE"
}
},
"order": {
"number": "riverty1",
"totalGrossAmount": 180,
"totalNetAmount": 151.21,
"currency": "EUR",
"items": [
{
"productId": "4534-BLK-M",
"description": "Leather jacket, Black, size M",
"grossUnitPrice": 100,
"netUnitPrice": 84,
"quantity": 1,
"vatPercent": 19,
"vatAmount": 16,
"imageUrl": "https://developer-sandbox.riverty.com/images/black_leather_jacket.jpg"
},
{
"productId": "5745-GRY-M",
"description": "Socks, Grey, Size M",
"grossUnitPrice": 10,
"netUnitPrice": 8.4,
"quantity": 5,
"vatPercent": 19,
"vatAmount": 1.6,
"imageUrl": "https://developer-sandbox.riverty.com/images/grey_socks.jpg"
},
{
"productId": "3323-BRN-M",
"description": "Woolen hat, brown, Size M",
"grossUnitPrice": 30,
"netUnitPrice": 25.21,
"quantity": 1,
"vatPercent": 19,
"vatAmount": 4.79,
"imageUrl": "https://developer-sandbox.riverty.com/images/brown_wool_hat.jpg"
}
]
}
}
Response
{
"Outcome": "Accepted",
"Customer": {
"CustomerNumber": "809303697",
"FirstName": "Astrid",
"LastName": "Svensson",
"AddressList": [
{
"Street": "Kungsgatan",
"StreetNumber": "66",
"PostalCode": "11122",
"PostalPlace": "Stockholm",
"CountryCode": "SE"
}
]
},
"ReservationId": "9453e3d5-ac75-48d9-b2d2-e599b9cbe6c7",
"CheckoutId": "47dd743b-99fc-4ec3-a7d3-db802008ff96"
}