Refund Payment | Riverty Docs

Path

POST /api/v3/orders/{orderNumber}/refunds

Request Parameters

orderNumber

required

string

Order number

Request Body

application/json

captureNumber

required

string

> 50 Characters

Capture number to refund. This is the capture number which comes from Capture response. Required for Partial Refund

required

array

Order items to refund. Required for Partial Refund. Maximum allowed 200 items.

refundType

string

Enum:

Refund

Return

productId

required

string

> 100 Characters

Merchant Product identification number.

groupId

string

> 50 Characters

Item group ID. The group this item belongs to. Provided by the merchant. Everything over 50 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

> 50 Characters

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

> 2048 Characters

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

> 255 Characters

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

> 255 Characters

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

> 2048 Characters

URL to the product.

marketPlaceSellerId

string

> 32 Characters

ID of an individual seller on a marketplace.

parentTransactionReference

string

> 128 Characters

A unique reference provided to Riverty by a third party (merchant or Payment Service Provider). Identifies an entire order.

additionalInformation

string

> 4096 Characters

Extended description of the order item.

specification

N/A

Specification.

serviceStart

string

Capture start time.

serviceEnd

string

Capture end time.

refundType

string

Enum:

Refund

Return

parentTransactionReference

string

> 128 Characters

A unique reference provided to Riverty by a third party (merchant or Payment Service Provider). Identifies an entire order.

transactionReference

string

> 100 Characters

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.

creditNoteNumber

string

> 19 Characters

Credit note number. The merchant may want to use internal credit note numbers, or let the Riverty generate one based on invoice to be credited.

merchantId

string

> 50 Characters

Merchant ID within the Riverty system, part of the credentials used for Riverty Netherlands and Belgium. If you were not provided these credentials by your Account Manager, leave empty.

Responses

Successful Request, Full Refund

Successful Request, Partial Refund

Successful request, Refund with return costs

Unsuccessful Request, Refund Amount Exceeds Capture Amount

Response Example

    
        {
 "totalCapturedAmount": 185,
 "totalAuthorizedAmount": 185,
 "refundNumbers": [
  "800090092"
 ],
 "totalRefundedAmount": 185,
 "remainingAuthorizedAmount": 0
}

Request Example

    
        null

Response Example

    
        {
 "totalCapturedAmount": 185,
 "totalAuthorizedAmount": 185,
 "refundNumbers": [
  "800090092"
 ],
 "totalRefundedAmount": 30,
 "remainingAuthorizedAmount": 150
}

Request Example

    
        {
 "captureNumber": "800001157",
 "orderItems": [
  {
   "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 Example

    
        {
 "totalCapturedAmount": 30,
 "totalAuthorizedAmount": 30,
 "refundNumbers": [
  "802129053"
 ],
 "totalRefundedAmount": 27,
 "remainingAuthorizedAmount": 0
}

Request Example

    
        {
 "captureNumber": "800001157",
 "items": [
  {
   "productId": "3323-BRN-M",
   "description": "Woolen hat, browm, Size M",
   "quantity": 1,
   "grossUnitPrice": 30,
   "netUnitPrice": 24.79,
   "vatAmount": 5.21,
   "vatPercent": 21
  },
  {
   "productId": "567657876",
   "description": "Return costs",
   "quantity": 1,
   "grossUnitPrice": -3,
   "netUnitPrice": -2.48,
   "vatAmount": -0.52,
   "vatPercent": 21
  }
 ]
}

Response Example

    
        [
 {
  "type": "BusinessError",
  "code": "400.127",
  "message": "Cannot refund the order as refund amount is higher than the capture balance amount.",
  "customerFacingMessage": "Cannot refund the order as refund amount is higher than the capture balance amount.",
  "actionCode": "Unavailable",
  "fieldReference": ""
 }
]

Request Example

    
        {
 "captureNumber": "800090094",
 "orderItems": [
  {
   "productId": "0001-BLK-S",
   "description": "Leather jacket, Black, size S",
   "grossUnitPrice": 1190,
   "netUnitPrice": 1000,
   "vatAmount": 190,
   "quantity": 1,
   "vatPercent": 19,
   "imageUrl": "https://developer-sandbox.riverty.com/images/black_leather_jacket.jpg",
   "lineNumber": 2
  }
 ]
}