Skip to Main Content
Riverty Docs
    riverty logo Docs

    Return Notification

    Allows merchants to notify Riverty that the customer has triggered a return notification. Please note: the return notification does not automatically trigger a refund to the consumer. This must be seperately triggered by the Merchant once they have receive the returned item and inspected it for damage.

    Path

    POST /api/v3/orders/{orderNumber}/captures/return-notification

    Request Parameters

    orderNumber
    required
    string
    Order number

    Request Body

    application/json

    captureNumber
    required
    string
    Max length: 50
    Capture number for return. This is the capture number which comes from Capture response
    totalGrossAmount
    number
    Total gross amount of order. Must match the grossUnitPrice * quantity of order items
    array
    Order items to return. 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.
    parentTransactionReference
    string
    Max length: 128
    A unique reference provided to Riverty by a third party (merchant or Payment Service Provider). Identifies an entire order.
    transactionReference
    string
    Max length: 100
    A unique reference for each transaction (separate for transactions within an order), generated and provided to Riverty by a third party (merchant or Payment Service Provider). It is used to identify transactions during back-end settlement between Core systems and the PSP.

    Responses

    • 200 OK
    • type
      string
      Enum:
      • BusinessError
      • TechnicalError
      • NotificationMessage
      code
      string
      Max length: 100
      Confirmation or error code
      message
      string
      Max length: 4096
      Message content
      customerFacingMessage
      string
      Max length: 4096
      Message to display to customer
      actionCode
      string
      Enum:
      • Unavailable
      • AskConsumerToConfirm
      • AskConsumerToReEnterData
      • OfferSecurePaymentMethods
      • RequiresSsn
      • AskConsumerToIdentify
      • ManualReview
      Action codes
      fieldReference
      string
      Max length: 100
      Reference 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.
    Successful RequestUnsuccessful Request, Incorrect Capture Number

    Request Example

        
        {
 "captureNumber": "800090330"
}

    Response Example

        
        {}