Hosted Checkout
More information can be found in our Documentation.
Path
POST /api/v3/hosted-checkout/request Request Body
application/json
webhookUrl
string
WebhookUrl used for callback when order has final state
array
Payment selection object used for request payment selection page
type
string
Enum:
- Invoice
- Installment
- Account
- Consolidatedinvoice
- PayinX
Payment method type
directDebit
string
Enum:
- Allowed
- NotAllowed
- Required
Payment method type
object
Authorize payment request. In case of One-Step Authorize, customer
and order objects must be filled in addition to payment info. In case of Two-Step Authorize,
only the checkoutId field must be filled.
merchantUrl
string
URL to redirect the customer to after the payment process
required
object
Payment information
type
required
string
Enum:
- Invoice
- Installment
- Account
- Consolidatedinvoice
- PayinX
Payment method type
object
Required for the payment method Fixed Installment payments in Germany and Austria and for the payment method Direct Debit in Germany, Austria and the Netherlands.
recurringAgreement
string
Enum:
- UseExisting
- CreateNew
bankAccount
required
string
Max length: 34
The bank account must be provided in the form of an IBAN (International Bank Account Number).
Ensure the IBAN is valid and correctly formatted.
token
string
Max length: 50
Unique string provided by Riverty if the merchant is using tokenization.
Contact your Key Account Manager for more details.
object
campaignNumber
required
integer
Campaign number
object
object
profileNo
required
integer
Account Profile number
object
Consolidated invoice information
invoiceDate
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Date when invoice will be created.
object
profileNo
required
integer
Installment profile number
numberOfInstallments
integer
Number of installments
customerInterestRate
number
Customer interest rate
object
Input data for authorize request with PayInX payment type. Currently empty
object
Enables redirecting the customer to Hosted Checkout and allows configuring Hosted Checkout settings.
array
Payment selection object used for request payment selection page
type
string
Enum:
- Invoice
- Installment
- Account
- Consolidatedinvoice
- PayinX
Payment method type
directDebit
string
Enum:
- Allowed
- NotAllowed
- Required
Payment method type
object
The person initiating the checkout, typically the buyer who places the order. May also receive the order.
identificationNumber
string
Max length: 20
National ID number (if the customer is a physical person). Registration number (if the customer is a company).
birthDate
required
string
yyyy-MM-dd
Date of birth. Not required if customerCategory is 'Company'.
object
Customer address
careOf
string
Max length: 50
Care of. Intermediary who is responsible for transferring a piece of mail between the postal system and the final addressee. For example Jane c/o John (“Jane at John's address”).
This field has to be used for company, authority and organization names as well - e. g. "Sportverein Blau-Weiß e.V.
street
string
Max length: 100
Name of street or packstation
streetNumber
string
Max length: 10
Street or packstation number
streetNumberAdditional
string
Max length: 10
Additional street number
postalCode
string
Max length: 10
Postal code
postalPlace
string
Max length: 100
Postal place
countryCode
string
Enum:
- NO
- SE
- FI
- DK
- DE
- AT
- CH
- NL
- BE
Country code
legalForm
string
Max length: 255
Type of business. This field is mandatory for processing B2B transactions in Austria, Germany and Switzerland.
object
existingCustomer
boolean
Is customer an existing customer for merchant
verifiedCustomerIdentification
boolean
This field signifies whether the customer's identification has been successfully verified.
marketingOptIn
boolean
Shows if merchant is allowed to send marketing information to customer
customerSince
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Since when customer has been merchant's client
customerClassification
string
Max length: 255
Customer reputation (e.g. VIP client)
acquisitionChannel
string
Enum:
- NotSet
- Advertisment
- SocialNetwork
- Direct
- SearchEngine
- Other
Customer acquisition channel
hasCustomerCard
boolean
Shows if customer has loyalty card
customerCardSince
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
The date when the loyalty card was issued to the customer
customerCardClassification
string
Max length: 100
Specifies the level of the loyalty card (e.g Gold member).
For DE, AT, CH, this must be an integer from 1 to 5, where 5 is the highest VIP level.
profileTrackingId
string
Max length: 50
Unique value for identifying a profile tracking session. We recommend to use a
uuid - e.g. 008b8215-3ef2-4a02-94e9-a121bf0e4c69. Please refrain from using
potentially URL-breaking characters (e.g. %,&,/)
ipAddress
string
Max length: 39
Customer’s IP address
numberOfTransactions
integer
Total number of successful purchases that have been made by the specific consumer
customerIndividualScore
string
The customer's individual risk score provided by the merchant.
Accepts a number from -10000 to 10000 (can be encased in quotation marks or not), or a single case-insensitive letter from 'a' to 'z'.
userAgent
string
Max length: 4096
UserAgent of this specific consumer
amountOfTransactions
number
Amount of paid orders last 12 months
otherPaymentMethods
boolean
Other payment method than MI in wallet
verifiedCustomerIdentificationType
string
Max length: 255
Specific method or category used to authenticate or verify a customer's identity
verifiedCustomerIdentificationDate
string
yyyy-MM-dd
Date on which a customer's identification details have been successfully confirmed or authenticated
dateformat: yyyy-MM-dd
customerNumber
string
Max length: 100
Customer number has to be unique, if no customer number available please leave empty
salutation
string
Enum:
- Mr
- Mrs
- Miss
Salutation
firstName
string
Max length: 50
First name. Everything over 50 characters will be truncated
lastName
string
Max length: 50
Last name. Everything over 50 characters will be truncated
companyName
string
Max length: 255
Purchasing company name. Everything over 255 characters will be truncated. This field is mandatory for processing B2B transactions in Austria, Belgium, Germany, the Netherlands and Switzerland.
email
string
Max length: 255
Email
phone
string
Max length: 16
Customer’s fixed-line phone number. The number will be normalised by us, removing non-numeric characters and converting it to international format.
The resulting number can contain up to 16 characters, including the country code.
mobilePhone
string
Max length: 16
Customer’s mobile phone number. The number will be normalised by us, removing non-numeric characters and converting it to international format.
The resulting number can contain up to 16 characters, including the country code.
customerCategory
required
string
Enum:
- Company
- Person
Customer category
conversationLanguage
string
Enum:
- NO
- SV
- FI
- DA
- EN
- DE
- NL
- FR
The language code used for client communication. If not provided, the system will default to the language configured for the client.
distributionType
string
Enum:
- Paper
- Sms
How information (invoices, notices, etc.) will be distributed to customer.
vatId
string
Max length: 50
VAT registration number, the unique number that identifies a business. This field is mandatory for processing B2B transactions in Austria, Germany and Switzerland.
object
The recipient of the order, potentially different from the buyer. Specifies the delivery address and contact details.
object
Customer address
addressType
string
Enum:
- Standard
- ShipTo
- PickUpPoint
- InStore
Delivery Address Type
object
PickUp point information
type
string
Enum:
- NotSet
- ParcelLocker
- ServicePoint
- NeighbourhoodPoint
- CarrierDepot
PickUp Point Type
name
string
Max length: 255
PickUp point name
careOf
string
Max length: 50
Care of. Intermediary who is responsible for transferring a piece of mail between the postal system and the final addressee. For example Jane c/o John (“Jane at John's address”).
This field has to be used for company, authority and organization names as well - e. g. "Sportverein Blau-Weiß e.V.
street
string
Max length: 100
Name of street or packstation
streetNumber
string
Max length: 10
Street or packstation number
streetNumberAdditional
string
Max length: 10
Additional street number
postalCode
string
Max length: 10
Postal code
postalPlace
string
Max length: 100
Postal place
countryCode
string
Enum:
- NO
- SE
- FI
- DK
- DE
- AT
- CH
- NL
- BE
Country code
salutation
string
Enum:
- Mr
- Mrs
- Miss
Salutation
firstName
string
Max length: 50
First name. Everything over 50 characters will be truncated
lastName
string
Max length: 50
Last name. Everything over 50 characters will be truncated
companyName
string
Max length: 255
Purchasing company name. Everything over 255 characters will be truncated. This field is mandatory for processing B2B transactions in Austria, Belgium, Germany, the Netherlands and Switzerland.
email
string
Max length: 255
Email
phone
string
Max length: 16
Customer’s fixed-line phone number. The number will be normalised by us, removing non-numeric characters and converting it to international format.
The resulting number can contain up to 16 characters, including the country code.
mobilePhone
string
Max length: 16
Customer’s mobile phone number. The number will be normalised by us, removing non-numeric characters and converting it to international format.
The resulting number can contain up to 16 characters, including the country code.
customerCategory
required
string
Enum:
- Company
- Person
Customer category
conversationLanguage
string
Enum:
- NO
- SV
- FI
- DA
- EN
- DE
- NL
- FR
The language code used for client communication. If not provided, the system will default to the language configured for the client.
distributionType
string
Enum:
- Paper
- Sms
How information (invoices, notices, etc.) will be distributed to customer.
vatId
string
Max length: 50
VAT registration number, the unique number that identifies a business. This field is mandatory for processing B2B transactions in Austria, Germany and Switzerland.
object
Order object
number
required
string
Max length: 50
Order number. Unique order number provided by the merchant. A valid order number can include alphanumeric characters, dashes and underscores.
totalNetAmount
required
number
Total net amount of order.
totalGrossAmount
required
number
Total gross amount of order. Must match the grossUnitPrice * quantity of order items
currency
string
Enum:
- EUR
- NOK
- SEK
- DKK
- CHF
Currency
object
channelType
string
Enum:
- Internet
- Catalog
- CallCenter
- Stationary
- Other
Order channel type
deliveryType
string
Enum:
- Normal
- Express
- InHouseDelivery
Indicates the type of delivery selected for the order. Possible values are "Normal" for standard delivery,
"Express" for expedited shipping, and "InHouseDelivery" when the merchant handles delivery using their own
logistics instead of an external carrier.
ticketDeliveryMethod
string
Enum:
- NotSet
- PickUp
- Post
- Phone
object
array
Passengers
id
integer
Continuous numbering.
firstName
string
Max length: 4096
First name.
lastName
string
Max length: 4096
Last name.
salutation
string
Enum:
- Mr
- Mrs
- Miss
Salutation
dateOfBirth
string
yyyy-MM-dd
Date birth of passenger.
array
Itineraries
operator
string
Max length: 4096
Name or Airport code (2-letter IATA) of the carrier
departure
string
Max length: 4096
Departure city or Airport Code (3-letter IATA)
arrival
string
Max length: 4096
Arrival city or Airport Code (3-letter IATA)
routeNumber
string
Max length: 4096
Number of this itinerary. Assumes String ordering.
dateOfTravel
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Departure date and time
price
number
Price
currency
string
Enum:
- EUR
- NOK
- SEK
- DKK
- CHF
Currency
object
company
string
Max length: 4096
Name of insurance company
type
string
Enum:
- NotSet
- Cancellation
- Travel
- CancellationTravel
- Bankruptcy
price
number
Price of insurance
currency
string
Enum:
- EUR
- NOK
- SEK
- DKK
- CHF
Currency
bookingReference
string
Max length: 4096
Booking reference
object
array
Passengers
id
integer
Continuous numbering.
firstName
string
Max length: 4096
First name.
lastName
string
Max length: 4096
Last name.
salutation
string
Enum:
- Mr
- Mrs
- Miss
Salutation
dateOfBirth
string
yyyy-MM-dd
Date birth of passenger.
array
Itineraries
operator
string
Max length: 4096
Name or Airport code (2-letter IATA) of the carrier
departure
string
Max length: 4096
Departure city or Airport Code (3-letter IATA)
arrival
string
Max length: 4096
Arrival city or Airport Code (3-letter IATA)
routeNumber
string
Max length: 4096
Number of this itinerary. Assumes String ordering.
dateOfTravel
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Departure date and time
price
number
Price
currency
string
Enum:
- EUR
- NOK
- SEK
- DKK
- CHF
Currency
object
company
string
Max length: 4096
Name of insurance company
type
string
Enum:
- NotSet
- Cancellation
- Travel
- CancellationTravel
- Bankruptcy
price
number
Price of insurance
currency
string
Enum:
- EUR
- NOK
- SEK
- DKK
- CHF
Currency
bookingReference
string
Max length: 4096
Booking reference
object
array
Passengers
id
integer
Continuous numbering.
firstName
string
Max length: 4096
First name.
lastName
string
Max length: 4096
Last name.
salutation
string
Enum:
- Mr
- Mrs
- Miss
Salutation
dateOfBirth
string
yyyy-MM-dd
Date birth of passenger.
array
Itineraries
operator
string
Max length: 4096
Name or Airport code (2-letter IATA) of the carrier
departure
string
Max length: 4096
Departure city or Airport Code (3-letter IATA)
arrival
string
Max length: 4096
Arrival city or Airport Code (3-letter IATA)
routeNumber
string
Max length: 4096
Number of this itinerary. Assumes String ordering.
dateOfTravel
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Departure date and time
price
number
Price
currency
string
Enum:
- EUR
- NOK
- SEK
- DKK
- CHF
Currency
object
company
string
Max length: 4096
Name of insurance company
type
string
Enum:
- NotSet
- Cancellation
- Travel
- CancellationTravel
- Bankruptcy
price
number
Price of insurance
currency
string
Enum:
- EUR
- NOK
- SEK
- DKK
- CHF
Currency
bookingReference
string
Max length: 4096
Booking reference
object
array
Passengers
id
integer
Continuous numbering.
firstName
string
Max length: 4096
First name.
lastName
string
Max length: 4096
Last name.
salutation
string
Enum:
- Mr
- Mrs
- Miss
Salutation
dateOfBirth
string
yyyy-MM-dd
Date birth of passenger.
array
Itineraries
operator
string
Max length: 4096
Name or Airport code (2-letter IATA) of the carrier
departure
string
Max length: 4096
Departure city or Airport Code (3-letter IATA)
arrival
string
Max length: 4096
Arrival city or Airport Code (3-letter IATA)
routeNumber
string
Max length: 4096
Number of this itinerary. Assumes String ordering.
dateOfTravel
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Departure date and time
price
number
Price
currency
string
Enum:
- EUR
- NOK
- SEK
- DKK
- CHF
Currency
object
company
string
Max length: 4096
Name of insurance company
type
string
Enum:
- NotSet
- Cancellation
- Travel
- CancellationTravel
- Bankruptcy
price
number
Price of insurance
currency
string
Enum:
- EUR
- NOK
- SEK
- DKK
- CHF
Currency
bookingReference
string
Max length: 4096
Booking reference
object
company
string
Max length: 4096
Name of rental company
object
Base class of Address fields
street
string
Max length: 100
Name of street or packstation
streetNumber
string
Max length: 10
Street or packstation number
streetNumberAdditional
string
Max length: 10
Additional street number
postalCode
string
Max length: 10
Postal code
postalPlace
string
Max length: 100
Postal place
countryCode
string
Enum:
- NO
- SE
- FI
- DK
- DE
- AT
- CH
- NL
- BE
Country code
object
Base class of Address fields
street
string
Max length: 100
Name of street or packstation
streetNumber
string
Max length: 10
Street or packstation number
streetNumberAdditional
string
Max length: 10
Additional street number
postalCode
string
Max length: 10
Postal code
postalPlace
string
Max length: 100
Postal place
countryCode
string
Enum:
- NO
- SE
- FI
- DK
- DE
- AT
- CH
- NL
- BE
Country code
startDate
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Pick up date and time
endDate
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
End date and time
array
Information about drivers who have rented a car
identificationNumber
string
Max length: 20
National ID number (if the customer is a physical person). Registration number (if the customer is a company).
birthDate
required
string
yyyy-MM-dd
Date of birth. Not required if customerCategory is 'Company'.
object
Customer address
careOf
string
Max length: 50
Care of. Intermediary who is responsible for transferring a piece of mail between the postal system and the final addressee. For example Jane c/o John (“Jane at John's address”).
This field has to be used for company, authority and organization names as well - e. g. "Sportverein Blau-Weiß e.V.
street
string
Max length: 100
Name of street or packstation
streetNumber
string
Max length: 10
Street or packstation number
streetNumberAdditional
string
Max length: 10
Additional street number
postalCode
string
Max length: 10
Postal code
postalPlace
string
Max length: 100
Postal place
countryCode
string
Enum:
- NO
- SE
- FI
- DK
- DE
- AT
- CH
- NL
- BE
Country code
legalForm
string
Max length: 255
Type of business. This field is mandatory for processing B2B transactions in Austria, Germany and Switzerland.
object
existingCustomer
boolean
Is customer an existing customer for merchant
verifiedCustomerIdentification
boolean
This field signifies whether the customer's identification has been successfully verified.
marketingOptIn
boolean
Shows if merchant is allowed to send marketing information to customer
customerSince
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Since when customer has been merchant's client
customerClassification
string
Max length: 255
Customer reputation (e.g. VIP client)
acquisitionChannel
string
Enum:
- NotSet
- Advertisment
- SocialNetwork
- Direct
- SearchEngine
- Other
Customer acquisition channel
hasCustomerCard
boolean
Shows if customer has loyalty card
customerCardSince
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
The date when the loyalty card was issued to the customer
customerCardClassification
string
Max length: 100
Specifies the level of the loyalty card (e.g Gold member).
For DE, AT, CH, this must be an integer from 1 to 5, where 5 is the highest VIP level.
profileTrackingId
string
Max length: 50
Unique value for identifying a profile tracking session. We recommend to use a
uuid - e.g. 008b8215-3ef2-4a02-94e9-a121bf0e4c69. Please refrain from using
potentially URL-breaking characters (e.g. %,&,/)
ipAddress
string
Max length: 39
Customer’s IP address
numberOfTransactions
integer
Total number of successful purchases that have been made by the specific consumer
customerIndividualScore
string
The customer's individual risk score provided by the merchant.
Accepts a number from -10000 to 10000 (can be encased in quotation marks or not), or a single case-insensitive letter from 'a' to 'z'.
userAgent
string
Max length: 4096
UserAgent of this specific consumer
amountOfTransactions
number
Amount of paid orders last 12 months
otherPaymentMethods
boolean
Other payment method than MI in wallet
verifiedCustomerIdentificationType
string
Max length: 255
Specific method or category used to authenticate or verify a customer's identity
verifiedCustomerIdentificationDate
string
yyyy-MM-dd
Date on which a customer's identification details have been successfully confirmed or authenticated
dateformat: yyyy-MM-dd
customerNumber
string
Max length: 100
Customer number has to be unique, if no customer number available please leave empty
salutation
string
Enum:
- Mr
- Mrs
- Miss
Salutation
firstName
string
Max length: 50
First name. Everything over 50 characters will be truncated
lastName
string
Max length: 50
Last name. Everything over 50 characters will be truncated
companyName
string
Max length: 255
Purchasing company name. Everything over 255 characters will be truncated. This field is mandatory for processing B2B transactions in Austria, Belgium, Germany, the Netherlands and Switzerland.
email
string
Max length: 255
Email
phone
string
Max length: 16
Customer’s fixed-line phone number. The number will be normalised by us, removing non-numeric characters and converting it to international format.
The resulting number can contain up to 16 characters, including the country code.
mobilePhone
string
Max length: 16
Customer’s mobile phone number. The number will be normalised by us, removing non-numeric characters and converting it to international format.
The resulting number can contain up to 16 characters, including the country code.
customerCategory
required
string
Enum:
- Company
- Person
Customer category
conversationLanguage
string
Enum:
- NO
- SV
- FI
- DA
- EN
- DE
- NL
- FR
The language code used for client communication. If not provided, the system will default to the language configured for the client.
distributionType
string
Enum:
- Paper
- Sms
How information (invoices, notices, etc.) will be distributed to customer.
vatId
string
Max length: 50
VAT registration number, the unique number that identifies a business. This field is mandatory for processing B2B transactions in Austria, Germany and Switzerland.
price
number
Price of a rental car
currency
string
Enum:
- EUR
- NOK
- SEK
- DKK
- CHF
Currency
bookingReference
string
Max length: 4096
Booking reference
object
company
string
Max length: 4096
object
Base class of Address fields
street
string
Max length: 100
Name of street or packstation
streetNumber
string
Max length: 10
Street or packstation number
streetNumberAdditional
string
Max length: 10
Additional street number
postalCode
string
Max length: 10
Postal code
postalPlace
string
Max length: 100
Postal place
countryCode
string
Enum:
- NO
- SE
- FI
- DK
- DE
- AT
- CH
- NL
- BE
Country code
checkin
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Check-in date and time
checkout
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Check-out date and time
array
Guests information
identificationNumber
string
Max length: 20
National ID number (if the customer is a physical person). Registration number (if the customer is a company).
birthDate
required
string
yyyy-MM-dd
Date of birth. Not required if customerCategory is 'Company'.
object
Customer address
careOf
string
Max length: 50
Care of. Intermediary who is responsible for transferring a piece of mail between the postal system and the final addressee. For example Jane c/o John (“Jane at John's address”).
This field has to be used for company, authority and organization names as well - e. g. "Sportverein Blau-Weiß e.V.
street
string
Max length: 100
Name of street or packstation
streetNumber
string
Max length: 10
Street or packstation number
streetNumberAdditional
string
Max length: 10
Additional street number
postalCode
string
Max length: 10
Postal code
postalPlace
string
Max length: 100
Postal place
countryCode
string
Enum:
- NO
- SE
- FI
- DK
- DE
- AT
- CH
- NL
- BE
Country code
legalForm
string
Max length: 255
Type of business. This field is mandatory for processing B2B transactions in Austria, Germany and Switzerland.
object
existingCustomer
boolean
Is customer an existing customer for merchant
verifiedCustomerIdentification
boolean
This field signifies whether the customer's identification has been successfully verified.
marketingOptIn
boolean
Shows if merchant is allowed to send marketing information to customer
customerSince
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Since when customer has been merchant's client
customerClassification
string
Max length: 255
Customer reputation (e.g. VIP client)
acquisitionChannel
string
Enum:
- NotSet
- Advertisment
- SocialNetwork
- Direct
- SearchEngine
- Other
Customer acquisition channel
hasCustomerCard
boolean
Shows if customer has loyalty card
customerCardSince
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
The date when the loyalty card was issued to the customer
customerCardClassification
string
Max length: 100
Specifies the level of the loyalty card (e.g Gold member).
For DE, AT, CH, this must be an integer from 1 to 5, where 5 is the highest VIP level.
profileTrackingId
string
Max length: 50
Unique value for identifying a profile tracking session. We recommend to use a
uuid - e.g. 008b8215-3ef2-4a02-94e9-a121bf0e4c69. Please refrain from using
potentially URL-breaking characters (e.g. %,&,/)
ipAddress
string
Max length: 39
Customer’s IP address
numberOfTransactions
integer
Total number of successful purchases that have been made by the specific consumer
customerIndividualScore
string
The customer's individual risk score provided by the merchant.
Accepts a number from -10000 to 10000 (can be encased in quotation marks or not), or a single case-insensitive letter from 'a' to 'z'.
userAgent
string
Max length: 4096
UserAgent of this specific consumer
amountOfTransactions
number
Amount of paid orders last 12 months
otherPaymentMethods
boolean
Other payment method than MI in wallet
verifiedCustomerIdentificationType
string
Max length: 255
Specific method or category used to authenticate or verify a customer's identity
verifiedCustomerIdentificationDate
string
yyyy-MM-dd
Date on which a customer's identification details have been successfully confirmed or authenticated
dateformat: yyyy-MM-dd
customerNumber
string
Max length: 100
Customer number has to be unique, if no customer number available please leave empty
salutation
string
Enum:
- Mr
- Mrs
- Miss
Salutation
firstName
string
Max length: 50
First name. Everything over 50 characters will be truncated
lastName
string
Max length: 50
Last name. Everything over 50 characters will be truncated
companyName
string
Max length: 255
Purchasing company name. Everything over 255 characters will be truncated. This field is mandatory for processing B2B transactions in Austria, Belgium, Germany, the Netherlands and Switzerland.
email
string
Max length: 255
Email
phone
string
Max length: 16
Customer’s fixed-line phone number. The number will be normalised by us, removing non-numeric characters and converting it to international format.
The resulting number can contain up to 16 characters, including the country code.
mobilePhone
string
Max length: 16
Customer’s mobile phone number. The number will be normalised by us, removing non-numeric characters and converting it to international format.
The resulting number can contain up to 16 characters, including the country code.
customerCategory
required
string
Enum:
- Company
- Person
Customer category
conversationLanguage
string
Enum:
- NO
- SV
- FI
- DA
- EN
- DE
- NL
- FR
The language code used for client communication. If not provided, the system will default to the language configured for the client.
distributionType
string
Enum:
- Paper
- Sms
How information (invoices, notices, etc.) will be distributed to customer.
vatId
string
Max length: 50
VAT registration number, the unique number that identifies a business. This field is mandatory for processing B2B transactions in Austria, Germany and Switzerland.
numberOfRooms
integer
Number of rooms
price
number
Price of the hotel accommodation
currency
string
Enum:
- EUR
- NOK
- SEK
- DKK
- CHF
Currency
bookingReference
string
Max length: 4096
Booking reference
merchantImageUrl
string
Max length: 2048
Image URL for the merchants brand. This image is shown at the top of the order page in Riverty. Supported image formats are: gif, jpeg (jpg), png, webp.
array
Array of order items. Maximum allowed 500 items.
productId
required
string
Max length: 100
Merchant Product identification number.
groupId
string
Max length: 255
Item group ID. The group this item belongs to. Provided by the merchant. Everything over 255 characters will be truncated.
description
required
string
Product name. For example "Black music player 64GB". Everything over 255 characters will be truncated.
type
string
Enum:
- PhysicalArticle
- DigitalArticle
- GiftCard
- Discount
- ShippingFee
- Surcharge
- Info
- Subscription
netUnitPrice
required
number
Net unit price.
grossUnitPrice
required
number
Gross price per item.
quantity
required
number
Quantity. Use of integer is strongly proposed. If you want to use decimal, please contact your integration manager.
unitCode
string
Max length: 50
Unit code (for example pieces, liters, kilograms, etc.).
vatCategory
string
Enum:
- HighCategory
- LowCategory
- NullCategory
- NoCategory
- MiddleCategory
- OtherCategory
Vat category
vatPercent
required
number
Tax percent.
vatAmount
required
number
Tax amount per item.
imageUrl
string
Max length: 2048
URL for the image of this product. It will be turned into a thumbnail and displayed in Riverty, on the invoice line next to the order item.
The linked image must be a rectangle or square, width between 100 pixels and 1280 pixels.
Supported image formats are: gif, jpeg (jpg), png, webp.
googleProductCategoryId
integer
Google product category ID.
googleProductCategory
string
Max length: 255
Indicates the category of the item based on the Google product taxonomy. Categorizing the product helps ensure that the ad is shown with the right search results.
merchantProductType
string
Max length: 255
Categorization used by Merchant as a complement to Google Taxonomy.
lineNumber
integer
Line number. The merchant may add a line number to each order item, to sort them in a particular order.
productUrl
string
Max length: 2048
URL to the product.
marketPlaceSellerId
string
Max length: 32
ID of an individual seller on a marketplace. If this field is used, an entry in the element additionalData -> marketplace must also be provided.
parentTransactionReference
string
Max length: 128
A unique reference provided to Riverty by a third party (merchant or Payment Service Provider). Identifies an entire order.
additionalInformation
string
Max length: 4096
Extended description of the order item.
specification
object
Specification.
serviceStart
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Capture start time.
serviceEnd
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Capture end time.
productUser
string
Max length: 50
Product User
costCenter
string
Max length: 50
Used for B2B to specify the costCenter e.g. Marketing or Sales Department - Displayed on the invoice.
parentTransactionReference
string
Max length: 128
A unique reference provided to Riverty by a third party (merchant or Payment Service Provider). Identifies an entire order.
object
Additional data
pluginProvider
string
Max length: 50
Plugin Provider Name
pluginVersion
string
Max length: 50
Plugin Version
shopUrl
string
Max length: 2048
URL of the Webshop
shopPlatform
string
Max length: 50
Name of the platform used for the Webshop
shopPlatformVersion
string
Max length: 50
Version of the webshop platform
array
Additional information for marketplace set-ups. If the marketPlaceSellerId field is used in the order items, then this element must include the corresponding marketplace data.
id
string
Max length: 32
ID of the marketplace seller. Required for marketplace set-ups.
merchantCategoryCode
string
Max length: 4
A four-digit merchant categoryCode number of the marketplace seller. Required for marketplace set-ups.
name
string
Max length: 50
Name of the marketplace seller. Required for marketplace set-ups.
registeredSince
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Registration date of the marketplace seller
rating
string
Max length: 20
Rating of the marketplace seller
transactions
integer
Number of transaction processed by the marketplace seller
object
Subscription information
name
string
Max length: 50
Name / Description of the subscription
start
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Startdate of the subscription
end
string
yyyy-MM-ddTHH:mm:ss.fffffffzzz
Enddate of the subscription
type
string
Enum:
- FixedPeriod
- AutoRenewal
Subscription type
object
pspName
string
Max length: 50
Name of the PSP
pspType
string
Enum:
- Collecting
- Distributing
- SuperMerchant
- MLevel
Type of the PSP
trackingProvider
string
Max length: 50
If device fingerprinting is applied, please specify the name of the provider
trackingSessionId
string
Max length: 50
Session id of tracking script
trackingScore
string
Max length: 20
Score provided by tracking provider
challengedScore
string
Max length: 20
Score provided by partner if transaction is challenged
additionalPaymentInfo
string
Max length: 250
Additional technical payment information, not used for customer communication
object
inStore object
storeId
string
Max length: 16
Number of Store
object
Base class of Address fields
street
string
Max length: 100
Name of street or packstation
streetNumber
string
Max length: 10
Street or packstation number
streetNumberAdditional
string
Max length: 10
Additional street number
postalCode
string
Max length: 10
Postal code
postalPlace
string
Max length: 100
Postal place
countryCode
string
Enum:
- NO
- SE
- FI
- DK
- DE
- AT
- CH
- NL
- BE
Country code
clerkId
string
Max length: 16
ClerkId
additionalMerchantData
string
Max length: 4096
Additional information about the merchant
Format: Base64 encoded JSON
yourReference
string
Max length: 20
Can be used by purchasing company if they would like to provide internal reference
ourReference
string
Max length: 128
Can be used by selling company if they would like to provide specific reference for purchasing company.
This field is limited to 128 characters, longer values will be truncated to fit within the specified limit.
object
e-invoice references information
reference
string
The customer's e-invoice reference
referenceType
string
Enum:
- GLN
- OrgNo
- PEPPOL
party
string
Max length: 50
Reference to the invoice party that should be used. For Finland the max length is 35 chars.
nonce
string
Unique string provided by Riverty if the merchant is using Hosted Fields. Contact your Key Account Manager for more details.
object
object
These fields can be used to include implementation-specific reference information when other reference fields are not applicable.
Usage of these fields needs to be aligned during implementation.
udf1
string
udf2
string
udf3
string
udf4
string
udf5
string
Responses
-
redirectUrlstringPayment url from hosted checkoutorderKeystringOrder key from hosted checkout
-
typestringEnum:
- BusinessError
- TechnicalError
- NotificationMessage
codestringMax length: 100Confirmation or error codemessagestringMax length: 4096Message contentcustomerFacingMessagestringMax length: 4096Message to display to customeractionCodestringEnum:- Unavailable
- AskConsumerToConfirm
- AskConsumerToReEnterData
- OfferSecurePaymentMethods
- RequiresSsn
- AskConsumerToIdentify
- ManualReview
Action codesfieldReferencestringMax length: 100Reference to field that caused an error -
401 Authorization has been denied for this request.
-
413 Request body too large.
-
429 Too many requests.
-
500 Internal server error.
Request Example
{
"merchantUrl": "https://example.com",
"authorizeRequest": {
"order": {
"items": [
{
"groupId": "0011",
"quantity": 5,
"productId": "0001",
"vatAmount": 2,
"vatPercent": 20,
"description": "item 1 description",
"netUnitPrice": 10,
"grossUnitPrice": 12
},
{
"groupId": "0022",
"quantity": 2,
"productId": "0002",
"vatAmount": 20,
"vatPercent": 20,
"description": "item 2 description",
"netUnitPrice": 100,
"grossUnitPrice": 120
}
],
"number": "RIVERTY01",
"totalNetAmount": 250,
"totalGrossAmount": 300
},
"payment": {
"type": "Invoice"
},
"customer": {
"email": "astrid.svensson@example.com",
"address": {
"street": "Gütersloher Straße",
"postalCode": "33415",
"countryCode": "DE",
"postalPlace": "Berlin",
"streetNumber": "123"
},
"lastName": "Svensson",
"firstName": "Astrid",
"customerCategory": "Person",
"conversationLanguage": "DE"
}
}
}
Response Example
{
"redirectUrl": "https://hosted-checkout.bnpl.riverty.io/pay/nl/098?token=123"
}
Request Example
{
"merchantUrl": "https://example.com",
"authorizeRequest": {
"order": {
"items": [
{
"groupId": "0011",
"quantity": 5,
"productId": "0001",
"vatAmount": 2,
"vatPercent": 20,
"description": "item 1 description",
"netUnitPrice": 10,
"grossUnitPrice": 12
},
{
"groupId": "0022",
"quantity": 2,
"productId": "0002",
"vatAmount": 20,
"vatPercent": 20,
"description": "item 2 description",
"netUnitPrice": 100,
"grossUnitPrice": 120
}
],
"number": "RIVERTY01",
"totalNetAmount": 250,
"totalGrossAmount": 300
},
"payment": {
"type": "Consolidatedinvoice"
},
"customer": {
"email": "astrid.svensson@example.com",
"address": {
"street": "Gütersloher Straße",
"postalCode": "33415",
"countryCode": "DE",
"postalPlace": "Berlin",
"streetNumber": "123"
},
"lastName": "Svensson",
"firstName": "Astrid",
"customerCategory": "Person",
"conversationLanguage": "DE"
}
}
}
Response Example
{
"redirectUrl": "https://hosted-checkout.bnpl.riverty.io/pay/nl/098?token=123"
}
Request Example
{
"merchantUrl": "https://example.com",
"authorizeRequest": {
"order": {
"items": [
{
"groupId": "0011",
"quantity": 5,
"productId": "0001",
"vatAmount": 2,
"vatPercent": 20,
"description": "item 1 description",
"netUnitPrice": 10,
"grossUnitPrice": 12
},
{
"groupId": "0022",
"quantity": 2,
"productId": "0002",
"vatAmount": 20,
"vatPercent": 20,
"description": "item 2 description",
"netUnitPrice": 100,
"grossUnitPrice": 120
}
],
"number": "RIVERTY01",
"totalNetAmount": 250,
"totalGrossAmount": 300
},
"payment": {
"type": "Invoice",
"directDebit": {
"available": true
}
},
"customer": {
"email": "astrid.svensson@example.com",
"address": {
"street": "Gütersloher Straße",
"postalCode": "33415",
"countryCode": "DE",
"postalPlace": "Berlin",
"streetNumber": "123"
},
"lastName": "Svensson",
"firstName": "Astrid",
"customerCategory": "Person",
"conversationLanguage": "DE"
}
}
}
Response Example
{
"redirectUrl": "https://hosted-checkout.bnpl.riverty.io/pay/nl/098?token=123"
}
Request Example
{
"merchantUrl": "https://example.com",
"authorizeRequest": {
"order": {
"items": [
{
"groupId": "0011",
"quantity": 5,
"productId": "0001",
"vatAmount": 2,
"vatPercent": 20,
"description": "item 1 description",
"netUnitPrice": 10,
"grossUnitPrice": 12
},
{
"groupId": "0022",
"quantity": 2,
"productId": "0002",
"vatAmount": 20,
"vatPercent": 20,
"description": "item 2 description",
"netUnitPrice": 100,
"grossUnitPrice": 120
}
],
"number": "RIVERTY01",
"totalNetAmount": 250,
"totalGrossAmount": 300
},
"payment": {
"type": "PayinX"
},
"customer": {
"email": "astrid.svensson@example.com",
"address": {
"street": "Gütersloher Straße",
"postalCode": "33415",
"countryCode": "DE",
"postalPlace": "Berlin",
"streetNumber": "123"
},
"lastName": "Svensson",
"firstName": "Astrid",
"customerCategory": "Person",
"conversationLanguage": "DE"
}
}
}
Response Example
{
"redirectUrl": "https://hosted-checkout.bnpl.riverty.io/pay/nl/098?token=123"
}
Request Example
{
"merchantUrl": "https://example.com",
"authorizeRequest": {
"order": {
"items": [
{
"groupId": "0011",
"quantity": 5,
"productId": "0001",
"vatAmount": 2,
"vatPercent": 20,
"description": "item 1 description",
"netUnitPrice": 10,
"grossUnitPrice": 12
},
{
"groupId": "0022",
"quantity": 2,
"productId": "0002",
"vatAmount": 20,
"vatPercent": 20,
"description": "item 2 description",
"netUnitPrice": 100,
"grossUnitPrice": 120
}
],
"number": "RIVERTY01",
"totalNetAmount": 250,
"totalGrossAmount": 300
},
"payment": {
"type": "Installment"
},
"customer": {
"email": "astrid.svensson@example.com",
"address": {
"street": "Gütersloher Straße",
"postalCode": "33415",
"countryCode": "DE",
"postalPlace": "Berlin",
"streetNumber": "123"
},
"lastName": "Svensson",
"firstName": "Astrid",
"customerCategory": "Person",
"conversationLanguage": "DE"
}
}
}
Response Example
{
"redirectUrl": "https://hosted-checkout.bnpl.riverty.io/pay/nl/098?token=123"
}
Request Example
{
"merchantUrl": "https://example.com",
"authorizeRequest": {
"order": {
"items": [
{
"groupId": "0011",
"quantity": 5,
"productId": "0001",
"vatAmount": 2,
"vatPercent": 20,
"description": "item 1 description",
"netUnitPrice": 10,
"grossUnitPrice": 12
},
{
"groupId": "0022",
"quantity": 2,
"productId": "0002",
"vatAmount": 20,
"vatPercent": 20,
"description": "item 2 description",
"netUnitPrice": 100,
"grossUnitPrice": 120
}
],
"number": "",
"totalNetAmount": 250,
"totalGrossAmount": 300
},
"payment": {
"type": "Invoice"
},
"customer": {
"email": "astrid.svensson@example.com",
"address": {
"street": "Gütersloher Straße",
"postalCode": "33415",
"countryCode": "DE",
"postalPlace": "Berlin",
"streetNumber": "123"
},
"lastName": "Svensson",
"firstName": "Astrid",
"customerCategory": "Person",
"conversationLanguage": "DE"
}
}
}
Response Example
[
{
"code": "400.002",
"type": "BusinessError",
"message": "Value is required.",
"actionCode": "Unavailable",
"fieldReference": "order.number",
"customerFacingMessage": "Value is required."
}
]