Authorize Payment

Why Authorize Payment is Important

The Authorize Payment call is a required called for all transactions, which transfers all consumer and order information to Riverty's system. The call triggers Riverty's Risk engine which when confirms the information provided is valid and that the constumer qualifies for the transaction. The authorization response informs whether the consumer and order are accepted by Riverty or not.

An Example

Astrid places the items into her Cart, and goes to the Checkout page and enters her name, email, national ID number, and address. She then selects Riverty 14 Day Invoice here desired payment method.

When she clicks the "Buy" button, the shop sends a POST call to the AUTHORIZE endpoint of the Riverty eCommerce API. This call contains the information Astrid entered above. The call passes all risk checks and responds "Accepted". Astrid is shown that the payment has been successful.

Now a reservation exists in Riverty’s accounts, in the merchant’s name, for the purchase price.

API Request 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.

Request

{
  "payment": {
    "type": "Invoice"
  },
  "customer": {
    "identificationNumber": "800119-3989",
    "salutation": "Mrs",
    "firstName": "Astrid",
    "lastName": "Svensson",
    "email": "astrid.svensson@example.com",
    "customerCategory": "Person",
    "address": {
      "street": "Gütersloher Straße",
      "streetNumber": "123",
      "postalCode": "33415",
      "postalPlace": "Verl",
      "countryCode": "DE"
    }
  },
  "order": {
    "number": "riverty1",
    "totalGrossAmount": 185,
    "totalNetAmount": 155.41,
    "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"
      },
      {
        "productId": "SHIP",
        "description": "Shipping",
        "type": "ShippingFee",
        "grossUnitPrice": 5,
        "netUnitPrice": 4.2,
        "quantity": 1,
        "vatPercent": 19,
        "vatAmount": 0.8
      }
    ]
  }
}

Response

{
  "Outcome": "Accepted",
  "Customer": {
    "CustomerNumber": "809303697",
    "FirstName": "Astrid",
    "LastName": "Svensson",
    "AddressList": [
      {
        "Street": "Gütersloher Straße",
        "StreetNumber": "123",
        "PostalCode": "33415",
        "PostalPlace": "Verl",
        "CountryCode": "DE"
      }
    ]
  },
  "ReservationId": "9453e3d5-ac75-48d9-b2d2-e599b9cbe6c7",
  "CheckoutId": "47dd743b-99fc-4ec3-a7d3-db802008ff96"
}

FAQ

What are the 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 an authorization is not 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 consumers 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 claims against the merchant in cases of fraud.

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 consumers 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 consumers 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, which will be the responsibility of the client or webshop.

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.