Compensation request

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. The 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.

idstring required

api-versionstring required

Example:10.1

Specify the version of the API to target.

x-forter-siteidstring required

Example:a1b2c3d4e5f6

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

Authorizationstring required

Example:Basic <base64-encoded-api-key:>

Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.

Request body

accountIdstring required

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'.

additionalEventIdentifiersobject nullable

Additional identifiers of the account event

additionalInformationobject nullable

General payload object

eventIdstring required

Unique identifier of this compensation request

eventTimenumber required

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

hasProofOfPurchaseboolean nullable

Whether the user has a proof of purchase

isGuestAccountboolean required

Boolean field indicating if account is a guest account.

originalOrderIdstring required

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 request

{
  "accountId": "e520-ba9a-367-60b",
  "compensationRequest": {
    "initiationType": "CALL_CENTER",
    "items": [
      {
        "basicItemData": {
          "category": "Apparel and accessories",
          "discount": {
            "couponCodeUsed": "FATHERSDAY2015",
            "couponDiscountAmount": {
              "amountLocalCurrency": "105.55",
              "amountUSD": "99.95",
              "currency": "CAD"
            }
          },
          "name": "White GenericBrand handbag",
          "price": {
            "amountLocalCurrency": "105.55",
            "amountUSD": "99.95",
            "currency": "CAD"
          },
          "productId": "Ag54352R7768kkO",
          "quantity": 1,
          "type": "TANGIBLE"
        },
        "itemCompensationData": {
          "compensationTypeRequested": "REFUND",
          "initiationTime": 1415287568000,
          "internalReasonCategory": "defective item",
          "reasonCategory": "CHANGED_MY_MIND",
          "requestedReturnType": "SHIP_TO_WAREHOUSE"
        }
      }
    ],
    "orderCompensationData": {
      "compensationTypeRequested": "REFUND",
      "initiationTime": 1415287568000,
      "internalReasonCategory": "defective item",
      "reasonCategory": "CHANGED_MY_MIND",
      "requestedReturnType": "SHIP_TO_WAREHOUSE"
    },
    "totalRequestedAmount": {
      "amountLocalCurrency": "105.55",
      "amountUSD": "99.95",
      "currency": "CAD"
    }
  },
  "connectionInformation": {
    "checkoutToolsSessionId": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd",
    "customerIP": "10.0.0.127",
    "forterMobileUID": "6429751237891",
    "forterTokenCookie": "249453te8tbf9355186fet0ken547b95_2786972955236__UDE52-n5_8dg",
    "merchantDeviceIdentifier": "HGJ7512345H3",
    "merchantProvidedSessionId": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd",
    "userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36"
  },
  "eventId": "r48987fgdse0r",
  "eventTime": 1415287568000,
  "hasProofOfPurchase": true,
  "merchantAgentData": {
    "merchantAgentId": "HG36885TZ",
    "merchantAgentName": "John Smith"
  },
  "merchantIdentifiers": {
    "merchantDomain": "HandbagsExpressDiscounts.com",
    "merchantName": "Handbags Express Discounts"
  },
  "originalOrderId": "2356fdse0rr489",
  "status": {
    "itemStatus": [
      {
        "basicItemData": {
          "category": "Apparel and accessories",
          "discount": {
            "couponCodeUsed": "FATHERSDAY2015",
            "couponDiscountAmount": {
              "amountLocalCurrency": "105.55",
              "amountUSD": "99.95",
              "currency": "CAD"
            }
          },
          "name": "White GenericBrand handbag",
          "price": {
            "amountLocalCurrency": "105.55",
            "amountUSD": "99.95",
            "currency": "CAD"
          },
          "productId": "Ag54352R7768kkO",
          "quantity": 1,
          "type": "TANGIBLE"
        },
        "statusData": {
          "compensationTypeGranted": "REFUND",
          "internalReasonCategory": "defective item",
          "reasonCategory": "CHANGED_MY_MIND",
          "returnCondition": "DAMAGED",
          "returnMethodGranted": "SHIP_TO_WAREHOUSE",
          "statusLog": {
            "arrivedToWarehouseTime": 1420070400000,
            "initiationTime": 1415287568000,
            "initiationType": "CALL_CENTER",
            "shippedByCustomerTime": 1420070400000
          },
          "updatedStatus": "ACCEPTED_BY_MERCHANT"
        }
      }
    ],
    "merchantAgentData": {
      "merchantAgentId": "HG36885TZ",
      "merchantAgentName": "John Smith"
    },
    "replacementOrderId": "2356fdse0rr489",
    "shippingRefundedAmount": {
      "amountLocalCurrency": "105.55",
      "amountUSD": "99.95",
      "currency": "CAD"
    },
    "statusData": {
      "compensationTypeGranted": "REFUND",
      "internalReasonCategory": "defective item",
      "reasonCategory": "CHANGED_MY_MIND",
      "returnCondition": "DAMAGED",
      "returnMethodGranted": "SHIP_TO_WAREHOUSE",
      "statusLog": {
        "arrivedToWarehouseTime": 1420070400000,
        "initiationTime": 1415287568000,
        "initiationType": "CALL_CENTER",
        "shippedByCustomerTime": 1420070400000
      },
      "updatedStatus": "ACCEPTED_BY_MERCHANT"
    },
    "totalGrantedAmount": {
      "amountLocalCurrency": "105.55",
      "amountUSD": "99.95",
      "currency": "CAD"
    }
  }
}

Response

Example unifiedCompensationRequestResponse

correlationIdstring required

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

decisionReasonstring required

forterDecisionstring required

The message containing the decision

merchantPolicyIdstring required

UID of the custom policy created in Forter's Policies tool that resulted in this decision

recommendationsstring[] required

Forter's recommendations for the optimal way of proceeding with the compensation request

statusstring required

Status of the request processing

Example response

{
  "correlationId": "HGJ7512345H3DE",
  "forterDecision": "approve",
  "merchantPolicyId": "0ee8ba28a8654c659addbae9253b707c",
  "recommendations": [],
  "status": "success"
}

v1

Compensation request

Path parameters

Headers

Request body

Example request

Response

Example response