--- title: Compensation request slug: reference/compensation-request docTags: createdAt: 2026-08-23T06:01:06.452Z --- { "id": "86LULFX8eRDOueKK0V0B6", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.forter-secure.com/v2/unified-compensation-request/{id}", "servers": [ { "url": "https://api.forter-secure.com/v2/unified-compensation-request/{id}" } ], "name": "Compensation request", "description": "

Send information about a customer-initiated request for compensation, such as a refund or a reship, in order to receive a fraud or abuse decision.\nThe request can be made on an order level or at the item level. The response may also include recommendations based on your abuse prevention policies.

", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "id", "type": "string", "description": "" } ], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" }, { "kind": "required", "name": "api-version", "type": "string", "example": "10.3", "description": "Specify the version of the API to target." }, { "kind": "required", "name": "x-forter-siteid", "type": "string", "example": "a1b2c3d4e5f6", "description": "

Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.

" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "

Send information about a customer-initiated request for compensation, such as a refund or a reship, in order to receive a fraud or abuse decision.\nThe request can be made on an order level or at the item level. The response may also include recommendations based on your abuse prevention policies.

", "customType": "unifiedCompensationRequestRequest", "schema": [ { "name": "accountId", "kind": "required", "type": "string", "description": "

Customer's account UID in merchant's site. If the compensation request is from a guest account then this field should be populated with the original order id ending with the suffix '_GUEST'.

", "example": "e520-ba9a-367-60b", "maxLength": 50 }, { "name": "additionalEventIdentifiers", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "AdditionalAccountEventIdentifiers", "description": "", "modelRef": "#/components/schemas/AdditionalAccountEventIdentifiers", "schema": [] } ], "schema": [] }, { "name": "additionalInformation", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "GeneralPayloadMap", "description": "", "modelRef": "#/components/schemas/GeneralPayloadMap", "schema": [] } ], "schema": [] }, { "name": "compensationRequest", "kind": "required", "type": "object", "description": "

Details of compensation request (type of compensation requested, items for which compensation is requested, etc.)

", "modelRef": "#/components/schemas/CompensationRequest", "customType": "CompensationRequest", "schema": [ { "name": "initiationType", "kind": "required", "type": "string", "description": "What channel did the customer use to initiate the request for compensation", "example": "CALL_CENTER", "enum": [ "CALL_CENTER", "IN_STORE", "CHAT", "ONLINE", "SELF_SERVICE" ] }, { "name": "items", "kind": "required", "type": "array", "description": "A list of all items for which compensation is being requested", "modelRef": "#/components/schemas/CompensationItem", "customType": "CompensationItem[]", "schema": [ { "name": "basicItemData", "kind": "required", "type": "object", "description": "

General data regarding item such as name, price, etc.

", "modelRef": "#/components/schemas/BasicItemData", "customType": "BasicItemData", "schema": [ { "name": "category", "kind": "optional", "type": "string", "nullable": true, "description": "Item category", "example": "Apparel and accessories", "maxLength": 1000 }, { "name": "discount", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "Discount", "description": "", "modelRef": "#/components/schemas/Discount", "schema": [ { "name": "couponCodeUsed", "kind": "required", "type": "string", "description": "Coupon code used", "example": "FATHERSDAY2015", "maxLength": 150 }, { "name": "couponDiscountAmount", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "Amount", "description": "", "modelRef": "#/components/schemas/Amount", "schema": [ { "name": "amountLocalCurrency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in currency chosen by the buyer", "example": "105.55", "maxLength": 20 }, { "name": "amountUSD", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in USD", "example": "99.95", "maxLength": 12 }, { "name": "currency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code

", "example": "CAD", "maxLength": 3, "pattern": "[A-Z]{3}" } ] } ], "schema": [] }, { "name": "couponDiscountPercent", "kind": "optional", "type": "string", "nullable": true, "description": "Coupon discount amount" } ] } ], "schema": [] }, { "name": "name", "kind": "required", "type": "string", "description": "Item name", "example": "White GenericBrand handbag", "maxLength": 500 }, { "name": "price", "kind": "required", "type": "object", "description": "

Final amount due for purchase, after all discounts and promotions

", "modelRef": "#/components/schemas/Amount", "customType": "Amount", "schema": [ { "name": "amountLocalCurrency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in currency chosen by the buyer", "example": "105.55", "maxLength": 20 }, { "name": "amountUSD", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in USD", "example": "99.95", "maxLength": 12 }, { "name": "currency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code

", "example": "CAD", "maxLength": 3, "pattern": "[A-Z]{3}" } ] }, { "name": "productId", "kind": "optional", "type": "string", "nullable": true, "description": "

Unique identifier for item that is common to all identical items (such as SKU, ISBN, etc.)

", "example": "Ag54352R7768kkO", "maxLength": 70 }, { "name": "quantity", "kind": "required", "type": "number", "description": "Item quantity", "example": 1 }, { "name": "type", "kind": "required", "type": "string", "description": "

Tangible if physical item, non-tangible if any other product

", "example": "TANGIBLE", "enum": [ "TANGIBLE", "NON_TANGIBLE" ] } ] }, { "name": "itemCompensationData", "kind": "required", "type": "object", "description": "Data relating to the return of the item", "modelRef": "#/components/schemas/CompensationData", "customType": "CompensationData", "schema": [ { "name": "compensationTypeRequested", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Indicates whether the customer requested a refund, store credit, replacement etc.

", "example": "REFUND", "enum": [ "REPLACEMENT", "REFUND", "REFUND_UPON_RETURN", "CREDIT", "MIXED", "UNKNOWN", "NO_COMPENSATION" ] }, { "name": "initiationTime", "kind": "required", "type": "number", "description": "

The time that the customer initiated the request for compensation in MILLISECONDS since unix epoch (Jan 1, 1970)

", "example": 1415287568000 }, { "name": "internalReasonCategory", "kind": "optional", "type": "string", "nullable": true, "description": "The reason for the request as defined by the merchant", "example": "defective item", "maxLength": 40 }, { "name": "reasonCategory", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nReason for compensation request", "example": "CHANGED_MY_MIND", "enum": [ "CHANGED_MY_MIND", "DOES_NOT_FIT", "NOT_AS_DESCRIBED", "WRONG_ITEM", "ARRIVED_TOO_LATE", "LOW_QUALITY", "DAMAGED_GOODS", "GIFT_RETURN", "RETURN_TO_SENDER", "RETURN_POLICY_EXCEPTION", "OTHER", "UNKNOWN", "ITEM_NOT_RECEIVED", "ENTIRE_ORDER_NOT_RECEIVED", "OUTBOUND_ISSUE_CARRIER", "OUTBOUND_ISSUE_MERCHANT", "FAILED_DELIVERY", "INBOUND_LOSS", "INBOUND_ISSUE_CARRIER" ] }, { "name": "requestedReturnType", "kind": "required", "type": "string", "description": "

Method of return requested by customer (or the request to not return item at all)

", "example": "SHIP_TO_WAREHOUSE", "enum": [ "SHIP_TO_WAREHOUSE", "IN_STORE", "NO_RETURN" ] } ] } ] }, { "name": "orderCompensationData", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "CompensationData", "description": "", "modelRef": "#/components/schemas/CompensationData", "schema": [ { "name": "compensationTypeRequested", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Indicates whether the customer requested a refund, store credit, replacement etc.

", "example": "REFUND", "enum": [ "REPLACEMENT", "REFUND", "REFUND_UPON_RETURN", "CREDIT", "MIXED", "UNKNOWN", "NO_COMPENSATION" ] }, { "name": "initiationTime", "kind": "required", "type": "number", "description": "

The time that the customer initiated the request for compensation in MILLISECONDS since unix epoch (Jan 1, 1970)

", "example": 1415287568000 }, { "name": "internalReasonCategory", "kind": "optional", "type": "string", "nullable": true, "description": "The reason for the request as defined by the merchant", "example": "defective item", "maxLength": 40 }, { "name": "reasonCategory", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nReason for compensation request", "example": "CHANGED_MY_MIND", "enum": [ "CHANGED_MY_MIND", "DOES_NOT_FIT", "NOT_AS_DESCRIBED", "WRONG_ITEM", "ARRIVED_TOO_LATE", "LOW_QUALITY", "DAMAGED_GOODS", "GIFT_RETURN", "RETURN_TO_SENDER", "RETURN_POLICY_EXCEPTION", "OTHER", "UNKNOWN", "ITEM_NOT_RECEIVED", "ENTIRE_ORDER_NOT_RECEIVED", "OUTBOUND_ISSUE_CARRIER", "OUTBOUND_ISSUE_MERCHANT", "FAILED_DELIVERY", "INBOUND_LOSS", "INBOUND_ISSUE_CARRIER" ] }, { "name": "requestedReturnType", "kind": "required", "type": "string", "description": "

Method of return requested by customer (or the request to not return item at all)

", "example": "SHIP_TO_WAREHOUSE", "enum": [ "SHIP_TO_WAREHOUSE", "IN_STORE", "NO_RETURN" ] } ] } ], "schema": [] }, { "name": "totalRequestedAmount", "kind": "required", "type": "object", "description": "Total amount of the compensation requested by customer", "modelRef": "#/components/schemas/Amount", "customType": "Amount", "schema": [ { "name": "amountLocalCurrency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in currency chosen by the buyer", "example": "105.55", "maxLength": 20 }, { "name": "amountUSD", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in USD", "example": "99.95", "maxLength": 12 }, { "name": "currency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code

", "example": "CAD", "maxLength": 3, "pattern": "[A-Z]{3}" } ] } ] }, { "name": "connectionInformation", "kind": "required", "type": "object", "description": "

Connection information about the customer typically found in the HTTP request header, if the compensation was initiated online

", "modelRef": "#/components/schemas/ConnectionInformation", "customType": "ConnectionInformation", "schema": [ { "name": "checkoutToolsSessionId", "kind": "optional", "type": "string", "nullable": true, "description": "CheckoutToolsSessionId received from the SDK", "example": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd", "maxLength": 128 }, { "name": "customerIP", "kind": "required", "type": "string", "description": "Customer IP address in IPv4 or IPv6 format. If missing should be populated with 127.0.0.1", "example": "10.0.0.127" }, { "name": "forterMobileUID", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

mobile UID. The device identifier such as IMEI in android or identifier for vendor in iOS. This should match the deviceId sent via the mobile events API (for mobile transactions only)

", "example": "6429751237891", "maxLength": 128 }, { "name": "forterTokenCookie", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nForter token cookie from request headers", "example": "249453te8tbf9355186fet0ken547b95_2786972955236__UDE52-n5_8dg", "maxLength": 128 }, { "name": "merchantDeviceIdentifier", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nA unique device identifier generated by merchant", "example": "HGJ7512345H3", "maxLength": 100 }, { "name": "merchantProvidedSessionId", "kind": "optional", "type": "string", "nullable": true, "description": "An identifier of the merchant session", "example": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd", "maxLength": 128 }, { "name": "userAgent", "kind": "required", "type": "string", "description": "Customer's User agent", "example": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36", "maxLength": 4096 } ] }, { "name": "eventId", "kind": "required", "type": "string", "description": "Unique identifier of this compensation request", "example": "r48987fgdse0r", "maxLength": 40 }, { "name": "eventTime", "kind": "required", "type": "number", "description": "

The time that the trigger event occurred in MILLISECONDS since unix epoch (Jan 1, 1970)

", "example": 1415287568000 }, { "name": "hasProofOfPurchase", "kind": "optional", "type": "boolean", "nullable": true, "description": "Whether the user has a proof of purchase", "example": true }, { "name": "isGuestAccount", "kind": "required", "type": "boolean", "description": "Boolean field indicating if account is a guest account.", "example": false }, { "name": "merchantAgentData", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "MerchantAgentData", "description": "", "modelRef": "#/components/schemas/MerchantAgentData", "schema": [ { "name": "merchantAgentId", "kind": "optional", "type": "string", "nullable": true, "description": "Unique identifier of the agent processing the customer's request", "example": "HG36885TZ" }, { "name": "merchantAgentName", "kind": "optional", "type": "string", "nullable": true, "description": "Name of the agent processing the customer's request", "example": "John Smith" } ] } ], "schema": [] }, { "name": "merchantIdentifiers", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "MerchantIdentifiers", "description": "", "modelRef": "#/components/schemas/MerchantIdentifiers", "schema": [ { "name": "merchantDomain", "kind": "optional", "type": "string", "nullable": true, "description": "

Use if merchant operates several sites (such as a regular site and a related discount brand)

", "example": "HandbagsExpressDiscounts.com", "maxLength": 2048 }, { "name": "merchantName", "kind": "optional", "type": "string", "nullable": true, "description": "

Use if merchant operates several sites (such as a regular site and a related discount brand)

", "example": "Handbags Express Discounts", "maxLength": 50 } ] } ], "schema": [] }, { "name": "originalOrderId", "kind": "required", "type": "string", "description": "

Unique order/transaction identifier for which compensation is being requested in this compensation event. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.

", "example": "2356fdse0rr489", "maxLength": 40 }, { "name": "status", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "CompensationStatus", "description": "", "modelRef": "#/components/schemas/CompensationStatus", "schema": [ { "name": "hasProofOfPurchase", "kind": "optional", "type": "boolean", "nullable": true, "description": "" }, { "name": "itemStatus", "kind": "required", "type": "array", "description": "A list of all items for which compensation was requested", "modelRef": "#/components/schemas/ItemCompensationStatus", "customType": "ItemCompensationStatus[]", "schema": [ { "name": "basicItemData", "kind": "required", "type": "object", "description": "

General data regarding item such as name, price, etc.

", "modelRef": "#/components/schemas/BasicItemData", "customType": "BasicItemData", "schema": [ { "name": "category", "kind": "optional", "type": "string", "nullable": true, "description": "Item category", "example": "Apparel and accessories", "maxLength": 1000 }, { "name": "discount", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "Discount", "description": "", "modelRef": "#/components/schemas/Discount", "schema": [ { "name": "couponCodeUsed", "kind": "required", "type": "string", "description": "Coupon code used", "example": "FATHERSDAY2015", "maxLength": 150 }, { "name": "couponDiscountAmount", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "Amount", "description": "", "modelRef": "#/components/schemas/Amount", "schema": [ { "name": "amountLocalCurrency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in currency chosen by the buyer", "example": "105.55", "maxLength": 20 }, { "name": "amountUSD", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in USD", "example": "99.95", "maxLength": 12 }, { "name": "currency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code

", "example": "CAD", "maxLength": 3, "pattern": "[A-Z]{3}" } ] } ], "schema": [] }, { "name": "couponDiscountPercent", "kind": "optional", "type": "string", "nullable": true, "description": "Coupon discount amount" } ] } ], "schema": [] }, { "name": "name", "kind": "required", "type": "string", "description": "Item name", "example": "White GenericBrand handbag", "maxLength": 500 }, { "name": "price", "kind": "required", "type": "object", "description": "

Final amount due for purchase, after all discounts and promotions

", "modelRef": "#/components/schemas/Amount", "customType": "Amount", "schema": [ { "name": "amountLocalCurrency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in currency chosen by the buyer", "example": "105.55", "maxLength": 20 }, { "name": "amountUSD", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in USD", "example": "99.95", "maxLength": 12 }, { "name": "currency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code

", "example": "CAD", "maxLength": 3, "pattern": "[A-Z]{3}" } ] }, { "name": "productId", "kind": "optional", "type": "string", "nullable": true, "description": "

Unique identifier for item that is common to all identical items (such as SKU, ISBN, etc.)

", "example": "Ag54352R7768kkO", "maxLength": 70 }, { "name": "quantity", "kind": "required", "type": "number", "description": "Item quantity", "example": 1 }, { "name": "type", "kind": "required", "type": "string", "description": "

Tangible if physical item, non-tangible if any other product

", "example": "TANGIBLE", "enum": [ "TANGIBLE", "NON_TANGIBLE" ] } ] }, { "name": "statusData", "kind": "required", "type": "object", "description": "Data relating to the return of the item", "modelRef": "#/components/schemas/ItemCompensationStatusData", "customType": "ItemCompensationStatusData", "schema": [ { "name": "compensationTypeGranted", "kind": "required", "type": "string", "description": "

Indicates whether the customer was granted a refund, store credit, replacement etc.

", "example": "REFUND", "enum": [ "REPLACEMENT", "REFUND", "REFUND_UPON_RETURN", "CREDIT", "MIXED", "UNKNOWN", "NO_COMPENSATION" ] }, { "name": "internalReasonCategory", "kind": "optional", "type": "string", "nullable": true, "description": "The reason for the request as defined by the merchant", "example": "defective item", "maxLength": 40 }, { "name": "reasonCategory", "kind": "required", "type": "string", "description": "Reason for compensation request", "example": "CHANGED_MY_MIND", "enum": [ "CHANGED_MY_MIND", "DOES_NOT_FIT", "NOT_AS_DESCRIBED", "WRONG_ITEM", "ARRIVED_TOO_LATE", "LOW_QUALITY", "DAMAGED_GOODS", "GIFT_RETURN", "RETURN_TO_SENDER", "RETURN_POLICY_EXCEPTION", "OTHER", "UNKNOWN", "ITEM_NOT_RECEIVED", "ENTIRE_ORDER_NOT_RECEIVED", "OUTBOUND_ISSUE_CARRIER", "OUTBOUND_ISSUE_MERCHANT", "FAILED_DELIVERY", "INBOUND_LOSS", "INBOUND_ISSUE_CARRIER" ] }, { "name": "returnCondition", "kind": "optional", "type": "string", "nullable": true, "description": "Condition of the item returned", "example": "DAMAGED", "enum": [ "GOOD_CONDITION", "DAMAGED", "WRONG_ITEM", "NO_ITEM", "NOT_ARRIVED", "NO_RETURN" ], "maxLength": 40 }, { "name": "returnMethodGranted", "kind": "required", "type": "string", "description": "Method of return granted to customer", "example": "SHIP_TO_WAREHOUSE", "enum": [ "SHIP_TO_WAREHOUSE", "IN_STORE", "NO_RETURN" ] }, { "name": "statusLog", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "CompensationStatusLog", "description": "", "modelRef": "#/components/schemas/CompensationStatusLog", "schema": [ { "name": "arrivedToWarehouseTime", "kind": "optional", "type": "number", "nullable": true, "description": "Time returned items arrived to the merchant's warehouse", "example": 1420070400000 }, { "name": "initiationTime", "kind": "optional", "type": "number", "nullable": true, "description": "

The time that the customer initiated the request for compensation in MILLISECONDS since unix epoch (Jan 1, 1970)

", "example": 1415287568000 }, { "name": "initiationType", "kind": "optional", "type": "string", "nullable": true, "description": "What channel did the customer use to initiate the request for compensation", "example": "CALL_CENTER", "enum": [ "CALL_CENTER", "IN_STORE", "CHAT", "ONLINE", "SELF_SERVICE" ] }, { "name": "shippedByCustomerTime", "kind": "optional", "type": "number", "nullable": true, "description": "Time returned items were shipped by the customer", "example": 1420070400000 } ] } ], "schema": [] }, { "name": "updatedStatus", "kind": "required", "type": "string", "description": "The updated compensation request status", "example": "ACCEPTED_BY_MERCHANT", "enum": [ "ACCEPTED_BY_MERCHANT", "REJECTED_BY_MERCHANT", "WITHDRAWN_BY_CUSTOMER" ] } ] } ] }, { "name": "merchantAgentData", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "MerchantAgentData", "description": "", "modelRef": "#/components/schemas/MerchantAgentData", "schema": [ { "name": "merchantAgentId", "kind": "optional", "type": "string", "nullable": true, "description": "Unique identifier of the agent processing the customer's request", "example": "HG36885TZ" }, { "name": "merchantAgentName", "kind": "optional", "type": "string", "nullable": true, "description": "Name of the agent processing the customer's request", "example": "John Smith" } ] } ], "schema": [] }, { "name": "replacementOrderId", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Unique order/transaction identifier for a replacement order issued by the merchant in response to this request

", "example": "2356fdse0rr489", "maxLength": 40 }, { "name": "shippingRefunded", "kind": "optional", "type": "boolean", "nullable": true, "description": "Indicates whether merchant reimbursed the customer for shipping expenses" }, { "name": "shippingRefundedAmount", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "Amount", "description": "", "modelRef": "#/components/schemas/Amount", "schema": [ { "name": "amountLocalCurrency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in currency chosen by the buyer", "example": "105.55", "maxLength": 20 }, { "name": "amountUSD", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in USD", "example": "99.95", "maxLength": 12 }, { "name": "currency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code

", "example": "CAD", "maxLength": 3, "pattern": "[A-Z]{3}" } ] } ], "schema": [] }, { "name": "statusData", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "ItemCompensationStatusData", "description": "", "modelRef": "#/components/schemas/ItemCompensationStatusData", "schema": [ { "name": "compensationTypeGranted", "kind": "required", "type": "string", "description": "

Indicates whether the customer was granted a refund, store credit, replacement etc.

", "example": "REFUND", "enum": [ "REPLACEMENT", "REFUND", "REFUND_UPON_RETURN", "CREDIT", "MIXED", "UNKNOWN", "NO_COMPENSATION" ] }, { "name": "internalReasonCategory", "kind": "optional", "type": "string", "nullable": true, "description": "The reason for the request as defined by the merchant", "example": "defective item", "maxLength": 40 }, { "name": "reasonCategory", "kind": "required", "type": "string", "description": "Reason for compensation request", "example": "CHANGED_MY_MIND", "enum": [ "CHANGED_MY_MIND", "DOES_NOT_FIT", "NOT_AS_DESCRIBED", "WRONG_ITEM", "ARRIVED_TOO_LATE", "LOW_QUALITY", "DAMAGED_GOODS", "GIFT_RETURN", "RETURN_TO_SENDER", "RETURN_POLICY_EXCEPTION", "OTHER", "UNKNOWN", "ITEM_NOT_RECEIVED", "ENTIRE_ORDER_NOT_RECEIVED", "OUTBOUND_ISSUE_CARRIER", "OUTBOUND_ISSUE_MERCHANT", "FAILED_DELIVERY", "INBOUND_LOSS", "INBOUND_ISSUE_CARRIER" ] }, { "name": "returnCondition", "kind": "optional", "type": "string", "nullable": true, "description": "Condition of the item returned", "example": "DAMAGED", "enum": [ "GOOD_CONDITION", "DAMAGED", "WRONG_ITEM", "NO_ITEM", "NOT_ARRIVED", "NO_RETURN" ], "maxLength": 40 }, { "name": "returnMethodGranted", "kind": "required", "type": "string", "description": "Method of return granted to customer", "example": "SHIP_TO_WAREHOUSE", "enum": [ "SHIP_TO_WAREHOUSE", "IN_STORE", "NO_RETURN" ] }, { "name": "statusLog", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "CompensationStatusLog", "description": "", "modelRef": "#/components/schemas/CompensationStatusLog", "schema": [ { "name": "arrivedToWarehouseTime", "kind": "optional", "type": "number", "nullable": true, "description": "Time returned items arrived to the merchant's warehouse", "example": 1420070400000 }, { "name": "initiationTime", "kind": "optional", "type": "number", "nullable": true, "description": "

The time that the customer initiated the request for compensation in MILLISECONDS since unix epoch (Jan 1, 1970)

", "example": 1415287568000 }, { "name": "initiationType", "kind": "optional", "type": "string", "nullable": true, "description": "What channel did the customer use to initiate the request for compensation", "example": "CALL_CENTER", "enum": [ "CALL_CENTER", "IN_STORE", "CHAT", "ONLINE", "SELF_SERVICE" ] }, { "name": "shippedByCustomerTime", "kind": "optional", "type": "number", "nullable": true, "description": "Time returned items were shipped by the customer", "example": 1420070400000 } ] } ], "schema": [] }, { "name": "updatedStatus", "kind": "required", "type": "string", "description": "The updated compensation request status", "example": "ACCEPTED_BY_MERCHANT", "enum": [ "ACCEPTED_BY_MERCHANT", "REJECTED_BY_MERCHANT", "WITHDRAWN_BY_CUSTOMER" ] } ] } ], "schema": [] }, { "name": "totalGrantedAmount", "kind": "required", "type": "object", "description": "

Total amount of the compensation granted to customer (excluding shippingRefundedAmount)

", "modelRef": "#/components/schemas/Amount", "customType": "Amount", "schema": [ { "name": "amountLocalCurrency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in currency chosen by the buyer", "example": "105.55", "maxLength": 20 }, { "name": "amountUSD", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in USD", "example": "99.95", "maxLength": 12 }, { "name": "currency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code

", "example": "CAD", "maxLength": 3, "pattern": "[A-Z]{3}" } ] } ] } ], "schema": [] } ], "modelRef": "#/components/schemas/unifiedCompensationRequestRequest", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "basicAuth", "name": "basicAuth", "kind": "optional", "type": "http", "scheme": "basic" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "Example unifiedCompensationRequestResponse", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "The response object of a forter compensation request call", "customType": "unifiedCompensationRequestResponse", "schema": [ { "name": "correlationId", "kind": "required", "type": "string", "description": "A Forter unique identifier that was provided as part of a Forter API response. Used to correlate between the compensation request event and final status update", "example": "HGJ7512345H3DE" }, { "name": "decisionReason", "kind": "required", "type": "string", "description": "", "example": "", "maxLength": 1000 }, { "name": "forterDecision", "kind": "required", "type": "string", "description": "The message containing the decision", "example": "approve", "maxLength": 1000 }, { "name": "merchantPolicyId", "kind": "required", "type": "string", "description": "UID of the custom policy created in Forter's Policies tool that resulted in this decision", "example": "0ee8ba28a8654c659addbae9253b707c" }, { "name": "recommendations", "kind": "required", "type": "array", "description": "Forter's recommendations for the optimal way of proceeding with the compensation request", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "status", "kind": "required", "type": "string", "description": "Status of the request processing", "example": "success", "maxLength": 50 } ], "modelRef": "#/components/schemas/unifiedCompensationRequestResponse", "isExpanded": true } ] }, { "statusCode": "400", "description": "

Bad Request (Often missing a required parameter)

", "jsonExample": "", "isExpanded": true }, { "statusCode": "401", "description": "

Unauthorized (No valid API key provided)

", "jsonExample": "", "isExpanded": true }, { "statusCode": "404", "description": "

Not Found (The requested item doesn't exist)

", "jsonExample": "", "isExpanded": true }, { "statusCode": "500", "description": "

Server Error (Something went wrong on Forter's end)

", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "ZjTtBtXimNISs0FfV6PTq", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.forter-secure.com/v2/unified-compensation-request/{id} \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'api-version: 10.3' \\\n --header 'x-forter-siteid: a1b2c3d4e5f6' \\\n --data '{\n \"accountId\": \"e520-ba9a-367-60b\",\n \"additionalEventIdentifiers\": {},\n \"additionalInformation\": {},\n \"compensationRequest\": {\n \"initiationType\": \"CALL_CENTER\",\n \"items\": [\n {\n \"basicItemData\": {\n \"discount\": {\n \"couponCodeUsed\": \"FATHERSDAY2015\",\n \"couponDiscountAmount\": {}\n },\n \"name\": \"White GenericBrand handbag\",\n \"price\": {},\n \"quantity\": 1,\n \"type\": \"TANGIBLE\"\n },\n \"itemCompensationData\": {\n \"initiationTime\": 1415287568000,\n \"requestedReturnType\": \"SHIP_TO_WAREHOUSE\"\n }\n }\n ],\n \"orderCompensationData\": {\n \"initiationTime\": 1415287568000,\n \"requestedReturnType\": \"SHIP_TO_WAREHOUSE\"\n },\n \"totalRequestedAmount\": {}\n },\n \"connectionInformation\": {\n \"customerIP\": \"10.0.0.127\",\n \"userAgent\": \"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36\"\n },\n \"eventId\": \"r48987fgdse0r\",\n \"eventTime\": 1415287568000,\n \"isGuestAccount\": false,\n \"merchantAgentData\": {},\n \"merchantIdentifiers\": {},\n \"originalOrderId\": \"2356fdse0rr489\",\n \"status\": {\n \"itemStatus\": [\n {\n \"basicItemData\": {\n \"discount\": {\n \"couponCodeUsed\": \"FATHERSDAY2015\",\n \"couponDiscountAmount\": {}\n },\n \"name\": \"White GenericBrand handbag\",\n \"price\": {},\n \"quantity\": 1,\n \"type\": \"TANGIBLE\"\n },\n \"statusData\": {\n \"compensationTypeGranted\": \"REFUND\",\n \"reasonCategory\": \"CHANGED_MY_MIND\",\n \"returnMethodGranted\": \"SHIP_TO_WAREHOUSE\",\n \"statusLog\": {},\n \"updatedStatus\": \"ACCEPTED_BY_MERCHANT\"\n }\n }\n ],\n \"merchantAgentData\": {},\n \"shippingRefundedAmount\": {},\n \"statusData\": {\n \"compensationTypeGranted\": \"REFUND\",\n \"reasonCategory\": \"CHANGED_MY_MIND\",\n \"returnMethodGranted\": \"SHIP_TO_WAREHOUSE\",\n \"statusLog\": {},\n \"updatedStatus\": \"ACCEPTED_BY_MERCHANT\"\n },\n \"totalGrantedAmount\": {}\n }\n }'" }, { "id": "9BDrL2DQ4CITD3Ecit_z0", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\nmyHeaders.append(\"api-version\", \"10.3\");\nmyHeaders.append(\"x-forter-siteid\", \"a1b2c3d4e5f6\");\n\nvar raw = JSON.stringify({\n \"accountId\": \"e520-ba9a-367-60b\",\n \"additionalEventIdentifiers\": {},\n \"additionalInformation\": {},\n \"compensationRequest\": {\n \"initiationType\": \"CALL_CENTER\",\n \"items\": [\n {\n \"basicItemData\": {\n \"discount\": {\n \"couponCodeUsed\": \"FATHERSDAY2015\",\n \"couponDiscountAmount\": {}\n },\n \"name\": \"White GenericBrand handbag\",\n \"price\": {},\n \"quantity\": 1,\n \"type\": \"TANGIBLE\"\n },\n \"itemCompensationData\": {\n \"initiationTime\": 1415287568000,\n \"requestedReturnType\": \"SHIP_TO_WAREHOUSE\"\n }\n }\n ],\n \"orderCompensationData\": {\n \"initiationTime\": 1415287568000,\n \"requestedReturnType\": \"SHIP_TO_WAREHOUSE\"\n },\n \"totalRequestedAmount\": {}\n },\n \"connectionInformation\": {\n \"customerIP\": \"10.0.0.127\",\n \"userAgent\": \"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36\"\n },\n \"eventId\": \"r48987fgdse0r\",\n \"eventTime\": 1415287568000,\n \"isGuestAccount\": false,\n \"merchantAgentData\": {},\n \"merchantIdentifiers\": {},\n \"originalOrderId\": \"2356fdse0rr489\",\n \"status\": {\n \"itemStatus\": [\n {\n \"basicItemData\": {\n \"discount\": {\n \"couponCodeUsed\": \"FATHERSDAY2015\",\n \"couponDiscountAmount\": {}\n },\n \"name\": \"White GenericBrand handbag\",\n \"price\": {},\n \"quantity\": 1,\n \"type\": \"TANGIBLE\"\n },\n \"statusData\": {\n \"compensationTypeGranted\": \"REFUND\",\n \"reasonCategory\": \"CHANGED_MY_MIND\",\n \"returnMethodGranted\": \"SHIP_TO_WAREHOUSE\",\n \"statusLog\": {},\n \"updatedStatus\": \"ACCEPTED_BY_MERCHANT\"\n }\n }\n ],\n \"merchantAgentData\": {},\n \"shippingRefundedAmount\": {},\n \"statusData\": {\n \"compensationTypeGranted\": \"REFUND\",\n \"reasonCategory\": \"CHANGED_MY_MIND\",\n \"returnMethodGranted\": \"SHIP_TO_WAREHOUSE\",\n \"statusLog\": {},\n \"updatedStatus\": \"ACCEPTED_BY_MERCHANT\"\n },\n \"totalGrantedAmount\": {}\n }\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.forter-secure.com/v2/unified-compensation-request/{id}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "dHJz-BqzgFoQGkyTLVi5H", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.forter-secure.com/v2/unified-compensation-request/{id}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"api-version\"] = \"10.3\"\nrequest[\"x-forter-siteid\"] = \"a1b2c3d4e5f6\"\nrequest.body = JSON.dump({\n \"accountId\": \"e520-ba9a-367-60b\",\n \"additionalEventIdentifiers\": {},\n \"additionalInformation\": {},\n \"compensationRequest\": {\n \"initiationType\": \"CALL_CENTER\",\n \"items\": [\n {\n \"basicItemData\": {\n \"discount\": {\n \"couponCodeUsed\": \"FATHERSDAY2015\",\n \"couponDiscountAmount\": {}\n },\n \"name\": \"White GenericBrand handbag\",\n \"price\": {},\n \"quantity\": 1,\n \"type\": \"TANGIBLE\"\n },\n \"itemCompensationData\": {\n \"initiationTime\": 1415287568000,\n \"requestedReturnType\": \"SHIP_TO_WAREHOUSE\"\n }\n }\n ],\n \"orderCompensationData\": {\n \"initiationTime\": 1415287568000,\n \"requestedReturnType\": \"SHIP_TO_WAREHOUSE\"\n },\n \"totalRequestedAmount\": {}\n },\n \"connectionInformation\": {\n \"customerIP\": \"10.0.0.127\",\n \"userAgent\": \"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36\"\n },\n \"eventId\": \"r48987fgdse0r\",\n \"eventTime\": 1415287568000,\n \"isGuestAccount\": false,\n \"merchantAgentData\": {},\n \"merchantIdentifiers\": {},\n \"originalOrderId\": \"2356fdse0rr489\",\n \"status\": {\n \"itemStatus\": [\n {\n \"basicItemData\": {\n \"discount\": {\n \"couponCodeUsed\": \"FATHERSDAY2015\",\n \"couponDiscountAmount\": {}\n },\n \"name\": \"White GenericBrand handbag\",\n \"price\": {},\n \"quantity\": 1,\n \"type\": \"TANGIBLE\"\n },\n \"statusData\": {\n \"compensationTypeGranted\": \"REFUND\",\n \"reasonCategory\": \"CHANGED_MY_MIND\",\n \"returnMethodGranted\": \"SHIP_TO_WAREHOUSE\",\n \"statusLog\": {},\n \"updatedStatus\": \"ACCEPTED_BY_MERCHANT\"\n }\n }\n ],\n \"merchantAgentData\": {},\n \"shippingRefundedAmount\": {},\n \"statusData\": {\n \"compensationTypeGranted\": \"REFUND\",\n \"reasonCategory\": \"CHANGED_MY_MIND\",\n \"returnMethodGranted\": \"SHIP_TO_WAREHOUSE\",\n \"statusLog\": {},\n \"updatedStatus\": \"ACCEPTED_BY_MERCHANT\"\n },\n \"totalGrantedAmount\": {}\n }\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "NG962nlWD7wG3QXEPW5M0", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.forter-secure.com/v2/unified-compensation-request/{id}\"\n\npayload = json.dumps({\n \"accountId\": \"e520-ba9a-367-60b\",\n \"additionalEventIdentifiers\": {},\n \"additionalInformation\": {},\n \"compensationRequest\": {\n \"initiationType\": \"CALL_CENTER\",\n \"items\": [\n {\n \"basicItemData\": {\n \"discount\": {\n \"couponCodeUsed\": \"FATHERSDAY2015\",\n \"couponDiscountAmount\": {}\n },\n \"name\": \"White GenericBrand handbag\",\n \"price\": {},\n \"quantity\": 1,\n \"type\": \"TANGIBLE\"\n },\n \"itemCompensationData\": {\n \"initiationTime\": 1415287568000,\n \"requestedReturnType\": \"SHIP_TO_WAREHOUSE\"\n }\n }\n ],\n \"orderCompensationData\": {\n \"initiationTime\": 1415287568000,\n \"requestedReturnType\": \"SHIP_TO_WAREHOUSE\"\n },\n \"totalRequestedAmount\": {}\n },\n \"connectionInformation\": {\n \"customerIP\": \"10.0.0.127\",\n \"userAgent\": \"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36\"\n },\n \"eventId\": \"r48987fgdse0r\",\n \"eventTime\": 1415287568000,\n \"isGuestAccount\": False,\n \"merchantAgentData\": {},\n \"merchantIdentifiers\": {},\n \"originalOrderId\": \"2356fdse0rr489\",\n \"status\": {\n \"itemStatus\": [\n {\n \"basicItemData\": {\n \"discount\": {\n \"couponCodeUsed\": \"FATHERSDAY2015\",\n \"couponDiscountAmount\": {}\n },\n \"name\": \"White GenericBrand handbag\",\n \"price\": {},\n \"quantity\": 1,\n \"type\": \"TANGIBLE\"\n },\n \"statusData\": {\n \"compensationTypeGranted\": \"REFUND\",\n \"reasonCategory\": \"CHANGED_MY_MIND\",\n \"returnMethodGranted\": \"SHIP_TO_WAREHOUSE\",\n \"statusLog\": {},\n \"updatedStatus\": \"ACCEPTED_BY_MERCHANT\"\n }\n }\n ],\n \"merchantAgentData\": {},\n \"shippingRefundedAmount\": {},\n \"statusData\": {\n \"compensationTypeGranted\": \"REFUND\",\n \"reasonCategory\": \"CHANGED_MY_MIND\",\n \"returnMethodGranted\": \"SHIP_TO_WAREHOUSE\",\n \"statusLog\": {},\n \"updatedStatus\": \"ACCEPTED_BY_MERCHANT\"\n },\n \"totalGrantedAmount\": {}\n }\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json',\n 'api-version': '10.3',\n 'x-forter-siteid': 'a1b2c3d4e5f6'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "ZjTtBtXimNISs0FfV6PTq" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// Example unifiedCompensationRequestResponse\n{\n \"correlationId\": \"HGJ7512345H3DE\",\n \"decisionReason\": \"\",\n \"forterDecision\": \"approve\",\n \"merchantPolicyId\": \"0ee8ba28a8654c659addbae9253b707c\",\n \"recommendations\": [\n \"\"\n ],\n \"status\": \"success\"\n}" }, { "id": "response-1-400", "language": "400", "code": "// Bad Request (Often missing a required parameter)\n" }, { "id": "response-2-401", "language": "401", "code": "// Unauthorized (No valid API key provided)\n" }, { "id": "response-3-404", "language": "404", "code": "// Not Found (The requested item doesn't exist)\n" }, { "id": "response-4-500", "language": "500", "code": "// Server Error (Something went wrong on Forter's end)\n" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "" } ] }