Verify chargeback risk | UPS API Documentation

curl -X POST https://wwwcie.ups.com/api/commerce-guard/v1/verify \
     -H "partnerId: PARTNER_001" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "userInformation": {
    "email": "alice.smith@example.com",
    "ipAddress": "192.168.1.101"
  },
  "billingContact": {
    "name": {
      "firstName": "Alice",
      "lastName": "Smith"
    },
    "phone": {
      "countryCode": "1",
      "number": "3125556789"
    },
    "address": {
      "addressLine": [
        "456 Elm Street",
        "Unit 12B"
      ],
      "city": "Chicago",
      "stateProvinceCode": "IL",
      "postalCode": "60616",
      "countryCode": "US"
    }
  },
  "shippingContact": {
    "name": {
      "firstName": "Alice",
      "lastName": "Smith"
    },
    "phone": {
      "countryCode": "1",
      "number": "3125556789"
    },
    "address": {
      "addressLine": [
        "456 Elm Street",
        "Unit 12B"
      ],
      "city": "Chicago",
      "stateProvinceCode": "IL",
      "postalCode": "60616",
      "countryCode": "US"
    }
  },
  "products": [
    {
      "sku": "ROD-ABC-123",
      "name": "Wireless Bluetooth Headphones"
    }
  ],
  "orderValue": 199.99,
  "currencyCode": "USD",
  "orderId": "ORDER1001",
  "orderCreatedAt": "2025-07-16T10:53:11.893Z",
  "paymentInformation": {
    "txnId": "TXN20250716001",
    "method": "card",
    "issuerIdNumber": 411111,
    "lastDigits": 4242,
    "issuer": "Visa"
  }
}'

{
  "superScore": 500,
  "decision": "review",
  "categoryScores": {
    "addressReliabilityScore": {
      "score": 520,
      "rank": "medium"
    },
    "digitalIdentityScore": {
      "score": 999,
      "rank": "high"
    },
    "proxyScore": {
      "score": 0,
      "rank": "no_risk"
    },
    "paymentReliabilityScore": {
      "score": 140,
      "rank": "low"
    }
  }
}

Evaluates chargeback risk based on user, payment, and address details. Returns scores and decision for risk classification.

Authentication

AuthorizationBearer

Find your Client ID and Secret on your app info page.

Select “Try It”
In the Security section enter your Client ID and Secret.
Select “Request Token”
Enter any additional information in the Body and Parameters sections.
Select “Send” to execute your API request

Path parameters

versionstringOptionalDefaults to v1

Denotes which version of the API to be called as new features are released.

Request

This endpoint expects an object.

userInformationobjectRequired

billingContactobjectRequired

Contact information structure used for billing and shipping

shippingContactobjectRequired

Contact information structure used for billing and shipping

productslist of objectsRequired

List of products in the order

orderValuedoubleRequired

Total order value

currencyCodestringRequiredformat: "^[A-Z]{3}$"=3 characters

The ISO 4217 currency

orderIdstringRequired1-64 characters

Unique order identifier

orderCreatedAtdatetimeRequired

The RFC 3339 date and time

paymentInformationobject or nullOptional

Payment details, nullable

Response headers

BkndTransIdstringOptional

The backend transaction id.

transIdstringOptional

An identifier unique to the request.

transactionSrcstringOptional

Identifies the client/source application that is calling.

Content-TypestringOptional

The Content-Type header provides the client with the actual content/media type of the returned content.

Response

Success

superScoredoubleOptional0-999

Overall risk score from 0 (lowest) to 999 (highest risk)

decisionenumOptional

Risk decision—whether to reject, review, or undecided

Allowed values:

categoryScoresobjectOptional

Detailed category risk scores

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

422

Unprocessable Entity Error

500

Internal Server Error