{ "openapi": "3.0.0", "info": { "version": "10.2", "title": "Forter API", "license": { "name": "Forter License" }, "description": "Forter helps brands grow their businesses with fraud and payments decisions, built on the world's most intelligent identity network — 1B+ identities, trillions of transactions, 300+ digital-first merchants including Nordstrom, ASOS, eBay, Priceline, Sephora, and Instacart.\n\nPagination: Forter REST endpoints return single-resource responses and do not paginate. List endpoints, when introduced, will follow the cursor convention documented at `x-pagination` and via the reusable `Cursor` / `Limit` parameters and `PaginationEnvelope` schema in `components`.\n\nBatch / bulk: Forter REST endpoints are single-event today and do not accept batched requests. Bulk endpoints, when introduced, will follow the envelope convention documented at `x-batch` and via the `BatchRequest` / `BatchResponse` / `BatchItemResult` schemas and the `BatchSize` parameter in `components`.\n\nError handling & retry: every 4xx / 5xx response returns the typed Error schema (`type`, `message`, `request_id`, `retry_hint`). Rate-limit headers per RFC 9598 (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`) are emitted on every response; honor `Retry-After` on `429`. Recommended client behavior: ~2 s timeout, exponential backoff (250 ms / 500 ms / 1 s / 2 s) capped at `Retry-After`. Per-status retry guidance and the canonical error/recovery convention are documented at `x-error-recovery` (root extension).", "summary": "Forter helps brands grow their businesses with fraud and payments decisions, built on the world's most intelligent identity network." }, "servers": [ { "url": "https://api.forter-secure.com/" } ], "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } }, "schemas": { "AccountOwner": { "additionalProperties": false, "description": "Basic account data such as name, account ID, email, and aggregated past purchases", "properties": { "accountId": { "description": "Customer's account UID in merchant's site (leave empty if guest)", "maxLength": 100, "type": "string", "x-conditional": true, "example": "e520-ba9a-367-60b", "nullable": true }, "birthdate": { "description": "Date of birth. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "1987-05-22", "nullable": true }, "created": { "description": "Account creation date in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "x-conditional": true, "example": 1415273168, "nullable": true }, "email": { "description": "Account holder's primary Email address", "maxLength": 256, "type": "string", "example": "john_s@test.com" }, "firstName": { "description": "Account holder's first name", "maxLength": 75, "type": "string", "example": "John" }, "fullName": { "description": "Account holder's fullName", "maxLength": 150, "type": "string", "example": "Smith", "nullable": true }, "gender": { "description": "Gender", "enum": [ "MALE", "FEMALE", "CHOSE_NOT_TO_SPECIFY", "NONE" ], "example": "MALE", "nullable": true }, "lastName": { "description": "Account holder's last name", "maxLength": 75, "type": "string", "example": "Smith" }, "loyaltyProgramsInAccount": { "description": "Details of all rewards/loyalty/frequent flyer programs customer saved in the account", "items": { "$ref": "#/components/schemas/LoyaltyProgram" }, "type": "array", "nullable": true }, "socialNetworkData": { "description": "Social network data", "items": { "$ref": "#/components/schemas/SocialNetwork" }, "type": "array", "nullable": true } }, "required": [ "firstName", "lastName", "email" ], "type": "object" }, "AcquirerData": { "additionalProperties": false, "description": "This provides information about the Acquirer of the transaction", "properties": { "acquirerBIN": { "description": "Bank acquirer BIN (Bank Identification Number)", "maxLength": 12, "type": "string", "x-conditional": true, "example": "457173", "nullable": true }, "acquirerCountry": { "description": "Acquirer country", "enum": [ "AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CK", "CR", "HR", "CU", "CY", "CZ", "DK", "DJ", "DM", "DO", "TP", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "CI", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "AN", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "KP", "GB", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "SH", "KN", "LC", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TJ", "TZ", "TH", "CD", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "YU", "ZM", "ZW" ], "example": "US", "nullable": true }, "acquirerMerchantId": { "description": "Merchant ID (MID) - merchant ID is a unique code provided to merchants by their payment processor", "maxLength": 30, "type": "string", "x-conditional": true, "example": "5245020244654", "nullable": true }, "acquirerMerchantName": { "description": "Merchant Name as appearing in processor records", "maxLength": 100, "type": "string", "example": "Simple T-shirt", "nullable": true }, "acquirerName": { "description": "Bank acquirer Name", "maxLength": 50, "type": "string", "example": "Barclays", "nullable": true }, "merchantCategoryCode": { "description": "A Merchant Category Code (MCC) is a four-digit number listed in ISO 18245 for retail financial services. MCC is used to classify the business by the type of goods or services it provides.", "maxLength": 4, "type": "number", "x-conditional": true, "example": 5655, "nullable": true }, "merchantCountryCode": { "description": "Merchant country code is a three-digit number listed in ISO 3166‑1 (zero‑padded)", "maxLength": 3, "type": "number", "x-conditional": true, "example": 840, "nullable": true } }, "type": "object" }, "AdditionalAccountEventIdentifiers": { "additionalProperties": false, "description": "Additional identifiers of the account event", "properties": {}, "type": "object" }, "AdditionalVerificationDocuments": { "additionalProperties": false, "description": "Additional Verification Documents includes any details gained from identifying documents or materials which the customer has shared.", "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address", "description": "Address details" }, { "type": "object", "nullable": true } ] }, "documentDateOfBirth": { "description": "Date of birth as appears on the document. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "1991-01-09", "nullable": true }, "documentExpiration": { "description": "Document's exipration date. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "2017-01-15", "nullable": true }, "documentFirstName": { "description": "First name as appears on the document", "maxLength": 50, "type": "string", "example": "John", "nullable": true }, "documentIssuingState": { "description": "Document issuing state or region", "maxLength": 25, "type": "string", "x-conditional": true, "example": "NY", "nullable": true }, "documentLastName": { "description": "Last name as appears on the document", "maxLength": 50, "type": "string", "example": "Smith", "nullable": true }, "documentNumber": { "description": "Official document's number (e.g. passport number, driving license number, etc.)", "maxLength": 50, "type": "string", "x-conditional": true, "example": "20439190", "nullable": true }, "documentSource": { "description": "Source of document (e.g. uploaded file, captured by camera, typed in by customer, etc.)", "enum": [ "CAMERA_CAPTURED", "UPLOADED_FILE", "TYPED", "OTHER" ], "example": "UPLOADED_FILE" }, "documentStatus": { "description": "Status of verification document (e.g. sent to customer, received by customer, abandoned by customer ).", "enum": [ "SENT_TO_CLIENT", "RECEIVED_FROM_CLIENT", "ABANDONED_BY_CLIENT", "RECEIVED_FROM_CLIENT_FAULTY" ], "maxLength": 50, "example": "SENT_TO_CLIENT", "nullable": true }, "documentType": { "description": "Type of document (Passport, ID, Driving license)", "maxLength": 35, "type": "string", "example": "Passport" }, "documentVerificationServiceAnswer": { "description": "Answer received from 3rd party document verification services", "maxLength": 20, "type": "string", "example": "APPROVED", "nullable": true }, "documentVerificationServiceName": { "description": "Name of 3rd party document verifcation service", "maxLength": 50, "type": "string", "example": "IDVerification.com", "nullable": true }, "documentVerificationServiceResponsePayload": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Response payload received from 3rd party document verification service" }, { "type": "object", "nullable": true } ] }, "documentVerified": { "description": "True if document was verified as authentic by merchant or 3rd party service", "type": "boolean", "example": true, "nullable": true }, "eventTime": { "description": "Time of event in seconds since unix epoch (UTC, Jan 1, 1970). For example, 01/01/2015 00:00 is 1420070400", "type": "number", "example": 1420070400, "nullable": true }, "nationality": { "description": "Document holder's nationality", "maxLength": 25, "type": "string", "x-conditional": true, "example": "US", "nullable": true } }, "required": [ "documentType", "documentSource" ], "type": "object" }, "Address": { "additionalProperties": false, "description": "Address description", "properties": { "address1": { "description": "Street-level address. Required when full address details are available", "maxLength": 255, "type": "string", "x-conditional": true, "example": "235 Montgomery st.", "nullable": true }, "address2": { "description": "Unit-level address", "maxLength": 255, "type": "string", "x-conditional": true, "example": "Ste. 1110", "nullable": true }, "city": { "description": "City. Required when full address details are available", "maxLength": 200, "type": "string", "example": "San Francisco", "nullable": true }, "company": { "description": "Company", "maxLength": 225, "type": "string", "example": "Generic Corp. ltd.", "nullable": true }, "country": { "description": "Country, two-letter ISO 3166-1 alpha-2 country code", "maxLength": 2, "minLength": 2, "type": "string", "example": "US" }, "region": { "description": "Top-level administrative subdivision - state/province/department/etc. Can be either abbreviated format or full name (NY/New York)", "maxLength": 200, "type": "string", "x-conditional": true, "example": "CA", "nullable": true }, "savedData": { "allOf": [ { "$ref": "#/components/schemas/SavedData", "description": "Indications for use of saved account data" }, { "type": "object", "nullable": true } ] }, "zip": { "description": "Zipcode", "maxLength": 20, "type": "string", "x-conditional": true, "example": "94104", "nullable": true } }, "required": [ "country" ], "type": "object" }, "Amount": { "additionalProperties": false, "description": "A monetary amount in USD or local currenncy.", "properties": { "amountLocalCurrency": { "description": "Transaction amount in currency chosen by the buyer", "maxLength": 20, "type": "string", "example": "105.55", "nullable": true }, "amountUSD": { "description": "Transaction amount in USD", "maxLength": 12, "type": "string", "x-conditional": true, "example": "99.95", "nullable": true }, "currency": { "description": "Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code", "maxLength": 3, "pattern": "[A-Z]{3}", "type": "string", "example": "CAD", "nullable": true } }, "type": "object" }, "BankTransfer": { "additionalProperties": false, "description": "This object contains information regarding bank transfer payment methods.", "properties": { "accountHolderFirstName": { "description": "Bank account holder first name", "maxLength": 50, "type": "string", "example": "John", "nullable": true }, "accountHolderLastName": { "description": "Bank account holder last name", "maxLength": 50, "type": "string", "example": "Smith", "nullable": true }, "achProcessingType": { "description": "Type of ACH processing used in the transaction", "maxLength": 50, "type": "string", "example": "SAME_DAY_ACH", "nullable": true }, "bankAccountIdentifier": { "description": "Bank account unique identifier (IBAN or equivalent)", "maxLength": 40, "type": "string", "example": "TEST63TEST1212121212" }, "bankAccountType": { "description": "Type of bank account payment is made from (e.g. savings/checking, etc.)", "maxLength": 50, "type": "string", "example": "Savings", "nullable": true }, "bankName": { "description": "Name of bank payment is made from", "maxLength": 50, "type": "string", "example": "Citigroup", "nullable": true }, "paymentGatewayData": { "allOf": [ { "$ref": "#/components/schemas/PaymentGatewayData", "description": "Payment gateway data" }, { "type": "object", "nullable": true } ] }, "paymentSuccessStatus": { "description": "Response text as received from the service provider", "type": "string", "example": "Payment Successful", "nullable": true }, "serviceName": { "description": "Payment method name", "maxLength": 30, "type": "string", "x-conditional": true, "example": "Direct Debit", "nullable": true } }, "required": [ "bankAccountIdentifier" ], "type": "object" }, "ConnectionInformation": { "additionalProperties": false, "description": "This object contains connection info which is usually found in the HTTP request header.", "properties": { "checkoutToolsSessionId": { "description": "CheckoutToolsSessionId received from the SDK", "maxLength": 128, "type": "string", "example": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd", "nullable": true }, "customerIP": { "description": "Customer IP address in IPv4 or IPv6 format. If missing should be populated with 127.0.0.1", "type": "string", "example": "10.0.0.127" }, "forterMobileUID": { "description": "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)", "maxLength": 1024, "type": "string", "example": "6429751237891", "nullable": true }, "forterTokenCookie": { "description": "Forter token cookie from request headers", "maxLength": 1024, "type": "string", "x-conditional": true, "example": "249453te8tbf9355186fet0ken547b95_2786972955236__UDE52-n5_8dg", "nullable": true }, "merchantDeviceIdentifier": { "description": "A unique device identifier generated by merchant", "maxLength": 100, "type": "string", "x-conditional": true, "example": "HGJ7512345H3", "nullable": true }, "merchantProvidedSessionId": { "description": "An identifier of the merchant session", "maxLength": 128, "type": "string", "example": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd", "nullable": true }, "userAgent": { "description": "Customer's User agent", "maxLength": 4096, "type": "string", "example": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36" } }, "required": [ "customerIP", "userAgent" ], "type": "object" }, "CreditCard": { "additionalProperties": false, "description": "This provides details relating to the credit card used.", "properties": { "bin": { "description": "Credit card's BIN (Bank Identification Number)", "maxLength": 8, "pattern": "[0-9]{6,8}", "type": "string", "example": "42424242" }, "cardBank": { "description": "Credit card's issuing bank", "maxLength": 128, "type": "string", "example": "Chase", "nullable": true }, "cardBrand": { "description": "Credit Card's issuer brand", "maxLength": 30, "type": "string", "example": "VISA", "nullable": true }, "cardType": { "description": "Payment card type", "enum": [ "CREDIT", "DEBIT", "PREPAID", "UNKNOWN" ], "x-conditional": true, "example": "CREDIT", "nullable": true }, "countryOfIssuance": { "description": "Credit card's issuing country, two-letter ISO 3166-1 alpha-2 country code", "maxLength": 2, "pattern": "[A-Za-z]{2}", "type": "string", "x-conditional": true, "example": "US", "nullable": true }, "creditCardCorrelationId": { "description": "Credit card - CorrelationId that was recieved by the init 3DS API", "type": "string", "nullable": true }, "expirationMonth": { "description": "Credit card's expiration month, in MM format", "maxLength": 2, "pattern": "[0-9]{2}", "type": "string", "example": "03" }, "expirationYear": { "description": "Credit card's expiration year, in YYYY format", "maxLength": 4, "pattern": "[0-9]{4}", "type": "string", "example": "2018" }, "fingerprint": { "description": "Unique identifier for card (sent by gateway or processor)", "maxLength": 128, "type": "string", "x-conditional": true, "example": "Xt5EWLLDS7FJjR1c", "nullable": true }, "fullCreditCard": { "description": "Credit Card's full PAN - needed for the 3DS secure implementation", "maxLength": 30, "type": "string", "example": "2424242424242424", "nullable": true }, "fullResponsePayload": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Full processor or gateway response object" }, { "type": "object", "nullable": true } ] }, "lastFourDigits": { "description": "Credit card's last 4 digits (For Amex, take 4 digits from last digit)", "maxLength": 4, "pattern": "[0-9]{2,4}", "type": "string", "example": "4242" }, "nameOnCard": { "description": "Cardholder's full name", "maxLength": 75, "type": "string", "example": "John R. H. Smith" }, "paymentGatewayData": { "allOf": [ { "$ref": "#/components/schemas/PaymentGatewayData", "description": "Payment gateway data" }, { "type": "object", "nullable": true } ] }, "paymentProcessorData": { "allOf": [ { "$ref": "#/components/schemas/PaymentProcessorData", "description": "Payment processor data" }, { "type": "object", "nullable": true } ] }, "threeDSecure": { "allOf": [ { "$ref": "#/components/schemas/ThreeDSecureInput" }, { "type": "object", "nullable": true } ] }, "verificationResults": { "$ref": "#/components/schemas/CreditCardVerification", "description": "Credit card verification data" } }, "required": [ "nameOnCard", "bin", "lastFourDigits", "expirationMonth", "expirationYear", "verificationResults" ], "type": "object" }, "CreditCardVerification": { "additionalProperties": false, "description": "Credit card CVV and AVS results", "properties": { "authorizationCode": { "description": "Card authorization code from payment gateway. Required if both processorResponseText and processorResponseCode are not provided.", "maxLength": 255, "type": "string", "x-conditional": true, "example": "A33244", "nullable": true }, "authorizationProcessedWith3DS": { "description": "3DSecure - indicating that the 3DS results were sent to processor and have been used during the authorization", "type": "boolean", "example": true, "nullable": true }, "avsFullResult": { "description": "Procesor response code for AVS. Only required in cases where all AVS results (zipcode, street address, and name when available) arrive as one string", "maxLength": 50, "type": "string", "x-conditional": true, "example": "Y", "nullable": true }, "avsNameResult": { "description": "Name portion of card's AVS result (when available)", "maxLength": 30, "type": "string", "x-conditional": true, "example": "M", "nullable": true }, "avsStreetResult": { "description": "Street address portion of card's AVS result", "maxLength": 30, "type": "string", "x-conditional": true, "example": "N", "nullable": true }, "avsZipResult": { "description": "Zipcode portion of card's AVS result", "maxLength": 30, "type": "string", "x-conditional": true, "example": "M", "nullable": true }, "cavvResult": { "description": "3DSecure - Authentication Value (CAVV / AAV for 3DS1) recieved from authorization/Authentication response", "maxLength": 50, "type": "string", "x-conditional": true, "example": "VYboNwcsB3F9gTIsbaUjvEuLW0o=", "nullable": true }, "cvvResult": { "description": "CVV result (if no data please send the value U)", "maxLength": 30, "type": "string", "x-conditional": true, "example": "M", "nullable": true }, "eciValue": { "description": "3DSecure - ECI value recieved from authorization/authentication response", "maxLength": 2, "type": "string", "x-conditional": true, "example": "05", "nullable": true }, "exemptionStatus": { "description": "Exemption status as received from the processor", "maxLength": 100, "type": "string", "example": "accepted", "nullable": true }, "external3dsVendorPayload": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "3DSecure - Raw response received from the 3D Secure provider" }, { "type": "object", "nullable": true } ] }, "issuerResponseCode": { "description": "Response code received from issuer", "maxLength": 50, "type": "string", "x-conditional": true, "example": "D23", "nullable": true }, "issuerResponseText": { "description": "Response text received from issuer", "maxLength": 1024, "type": "string", "x-conditional": true, "example": "Stolen card", "nullable": true }, "liabilityShift": { "description": "3DSecure - liability shift - indicate whether the chargeback liability shifted to the card issuer", "type": "boolean", "x-conditional": true, "example": true, "nullable": true }, "partyExecuted3DS": { "description": "3DSecure - Party executed the 3DS authentication", "enum": [ "PSP", "FORTER", "BOTH" ], "example": "PSP", "nullable": true }, "processorResponseCode": { "description": "Response code received from processor. Required if both processorResponseText and authorizationCode are not provided.", "maxLength": 50, "type": "string", "x-conditional": true, "example": "D23", "nullable": true }, "processorResponseText": { "description": "Response text received from processor. Required if both processorResponseCode and authorizationCode are not provided.", "maxLength": 255, "type": "string", "x-conditional": true, "example": "Stolen card", "nullable": true }, "threeDsInteractionMode": { "description": "3DSecure - Indication of the friction that the user experienced", "enum": [ "FRICTIONLESS", "CHALLENGED" ], "example": "FRICTIONLESS", "nullable": true }, "threeDsStatus": { "description": "3DSecure - Status text received from 3D secure vendor", "maxLength": 100, "type": "string", "x-conditional": true, "example": "Cardholder authenticated", "nullable": true }, "threeDsVersion": { "description": "3DSecure - Version used in the transaction", "maxLength": 5, "type": "string", "x-conditional": true, "example": "2.1.0", "nullable": true } }, "type": "object" }, "CreditLineDetails": { "additionalProperties": false, "description": "Details of credit line.", "properties": { "askedToIncreaseCreditLineLimit": { "description": "True if customer asked to increase credit line limit", "type": "boolean", "example": false, "nullable": true }, "creditLineLimitIncreaseMethod": { "description": "Method customer chose to ask to increase credit line limit - PRE_APPROVAL, AT_PURCHASE", "enum": [ "PRE_APPROVAL", "AT_PURCHASE" ], "example": "AT_PURCHASE", "nullable": true }, "currentCreditLineLimit": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Current limit that was set for the credit line" }, { "type": "object", "nullable": true } ] }, "originalCreditLineLimit": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Original limit that was set for the credit line" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "CreditUsed": { "additionalProperties": false, "description": "Information about various types of credits used to finance a transaction", "properties": { "activationTime": { "description": "Time credit/gift card was activated in the account, in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1448549922, "nullable": true }, "creditCurrency": { "description": "Original transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code", "maxLength": 3, "pattern": "[A-Z]{3}", "type": "string", "x-conditional": true, "example": "CAD", "nullable": true }, "creditOrigin": { "description": "Source which created gift card for customer.", "type": "string", "example": "CS Compensation", "nullable": true }, "merchantPaymentId": { "description": "unique payment identifier for the merchant reference.", "maxLength": 150, "type": "string", "example": "eab12-ba9a-367-60b", "nullable": true }, "value": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Monetary value of credits used" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "CryptoWallet": { "additionalProperties": false, "description": "This provides information about the digital crypto wallet associated with the resipient or transaction.", "properties": { "cryptoWalletName": { "description": "Crypto wallet name", "maxLength": 30, "type": "string", "example": "CryptoWallet", "nullable": true }, "cryptoWalletPaymentId": { "description": "Crypto wallet payment ID", "maxLength": 50, "type": "string", "example": "3JQiwG88SQvwihDAHg9M2EnqEisharz49c", "nullable": true }, "cryptoWalletType": { "description": "Crypto wallet type (Indicate whether wallet provider is internal to the site ecosystem)", "enum": [ "INTERNAL", "EXTERNAL" ], "example": "EXTERNAL" } }, "required": [ "cryptoWalletType" ], "type": "object" }, "DigitalWallet": { "additionalProperties": false, "description": "This provides information about the digital wallet account associated with the customer or transaction.", "properties": { "digitalWalletName": { "description": "Digital wallet name", "enum": [ "AMAZONPAY", "FACEBOOKPAY", "ALIPAY", "WECHAT", "AMEDIGITAL", "MERCADOPAGO", "DUE", "ZELLE", "PAYONEER", "ALLIEDWALLET", "KONBINI", "UNIONPAY", "IYZICO", "VENMO", "BARTER", "PAYNOW", "PAYCO", "KAKAOPAY", "NAVERPAY", "LINEPAY", "BANCONTACT", "MBWAY", "AIIA", "BLIK", "EPS", "OVO", "DANA", "GCASH", "GOPAY", "RAKUTENPAY", "APLAZO", "GRABPAY", "TWINT", "TRUEMONEY", "SWISH", "KLARNA", "SHOPBACK", "OTHER", "PAYPAY", "TRUSTLY", "PIX", "PAYCONIQ", "QRIS" ], "example": "ALIPAY" }, "digitalWalletPayerEmail": { "description": "Email address associated with the digital wallet account", "maxLength": 75, "type": "string", "x-conditional": true, "example": "john_s@test.com", "nullable": true }, "digitalWalletPayerId": { "description": "Unique identifier for each digital wallet account. This ID should persist across all orders made by the same user, regardless of underlying payment methods.", "maxLength": 154, "type": "string", "x-conditional": true, "example": "FD000A45P", "nullable": true }, "digitalWalletpaymentId": { "description": "Digital wallet payment ID", "maxLength": 50, "type": "string", "example": "PAY-0MB00000KR8073311KZSDEYA", "nullable": true }, "freeTextDigitalWalletName": { "description": "Specifics about the source of the wallet such as the name / 3rd party name, etc. (required for OTHER digitalWalletName)", "type": "string", "x-conditional": true, "example": "ALIBABA", "nullable": true }, "fullDigitalWalletResponsePayload": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Full digital wallet response object" }, { "type": "object", "nullable": true } ] }, "payerAccountCountry": { "description": "Digital wallet account country, two-letter ISO 3166-1 alpha-2 country code", "maxLength": 2, "minLength": 2, "type": "string", "x-conditional": true, "example": "US", "nullable": true }, "paymentSuccessStatus": { "description": "Digital wallet payment status", "maxLength": 50, "type": "string", "x-conditional": true, "example": "COMPLETED", "nullable": true }, "underlyingPaymentMethod": { "$ref": "#/components/schemas/UnderlyingPaymentMethod", "description": "The underlying payment method associated to the digital wallet that was used in the current transaction" } }, "required": [ "digitalWalletName", "underlyingPaymentMethod" ], "type": "object" }, "Email": { "additionalProperties": false, "description": "This refers to the email address associated with the customer or transaction, giving details about the address and any role it has played in the customer's being on or interacting with the site.", "properties": { "email": { "description": "Email address", "maxLength": 256, "type": "string", "example": "john_s@test.com" }, "emailVerification": { "allOf": [ { "$ref": "#/components/schemas/Verification", "description": "True if customer received email verification message to this address and clicked-through back to merchant's site" }, { "type": "object", "nullable": true } ] } }, "required": [ "email" ], "type": "object" }, "EmploymentInformation": { "additionalProperties": false, "description": "Employment information", "properties": { "employerAddress": { "allOf": [ { "$ref": "#/components/schemas/Address", "description": "Employing company's address" }, { "type": "object", "nullable": true } ] }, "employerCompanySizeRange": { "description": "Employing company's number of employees", "maxLength": 30, "type": "string", "example": "20", "nullable": true }, "employerIndustry": { "description": "Employing company's industry", "maxLength": 100, "type": "string", "example": "Retail", "nullable": true }, "employerName": { "description": "Employing company's name", "maxLength": 100, "type": "string", "example": "Forter", "nullable": true }, "employerPhone": { "description": "Employing company's phone", "maxLength": 30, "type": "string", "example": "+12126667777", "nullable": true }, "income": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Gross annual income" }, { "type": "object", "nullable": true } ] }, "jobTitle": { "description": "Job title", "maxLength": 50, "type": "string", "example": "Fraud Analyst", "nullable": true } }, "type": "object" }, "GeneralPayloadMap": { "additionalProperties": true, "description": "General payload object", "properties": {}, "type": "object" }, "InstallmentService": { "additionalProperties": false, "description": "This provides details relating to the credit card used.", "properties": { "firstName": { "description": "Account holder's first name", "maxLength": 75, "type": "string", "example": "John", "nullable": true }, "fullResponsePayload": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Full installment service response object" }, { "type": "object", "nullable": true } ] }, "lastName": { "description": "Account holder's last name", "maxLength": 75, "type": "string", "example": "Smith", "nullable": true }, "paymentId": { "description": "Installment payment ID", "maxLength": 50, "type": "string", "example": "YTZ8IATEGAWRRVVG", "nullable": true }, "serviceName": { "description": "Installment service's name", "maxLength": 30, "type": "string", "x-conditional": true, "example": "Affirm", "nullable": true }, "serviceResponseCode": { "description": "Response code received from installment service", "maxLength": 50, "type": "string", "example": "200", "nullable": true } }, "type": "object" }, "LoyaltyPoints": { "additionalProperties": false, "description": "Loyalty Points information is relevant when customers have entered some kind of loyalty program and are receiving points or other related value as a result", "properties": { "loyaltyPointsCount": { "description": "Number of points (miles, stars, etc.)", "type": "number", "example": 1506, "nullable": true }, "loyaltyPointsSource": { "description": "Source of points (promo, referral, etc.)", "enum": [ "REFERRAL", "IN_ACCOUNT_PURCHASES", "PROMOTION", "COMPENSATION", "CARD_SCHEME_POINTS" ], "x-conditional": true, "example": "IN_ACCOUNT_PURCHASES", "nullable": true }, "loyaltyPointsValue": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Monetary value of points (miles, stars, etc.)" }, { "type": "object", "nullable": true } ] }, "merchantPaymentId": { "description": "unique payment identifier for the merchant reference.", "maxLength": 150, "type": "string", "example": "eab12-ba9a-367-60b", "nullable": true } }, "type": "object" }, "LoyaltyProgram": { "additionalProperties": false, "description": "Details of rewards/loyalty programs user is member of", "properties": { "accountNumber": { "description": "Customer's rewards/loyalty/frequent flyer account number", "maxLength": 100, "type": "string", "example": "VC1568OP", "nullable": true }, "loyaltyPointsValue": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Monetary value of points (miles, stars, etc.)" }, { "type": "object", "nullable": true } ] }, "programName": { "description": "Name of program", "maxLength": 100, "type": "string", "x-conditional": true, "example": "StarAlliance", "nullable": true }, "programPoints": { "description": "Customer's rewards/loyalty/frequent flyer miles/point/stars", "maxLength": 20, "type": "number", "example": 0, "nullable": true }, "tier": { "description": "Program tier name", "maxLength": 100, "type": "string", "x-conditional": true, "example": "Blue", "nullable": true } }, "type": "object" }, "MerchantIdentifiers": { "additionalProperties": false, "description": "If a merchant operates a number of sites, Merchant Identifiers help Forter's system to identify the right transactions with the right sites.", "properties": { "merchantDomain": { "description": "Use if merchant operates several sites (such as a regular site and a related discount brand)", "maxLength": 2048, "type": "string", "example": "HandbagsExpressDiscounts.com", "nullable": true }, "merchantName": { "description": "Use if merchant operates several sites (such as a regular site and a related discount brand)", "maxLength": 50, "type": "string", "example": "Handbags Express Discounts", "nullable": true } }, "type": "object" }, "MerchantInitiatedPayment": { "additionalProperties": false, "description": "Details about merchant initiated payment", "properties": { "initialOrderId": { "description": "Unique order/transaction identifier of the initial order (CIT).", "maxLength": 40, "type": "string", "example": "2356fdse0rr489", "nullable": true }, "type": { "description": "Specifies the type of merchant-initiated payment", "enum": [ "RECURRING_TRANSACTION", "INSTALMENT_TRANSACTION", "ADD_CARD", "MAINTAIN_CARD_INFORMATION", "ACCOUNT_VERIFICATION", "SPLIT_OR_DELAYED_SHIPMENT", "TOP_UP", "MAIL_ORDER", "TELEPHONE_ORDER", "WHITELIST_STATUS_CHECK", "OTHER_PAYMENT" ], "nullable": true } }, "type": "object" }, "MobileMoney": { "additionalProperties": false, "description": "This provides information about the mobile money account associated with the customer or transaction.", "properties": { "fullResponsePayload": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Payload as received from the service provider" }, { "type": "object", "nullable": true } ] }, "mobileMoneyNetwork": { "description": "Mobile money provider name", "enum": [ "MPESA", "MTN", "MPAWA", "MSHWAEI", "SAFARICOM", "DASH" ], "example": "MPESA" }, "paymentAcquirerData": { "allOf": [ { "$ref": "#/components/schemas/AcquirerData", "description": "Payment acquirer data" }, { "type": "object", "nullable": true } ] }, "paymentGatewayData": { "allOf": [ { "$ref": "#/components/schemas/PaymentGatewayData", "description": "Payment gateway data" }, { "type": "object", "nullable": true } ] }, "paymentSuccessStatus": { "description": "Mobile money payment status", "maxLength": 50, "type": "string", "example": "success" }, "phoneNumber": { "description": "Account phone number", "maxLength": 50, "type": "string", "example": "15557654321" } }, "required": [ "mobileMoneyNetwork", "phoneNumber", "paymentSuccessStatus" ], "type": "object" }, "Payment": { "additionalProperties": false, "description": "This object reflects the different details associated with a single method of payment chosen by the customer. A single payment method object is required. Multiple payment methods in a single transaction should be represented by different instances of this object.", "properties": { "allowedMerchantInitiatedTransactions": { "description": "True if customer chose to allow future transactions to initiate without taking further action (payment that's initiated on behalf of a customer)", "type": "boolean", "example": false, "nullable": true }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Amount paid with this payment instrument" }, { "type": "object", "nullable": true } ] }, "androidPay": { "allOf": [ { "$ref": "#/components/schemas/TokenizedCreditCard", "description": "AndroidPay details" }, { "type": "object", "nullable": true } ] }, "applePay": { "allOf": [ { "$ref": "#/components/schemas/TokenizedCreditCard", "description": "ApplePay details" }, { "type": "object", "nullable": true } ] }, "bankTransfer": { "allOf": [ { "$ref": "#/components/schemas/BankTransfer", "description": "Bank transfer used to pay for purchase (incl. Sofort, iDEAL, ACH, SEPA Direct Debit, etc.)" }, { "type": "object", "nullable": true } ] }, "billingDetails": { "$ref": "#/components/schemas/Person", "description": "Billing details associated with this payment method" }, "cameraCaptured": { "description": "True if payment instrument details were captured by OCR from a picture. False if payment instrument details were manually typed in", "type": "boolean", "example": true, "nullable": true }, "cash": { "description": "Payed with cash", "type": "boolean", "example": false, "nullable": true }, "creditCard": { "allOf": [ { "$ref": "#/components/schemas/CreditCard", "description": "Credit card details" }, { "type": "object", "nullable": true } ] }, "creditLineDetails": { "allOf": [ { "$ref": "#/components/schemas/CreditLineDetails", "description": "Details of credit line" }, { "type": "object", "nullable": true } ] }, "cryptoWallet": { "allOf": [ { "$ref": "#/components/schemas/CryptoWallet", "description": "Crypto wallet account details" }, { "type": "object", "nullable": true } ] }, "digitalWallet": { "allOf": [ { "$ref": "#/components/schemas/DigitalWallet", "description": "Digital wallet account details" }, { "type": "object", "nullable": true } ] }, "giftCard": { "allOf": [ { "$ref": "#/components/schemas/CreditUsed", "description": "Gift card credit used to pay for purchase" }, { "type": "object", "nullable": true } ] }, "installmentService": { "allOf": [ { "$ref": "#/components/schemas/InstallmentService", "description": "Installment service details" }, { "type": "object", "nullable": true } ] }, "loyaltyPoints": { "allOf": [ { "$ref": "#/components/schemas/LoyaltyPoints", "description": "Loyalty points used to pay for purchase" }, { "type": "object", "nullable": true } ] }, "merchantInitiated": { "allOf": [ { "$ref": "#/components/schemas/MerchantInitiatedPayment", "description": "Details about merchant initiated payment" }, { "type": "object", "nullable": true } ] }, "mobileMoney": { "allOf": [ { "$ref": "#/components/schemas/MobileMoney", "description": "Mobile payment details (Mpesa, MTN, etc.)" }, { "type": "object", "nullable": true } ] }, "numberOfInstallments": { "description": "Number of payments if customer chose to pay in several installments", "type": "integer", "x-conditional": true, "example": 12, "nullable": true }, "paymentMethodNickname": { "description": "Nickname assigned to this payment method by the user", "type": "string", "x-conditional": true, "example": "My Work Card", "nullable": true }, "paypal": { "allOf": [ { "$ref": "#/components/schemas/Paypal", "description": "PayPal account details" }, { "type": "object", "nullable": true } ] }, "recurringPayment": { "allOf": [ { "$ref": "#/components/schemas/RecurringPaymentDetails", "description": "Information about the payment structure in case part of recurring payment" }, { "type": "object", "nullable": true } ] }, "samsungPay": { "allOf": [ { "$ref": "#/components/schemas/TokenizedCreditCard", "description": "SamsungPay details" }, { "type": "object", "nullable": true } ] }, "savedData": { "allOf": [ { "$ref": "#/components/schemas/SavedData", "description": "Indications for use of saved account data" }, { "type": "object", "nullable": true } ] }, "storeCreditUsed": { "allOf": [ { "$ref": "#/components/schemas/CreditUsed", "description": "Store credit used to pay for purchase" }, { "type": "object", "nullable": true } ] }, "tokenizedCard": { "allOf": [ { "$ref": "#/components/schemas/TokenizedCreditCard", "description": "Tokenized card details" }, { "type": "object", "nullable": true } ] }, "venmo": { "allOf": [ { "$ref": "#/components/schemas/Venmo", "description": "Venmo details" }, { "type": "object", "nullable": true } ] } }, "required": [ "billingDetails" ], "type": "object" }, "PaymentGatewayData": { "additionalProperties": false, "description": "This provides information about the payment gateway", "properties": { "gatewayName": { "description": "Payment gateway name", "maxLength": 50, "type": "string", "x-conditional": true, "example": "Braintree", "nullable": true }, "gatewayTransactionId": { "description": "Unique transaction identifier (sent by gateway)", "maxLength": 50, "type": "string", "x-conditional": true, "example": "fjdsS46sdklFd20", "nullable": true } }, "type": "object" }, "PaymentProcessorData": { "additionalProperties": false, "description": "This provides information about the payment processor", "properties": { "processorName": { "description": "Payment processor name", "maxLength": 50, "type": "string", "x-conditional": true, "example": "Chase Paymentech", "nullable": true }, "processorTransactionId": { "description": "Unique transaction identifier (sent by processor)", "maxLength": 50, "type": "string", "x-conditional": true, "example": "fjdsS46sdklFd20", "nullable": true } }, "type": "object" }, "Paypal": { "additionalProperties": false, "properties": { "authorizationId": { "description": "PayPal authorization ID", "maxLength": 50, "type": "string", "x-conditional": true, "example": "2WC75407LV7300439", "nullable": true }, "fullPaypalResponsePayload": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Full PayPal response object" }, { "type": "object", "nullable": true } ] }, "payerAccountCountry": { "description": "PayPal account country, two-letter ISO 3166-1 alpha-2 country code", "maxLength": 2, "minLength": 2, "type": "string", "x-conditional": true, "example": "US", "nullable": true }, "payerAddressStatus": { "description": "PayPal payer address status", "type": "string", "x-conditional": true, "example": "CONFIRMED", "nullable": true }, "payerEmail": { "description": "PayPal payer Email address", "maxLength": 256, "type": "string", "example": "john_s@test.com" }, "payerId": { "description": "PayPal payer ID", "maxLength": 154, "type": "string", "example": "FD000A45P" }, "payerStatus": { "description": "PayPal payer status", "type": "string", "x-conditional": true, "example": "VERIFIED", "nullable": true }, "paymentGatewayData": { "allOf": [ { "$ref": "#/components/schemas/PaymentGatewayData", "description": "Payment gateway data" }, { "type": "object", "nullable": true } ] }, "paymentId": { "description": "PayPal payment ID", "maxLength": 50, "type": "string", "x-conditional": true, "example": "PAY-0MB00000KR8073311KZSDEYA", "nullable": true }, "paymentStatus": { "description": "PayPal payment status", "maxLength": 50, "type": "string", "example": "COMPLETED" }, "protectionEligibility": { "description": "PayPal protection eligibility", "type": "string", "x-conditional": true, "example": "ELIGIBLE", "nullable": true } }, "required": [ "payerId", "payerEmail", "paymentStatus" ], "type": "object" }, "Person": { "additionalProperties": false, "description": "This object combines a number of pieces of data which contribute to building up an understanding of the person as an individual, both online and offline.", "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address", "description": "Address details", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "allAdditionalVerificationDocuments": { "description": "Additional identification documents details and verification", "items": { "$ref": "#/components/schemas/AdditionalVerificationDocuments" }, "type": "array", "nullable": true }, "employmentInformation": { "description": "Credit applicant's employment information", "items": { "$ref": "#/components/schemas/EmploymentInformation" }, "type": "array", "nullable": true }, "personalDetails": { "$ref": "#/components/schemas/PersonalDetails", "description": "Personal information such as name and birthdate" }, "phone": { "description": "Phone details", "items": { "$ref": "#/components/schemas/Phone" }, "type": "array", "x-conditional": true, "nullable": true } }, "required": [ "personalDetails" ], "type": "object" }, "PersonalDetails": { "additionalProperties": false, "description": "Personal details are those which contribute to building up a picture of the person as an individual, such as name, title, etc..", "properties": { "birthdate": { "description": "Date of birth. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "1987-05-22", "nullable": true }, "email": { "description": "Email address", "maxLength": 256, "type": "string", "example": "john_s@test.com", "nullable": true }, "firstName": { "description": "First name", "maxLength": 75, "type": "string", "x-conditional": true, "example": "John", "nullable": true }, "fullName": { "description": "Full name. Not Needed if firstName and LastName are provided independently.", "maxLength": 150, "type": "string", "x-conditional": true, "example": "John Smith", "nullable": true }, "gender": { "description": "Gender", "enum": [ "MALE", "FEMALE", "CHOSE_NOT_TO_SPECIFY", "NONE" ], "example": "MALE", "nullable": true }, "lastName": { "description": "Last name", "maxLength": 75, "type": "string", "x-conditional": true, "example": "Smith", "nullable": true } }, "type": "object" }, "Phone": { "additionalProperties": false, "description": "This provides information about the telephone number associated with the customer or transaction.", "properties": { "phone": { "description": "Phone number including all country and local access codes", "maxLength": 25, "type": "string", "example": "15557654321" }, "smsVerified": { "allOf": [ { "$ref": "#/components/schemas/Verification", "description": "Phone verification details" }, { "type": "object", "nullable": true } ] } }, "required": [ "phone" ], "type": "object" }, "RecurringPaymentDetails": { "additionalProperties": false, "properties": { "currentPaymentNumber": { "description": "The number of payments processed in this recurring event including current transaction (1 for the original transaction)", "type": "integer", "example": 1, "nullable": true }, "initialPaymentOrderId": { "description": "Original order/transaction identifier that started the recurring event (payment number 1)", "maxLength": 40, "type": "string", "example": "2356fdse0rr483" }, "isPaymentAmountIdenticalForAllPayments": { "description": "True if the amount is constant between payments", "type": "boolean", "example": false, "nullable": true }, "recurringPaymentExpirationDate": { "description": "Date of last expected payment event. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "1988-06-22", "nullable": true }, "recurringPaymentFrequency": { "description": "The number of days between transactions.", "type": "string", "example": "7" }, "totalNumberOfPayments": { "description": "Expected number of payments processed in this recurring event", "type": "integer", "example": 12, "nullable": true } }, "required": [ "recurringPaymentFrequency", "initialPaymentOrderId" ], "type": "object" }, "SavedData": { "additionalProperties": false, "description": "Saved Data refers to information which persists in the account settings, such as address or payment information.", "properties": { "choseToSaveData": { "description": "True if customer chose to save data in the account for future use", "type": "boolean", "example": false, "nullable": true }, "usedSavedData": { "description": "True if customer chose to use data saved in the account", "type": "boolean", "example": true, "nullable": true } }, "type": "object" }, "SocialNetwork": { "additionalProperties": false, "description": "Social networks are a mine of valuable information which can be used to identify a customer as real or fraudulent.\nThis object contains information known about a customer's social profile.", "properties": { "networkName": { "description": "Social network name", "enum": [ "FACEBOOK", "GOOGLE", "TWITTER", "REDDIT", "PINTEREST", "WECHAT", "QQ", "TWITCH", "APPLE", "DRIBBBLE", "GITHUB", "LINKEDIN", "MAKER_STUDIOS", "STACK_EXCHANGE", "VIMEO", "STEAM", "OTHER", "KAKAO", "NAVER", "GRAB", "JKOPAY", "LINE" ], "example": "FACEBOOK", "nullable": true }, "profileId": { "description": "Unique social profile identifier", "maxLength": 50, "type": "string", "example": "10000054564897", "nullable": true } }, "type": "object" }, "ThreeDSecureForcePsd2Exemption": { "additionalProperties": false, "properties": { "channel": { "description": "The channel through which the exemption is requested", "enum": [ "THREEDS_RAILS", "AUTHORIZATION" ], "example": "THREEDS_RAILS" }, "type": { "description": "The type of exemption requested", "enum": [ "LOW_VALUE", "TRANSACTION_RISK_ANALYSIS", "SECURE_CORPORATE", "TRUSTED_BENEFICIARY" ], "example": "LOW_VALUE" } }, "required": [ "channel", "type" ], "type": "object" }, "ThreeDSecureInput": { "additionalProperties": false, "properties": { "acquirerData": { "allOf": [ { "$ref": "#/components/schemas/AcquirerData", "description": "This provides information about the Acquirer of the transaction", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "challengeIndicator": { "description": "Request your preference regarding the executing of 3DS challange regardless of Forter's decision and recommendation", "enum": [ "NO_PREFERENCE", "NO_CHALLENGE", "CHALLENGE", "CHALLENGE_AS_MANDATE" ], "example": "NO_PREFERENCE", "nullable": true }, "execute3ds": { "description": "Request your preference regarding the execution of 3DS", "enum": [ "FORCE_3DS", "FORCE_DATA_ONLY", "NOT_SUPPORTED_BY_MERCHANT", "DYNAMIC_FORTER_DECISION" ], "example": "DYNAMIC_FORTER_DECISION", "nullable": true }, "forcePsd2Exemption": { "allOf": [ { "$ref": "#/components/schemas/ThreeDSecureForcePsd2Exemption", "description": "Request for specific exemption regardless of Forter's decision and recommendation" }, { "type": "object", "nullable": true } ] }, "requestChallenge": { "description": "Indicates if a 3DS challenge should be requested from the Issuer ACS.", "type": "boolean", "example": false, "nullable": true }, "threeDSServerTransID": { "description": "Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction generated by the Init 3DS API and used to link the init call to the order call", "maxLength": 100, "type": "string", "example": "26d648a9-da8a-4f8b-a76d-094801d2fd45" }, "threeDsExecutor": { "description": "Request your preference regarding the 3DS executor. To be used only for an edge case, where a merchant with 3DS execution demands Forter to not execute 3DS on a limited subset of TXs", "enum": [ "FORTER", "MERCHANT" ], "nullable": true } }, "required": [ "threeDSServerTransID" ], "type": "object" }, "TokenizedCreditCard": { "additionalProperties": false, "description": "This provides details relating to a tokenized card.", "properties": { "bin": { "description": "Credit card's BIN (Bank Identification Number)", "maxLength": 8, "pattern": "[0-9]{6,8}", "type": "string", "x-conditional": true, "example": "42424242", "nullable": true }, "cardBank": { "description": "Credit card's issuing bank", "maxLength": 128, "type": "string", "x-conditional": true, "example": "Chase", "nullable": true }, "cardBrand": { "description": "Credit card's issuer brand", "maxLength": 50, "type": "string", "x-conditional": true, "example": "VISA", "nullable": true }, "cardType": { "description": "Payment card type", "enum": [ "CREDIT", "DEBIT", "PREPAID", "UNKNOWN" ], "x-conditional": true, "example": "CREDIT", "nullable": true }, "countryOfIssuance": { "description": "Credit card's issuing country, two-letter ISO 3166-1 alpha-2 country code", "maxLength": 2, "pattern": "[A-Za-z]{2}", "type": "string", "x-conditional": true, "example": "US", "nullable": true }, "creationTime": { "description": "Time the card was tokenized by the merchant in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1430997968, "nullable": true }, "creditCardCorrelationId": { "description": "Credit card - CorrelationId that was recieved by the init 3DS API", "type": "string", "nullable": true }, "expirationMonth": { "description": "Credit card's expiration month, in MM format", "maxLength": 2, "pattern": "[0-9]{2}", "type": "string", "example": "03" }, "expirationYear": { "description": "Credit card's expiration year, in YYYY format", "maxLength": 4, "pattern": "[0-9]{4}", "type": "string", "example": "2018" }, "fullResponsePayload": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Full processor or gateway response object" }, { "type": "object", "nullable": true } ] }, "lastFourDigits": { "description": "Credit card's last 4 digits", "maxLength": 4, "pattern": "[0-9]{2,4}", "type": "string", "example": "4242", "nullable": true }, "nameOnCard": { "description": "Cardholder's full name", "maxLength": 75, "type": "string", "example": "John R. H. Smith", "nullable": true }, "paymentProcessorData": { "allOf": [ { "$ref": "#/components/schemas/PaymentProcessorData", "description": "Payment processor data" }, { "type": "object", "nullable": true } ] }, "threeDSecure": { "allOf": [ { "$ref": "#/components/schemas/ThreeDSecureInput" }, { "type": "object", "nullable": true } ] }, "token": { "description": "Credit card token used by the merchant", "maxLength": 200, "type": "string", "example": "tkn-77620C360132856A103477D2959967AB" }, "tokenType": { "description": "Token type, determined by the party/protocol the token created by", "enum": [ "PSP", "EMV_PAYMENT_TOKEN", "MERCHANT_GENERATED", "FORTER_TOKEN", "OTHER" ], "maxLength": 128, "nullable": true }, "verificationResults": { "$ref": "#/components/schemas/CreditCardVerification", "description": "Credit card verification data" } }, "required": [ "token", "expirationMonth", "expirationYear", "verificationResults" ], "type": "object" }, "UnderlyingPaymentMethod": { "additionalProperties": false, "description": "This provides details relating to an underlying payment method belongs to a digital wallet.", "properties": { "bankTransfer": { "allOf": [ { "$ref": "#/components/schemas/BankTransfer", "description": "Bank transfer used to pay for purchase (incl. Sofort, iDEAL, ACH, SEPA Direct Debit, etc.)", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "bitcoin": { "description": "Bitcoin payment details", "type": "boolean", "x-conditional": true, "example": false, "nullable": true }, "cash": { "description": "Payed with cash", "type": "boolean", "x-conditional": true, "example": false, "nullable": true }, "creditCard": { "allOf": [ { "$ref": "#/components/schemas/TokenizedCreditCard", "description": "Credit card details", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "underlyingPaymentMethodType": { "description": "Underlying payment method type used in current transaction", "enum": [ "UNKNOWN", "CREDITCARD", "BANKTRANSFER", "CASH", "BITCOIN" ], "example": "UNKNOWN" } }, "required": [ "underlyingPaymentMethodType" ], "type": "object" }, "Venmo": { "additionalProperties": false, "description": "This provides information about the Venmo account associated with the customer or transaction.", "properties": { "fullVenmoResponsePayload": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Full Venmo response object" }, { "type": "object", "nullable": true } ] }, "paymentId": { "description": "Venmo payment ID", "maxLength": 50, "type": "string", "x-conditional": true, "example": "1KZSDEYA", "nullable": true }, "token": { "description": "Token representing the specific payment method used within the Venmo vault", "maxLength": 200, "type": "string", "example": "77620C360132856A103477D2959967AB" }, "userId": { "description": "Venmo userID", "maxLength": 50, "type": "string", "example": "johndoe" }, "userName": { "description": "Venmo user name", "maxLength": 50, "type": "string", "example": "johndoe1987" } }, "required": [ "token", "userId", "userName" ], "type": "object" }, "Verification": { "additionalProperties": false, "description": "This object contains information about steps taken to verify the customer's identity such as email or phone verifcations.", "properties": { "sent": { "description": "True if verification email was sent to email address or verification SMS was sent to phone number", "type": "boolean", "example": true, "nullable": true }, "timeSent": { "description": "Date verification email or SMS was sent in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1389567341, "nullable": true }, "verified": { "description": "True if customer received email verification message to this address and clicked-through back to merchant's site, or received SMS message and enterd code in merchant's site (two-factor authentication)", "type": "boolean", "example": false } }, "required": [ "verified" ], "type": "object" }, "accountAccessRequestRequest": { "additionalProperties": false, "description": "Send information on an attempt to access or edit a customer profile to receive a fraud decision. Used for account takeover at profile touchpoint, card testing, and digital key use cases. The response may also include recommendations for additional authentication (MFA) and a correlation ID to include with the authentication result.", "properties": { "accessRequestType": { "description": "The type of restricted access the user is asking for", "enum": [ "VIEW_PERSONAL_PREFERENCES", "UPDATE_PASSWORD", "UPDATE_PAYMENT", "UPDATE_PHONE", "UPDATE_EMAIL", "UPDATE_ADDRESS", "REDEEM_ACCOUNT_ASSETS", "SHARE_CREDENTIALS", "DIGITAL_KEY_ACCESS", "DIGITAL_CHECK_IN", "USE_PAYMENT_METHOD" ], "x-conditional": true, "example": "UPDATE_PASSWORD", "nullable": true }, "accountId": { "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\nsuffix '_GUEST'", "maxLength": 100, "type": "string", "example": "e520-ba9a-367-60b" }, "accountOwner": { "allOf": [ { "$ref": "#/components/schemas/AccountOwner", "description": "The customer's basic information.", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "additionalAccountEventIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/AdditionalAccountEventIdentifiers", "description": "Additional identifiers of the account event." }, { "type": "object", "nullable": true } ] }, "additionalInformation": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Additional information not described in the documentation." }, { "type": "object", "nullable": true } ] }, "channelType": { "description": "The source channel through which the customer requested profile access. Note that some of the enum values are not relevant for this interaction.", "enum": [ "WEB", "PHONE", "DYNAMIC_PHONE", "MOBILE", "MOBILE_IN_STORE", "IOS", "ANDROID", "WAP", "STORE", "MERCHANT_EMPLOYEE", "MAIL_ORDER", "AUTOMATIC_RENEWAL_OR_INSTALLMENT_PAYMENT", "MERCHANT_INITIATED", "UNKNOWN", "POS", "API_ONLY", "PERSONAL_POS", "PHONE_LINK", "AI_AGENT" ], "x-conditional": true, "example": "WEB", "nullable": true }, "connectionInformation": { "$ref": "#/components/schemas/ConnectionInformation", "description": "Connection information about the customer typically found in the HTTP request header." }, "eventTime": { "description": "The time that the trigger event occurred in MILLISECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1415287568000 }, "existingPaymentMethod": { "allOf": [ { "$ref": "#/components/schemas/Payment", "description": "Existing payment method being used for the transaction. Required only in case the access request is USE_PAYMENT_METHOD" }, { "type": "object", "nullable": true } ] }, "merchantIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/MerchantIdentifiers", "description": "If a merchant operates a number of sites, Merchant Identifiers help Forter's system to identify the right site." }, { "type": "object", "nullable": true } ] }, "newAddress": { "allOf": [ { "$ref": "#/components/schemas/Address", "description": "new address to save in the account. Required only in case the access request is UPDATE_ADDRESS." }, { "type": "object", "nullable": true } ] }, "newEmail": { "allOf": [ { "$ref": "#/components/schemas/Email", "description": "new email to save in the account. Required only in case the access request is UPDATE_EMAIL." }, { "type": "object", "nullable": true } ] }, "newPaymentMethods": { "allOf": [ { "$ref": "#/components/schemas/Payment", "description": "new payment method to save in the account. Required only in case the access request is UPDATE_PAYMENT" }, { "type": "object", "nullable": true } ] }, "newPhone": { "allOf": [ { "$ref": "#/components/schemas/Phone", "description": "new phone to save in the account. Required only in case the access request is UPDATE_PHONE." }, { "type": "object", "nullable": true } ] }, "originalOrderId": { "description": "Unique order/transaction identifier for which this access request is referring to, if relevant. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.", "maxLength": 54, "type": "string", "example": "2356fdse0rr489", "nullable": true }, "passwordUpdateTrigger": { "description": "The trigger that caused the password update. Required only in case the access request is UPDATE_PASSWORD", "enum": [ "MERCHANT_POLICY", "USER_FORGOT_PASSWORD", "LOGGED_IN_USER" ], "x-conditional": true, "example": "USER_FORGOT_PASSWORD", "nullable": true } }, "required": [ "accountId", "eventTime", "connectionInformation" ], "type": "object" }, "AdvancedAuthenticationMethod": { "additionalProperties": false, "description": "Details and status of advanced authentication methods used for MFA and OTP.\nWhen this object is sent, at least one of the verifications should be provided", "properties": { "correlationId": { "description": "A forter unique identifier that was provided as part of a Forter API response recommending additional authentication measures. Used to correlate between the user action which triggered the recommendation and the authentication attempt result. Required when the additional authentication was triggered by Forter's recommendation.", "type": "string", "example": "HGJ7512345H3DE" }, "documentVerification": { "allOf": [ { "$ref": "#/components/schemas/AdditionalVerificationDocuments", "description": "The document used for MFA and the verification status", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "emailVerification": { "allOf": [ { "$ref": "#/components/schemas/Email", "description": "The email used for MFA and the verification status", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "oneTimePasswordVerification": { "allOf": [ { "$ref": "#/components/schemas/SimplifiedVerification", "description": "The method used for user verification at payment time", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "paymentInstrumentVerification": { "allOf": [ { "$ref": "#/components/schemas/PaymentInstrumentVerification", "description": "The payment instrument verification steps used and the verification status", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "phoneVerification": { "allOf": [ { "$ref": "#/components/schemas/Phone", "description": "The phone number used for MFA and the verification status", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "verificationOutcome": { "description": "Outcome of verification attempt", "enum": [ "SUCCESS", "FAILURE", "NONE_ATTEMPTED" ], "example": "SUCCESS" } }, "required": [ "verificationOutcome", "correlationId" ], "type": "object" }, "PaymentInstrumentVerification": { "additionalProperties": false, "description": "Details and status of advanced payment instrument authentication methods used for MFA and OTP.\nWhen this object is sent, at least one of the verifications should be provided", "properties": { "cameraCaptured": { "description": "The user successfully took a photo of their credit card using an OCR feature of the mobile app", "type": "boolean", "example": false, "nullable": true }, "creditCardManuallyTypedIn": { "description": "The user successfully typed in the full number of the credit card that was saved in the account", "type": "boolean", "example": false, "nullable": true }, "cvvManuallyTypedIn": { "description": "The user successfully typed in the CVV of the credit card that was saved in the account", "type": "boolean", "example": false, "nullable": true }, "lastFourDigits": { "description": "Last 4 digits of the credit card that was verified", "maxLength": 4, "pattern": "[0-9]{4}", "type": "string", "example": "4242", "nullable": true }, "token": { "description": "Token of the credit card that was verified", "maxLength": 200, "type": "string", "example": "tkn-77620C360132856A103477D2959967AB", "nullable": true } }, "type": "object" }, "SimplifiedVerification": { "additionalProperties": false, "description": "This object contains information about steps taken to verify a customer's identity.", "properties": { "timeVerified": { "description": "Date user was verified in seconds since unix epoch(UTC, Jan 1, 1970)", "type": "number", "example": 1388560227, "nullable": true }, "verificationMethod": { "description": "Type of one time verification method", "maxLength": 50, "type": "string", "example": "Google Authenticator" }, "verified": { "description": "Was the user verified via the chosen verification method", "type": "boolean", "example": false } }, "required": [ "verificationMethod", "verified" ], "type": "object" }, "accountAuthenticationRequest": { "additionalProperties": false, "description": "Inform of authentication results after an attempted login or profile access request, using the provided correlation ID. While no decision is provided on this request, it improves the decision model for login and access.", "properties": { "accountId": { "description": "Customer's account UID in merchant's site. Should not be the user email.", "maxLength": 100, "type": "string", "example": "e520-ba9a-367-60b" }, "additionalAuthenticationMethod": { "allOf": [ { "$ref": "#/components/schemas/AdvancedAuthenticationMethod", "description": "Additional details in case advanced authentication methods were used (e.g. MFA, OTP)" }, { "type": "object", "nullable": true } ] }, "additionalInformation": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Additional information not described in the documentation." }, { "type": "object", "nullable": true } ] }, "bankTransferVerificationResults": { "allOf": [ { "$ref": "#/components/schemas/BankTransfer", "description": "Bank transfer verification data" }, { "type": "object", "nullable": true } ] }, "connectionInformation": { "allOf": [ { "$ref": "#/components/schemas/ConnectionInformation", "description": "Connection information about the customer typically found in the HTTP request header.", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "eventTime": { "description": "The time that the trigger event occurred in MILLISECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1415287568000 }, "merchantIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/MerchantIdentifiers", "description": "If a merchant operates a number of sites, Merchant Identifiers help Forter's system to identify the right site." }, { "type": "object", "nullable": true } ] }, "paymentAuthorizationResults": { "allOf": [ { "$ref": "#/components/schemas/CreditCardVerification", "description": "Credit card verification data" }, { "type": "object", "nullable": true } ] }, "paypalVerificationResults": { "allOf": [ { "$ref": "#/components/schemas/Paypal", "description": "PayPal verification data" }, { "type": "object", "nullable": true } ] } }, "required": [ "accountId", "eventTime" ], "type": "object" }, "AccommodationItem": { "additionalProperties": false, "description": "In cases where the transaction involves purchasing accommodation, Accommodation Item gives details relating to the type of accommodation purchased.", "properties": { "accommodationAddress": { "allOf": [ { "$ref": "#/components/schemas/Address", "description": "Location of accommodation" }, { "type": "object", "nullable": true } ] }, "accommodationName": { "description": "Name of the facility", "maxLength": 100, "type": "string", "nullable": true }, "duration": { "allOf": [ { "$ref": "#/components/schemas/Duration", "description": "Duration of stay" }, { "type": "object", "nullable": true } ] }, "housingType": { "description": "Type of room/housing", "maxLength": 100, "type": "string", "example": "Presidential Suite", "nullable": true }, "isRefundable": { "description": "True if order can be cancelled and refunded", "type": "boolean", "example": false, "nullable": true }, "location": { "allOf": [ { "$ref": "#/components/schemas/RoughLocation", "description": "Location of accommodation" }, { "type": "object", "nullable": true } ] }, "numberOfGuests": { "description": "Number of guests", "type": "number", "example": 2 }, "rating": { "description": "All ratings given to item or service. Can include internal peer rating, merchant rating, official professional association ratings, etc.", "items": { "$ref": "#/components/schemas/Rating" }, "type": "array", "x-conditional": true, "nullable": true }, "type": { "description": "Type of accommodation service", "enum": [ "HOTEL", "APARTMENT", "CRUISE", "STUDIO", "EVENT_VENUE" ], "example": "HOTEL", "nullable": true } }, "required": [ "numberOfGuests" ], "type": "object" }, "AccountData": { "additionalProperties": false, "description": "This provides information associated with the buyer/seller account.", "properties": { "additionalVerificationDocuments": { "allOf": [ { "$ref": "#/components/schemas/AdditionalVerificationDocuments", "description": "Additional identification document details and verification" }, { "type": "object", "nullable": true } ] }, "addressesInAccount": { "description": "All non-billing addresses saved in account. Billing information is included in paymentMethodsInAccount", "items": { "$ref": "#/components/schemas/Address" }, "type": "array", "nullable": true }, "customerEngagement": { "allOf": [ { "$ref": "#/components/schemas/CustomerEngagement", "description": "Different indicators of customer engagement within the merchant's site and community", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "emailsInAccount": { "description": "All email addresses saved in account", "items": { "$ref": "#/components/schemas/Email" }, "type": "array", "nullable": true }, "paymentMethodsInAccount": { "description": "All payment methods saved in account", "items": { "$ref": "#/components/schemas/Payment" }, "type": "array", "nullable": true }, "personalDetails": { "allOf": [ { "$ref": "#/components/schemas/PersonalDetails", "description": "Account holder's personal details" }, { "type": "object", "nullable": true } ] }, "phonesInAccount": { "description": "All phone numbers saved in account", "items": { "$ref": "#/components/schemas/Phone" }, "type": "array", "nullable": true }, "ratingAsBuyer": { "allOf": [ { "$ref": "#/components/schemas/Rating", "description": "Rating pertaining to the customer as a buyer" }, { "type": "object", "nullable": true } ] }, "registrationIP": { "description": "IP address used by the account owner at the time of registration.", "type": "string", "example": "203.12.55.12", "nullable": true }, "type": { "description": "Account type (a business account, a private account, a merchant-operated account)", "enum": [ "GUEST", "PRIVATE", "BUSINESS", "VIP", "MERCHANT_OPERATED", "TRIAL", "MERCHANT_EMPLOYEE", "PREMIUM_PAID", "SMALL_BUSINESS", "AGENT", "BUSINESS_PRIVATE", "BUSINESS_PREMIUM_PAID" ], "x-conditional": true, "example": "BUSINESS", "nullable": true } }, "type": "object" }, "BasicItemData": { "additionalProperties": false, "description": "This is an item associated with the customer or transaction.", "properties": { "category": { "description": "Item category", "maxLength": 1000, "type": "string", "example": "Apparel and accessories", "nullable": true }, "discount": { "allOf": [ { "$ref": "#/components/schemas/Discount" }, { "type": "object", "nullable": true } ] }, "name": { "description": "Item name", "maxLength": 500, "type": "string", "example": "White GenericBrand handbag" }, "price": { "$ref": "#/components/schemas/Amount", "description": "Final amount due for purchase, after all discounts and promotions" }, "productId": { "description": "Unique identifier for item that is common to all identical items (such as SKU, ISBN, etc.)", "maxLength": 70, "type": "string", "example": "Ag54352R7768kkO", "nullable": true }, "quantity": { "description": "Item quantity", "type": "number", "example": 1 }, "type": { "description": "Tangible if physical item, non-tangible if any other product", "enum": [ "TANGIBLE", "NON_TANGIBLE" ], "example": "TANGIBLE" } }, "required": [ "name", "quantity", "type", "price" ], "type": "object" }, "BasicSellerData": { "additionalProperties": false, "description": "This provides a more detailed picture of the seller - their details, actions etc..", "properties": { "availableFundsForWithdrawal": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Funds ready for immediate withdrawal by seller" }, { "type": "object", "nullable": true } ] }, "dateOfFirstSale": { "description": "Date of first sale by seller, in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1430997968, "nullable": true }, "ratingAsBuyer": { "allOf": [ { "$ref": "#/components/schemas/Rating", "description": "Rating pertaining to the customer as a buyer" }, { "type": "object", "nullable": true } ] }, "ratingAsSeller": { "allOf": [ { "$ref": "#/components/schemas/Rating", "description": "Rating pertaining to the customer as a seller" }, { "type": "object", "nullable": true } ] }, "sellerAccountCreationDate": { "description": "Date seller account was created in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1415273168 }, "sellerLastLoginIP": { "allOf": [ { "$ref": "#/components/schemas/IP", "description": "IP used by seller on his latest login event", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "sellerPastSalesCount": { "description": "Count of all successfully fulfilled sales made", "type": "integer", "example": 8, "nullable": true }, "sellerPersonalDetails": { "allOf": [ { "$ref": "#/components/schemas/PersonalDetails", "description": "Basic information regarding seller", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "sellerRegistrationIP": { "allOf": [ { "$ref": "#/components/schemas/IP", "description": "IP used by seller when first registering account", "x-conditional": true }, { "type": "object", "nullable": true } ] } }, "required": [ "sellerAccountCreationDate" ], "type": "object" }, "Beneficiary": { "additionalProperties": false, "description": "Beneficiaries are people who have received goods sent to them by customers through your website - as when a parent sends an item to a child at university, or when a gift is purchased and sent straight to the recipient.", "properties": { "additionalVerificationDocuments": { "allOf": [ { "$ref": "#/components/schemas/AdditionalVerificationDocuments", "description": "Aditional identification document details and verification" }, { "type": "object", "nullable": true } ] }, "address": { "allOf": [ { "$ref": "#/components/schemas/Address", "description": "Address details", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "bankAccount": { "allOf": [ { "$ref": "#/components/schemas/BankTransfer", "description": "Recipient's bank account details" }, { "type": "object", "nullable": true } ] }, "comments": { "allOf": [ { "$ref": "#/components/schemas/Comments", "description": "Comments to merchant or beneficiary written by customer" }, { "type": "object", "nullable": true } ] }, "cryptoWallet": { "allOf": [ { "$ref": "#/components/schemas/CryptoWallet", "description": "Digital wallet details" }, { "type": "object", "nullable": true } ] }, "identityCard": { "description": "Recipient's identity card number", "type": "string", "nullable": true }, "loyaltyProgram": { "description": "Details regarding loyalty program customer entered to receive points for this order", "items": { "$ref": "#/components/schemas/LoyaltyProgram" }, "type": "array", "nullable": true }, "personalDetails": { "$ref": "#/components/schemas/PersonalDetails", "description": "Personal information such as name, birthdate and email" }, "phone": { "description": "Phone details", "items": { "$ref": "#/components/schemas/Phone" }, "type": "array", "x-conditional": true, "nullable": true } }, "required": [ "personalDetails" ], "type": "object" }, "Comments": { "additionalProperties": false, "description": "Comments are notes the customer included as part of their transaction, whether directed to the merchant or to the intended recipient.", "properties": { "merchantComments": { "description": "Comments by the merchant", "maxLength": 600, "type": "string", "example": "Shipping delayed", "nullable": true }, "messageToBeneficiary": { "description": "Comments the customer left to the beneficiary of the purchase made", "maxLength": 600, "type": "string", "example": "Enjoy the gift John!", "nullable": true }, "userCommentsToMerchant": { "description": "Comments the customer left to the merchant", "maxLength": 600, "type": "string", "example": "Please wrap with care!!", "nullable": true } }, "type": "object" }, "CryptoItem": { "additionalProperties": false, "description": "Details relating to cryptocurrency purchases", "properties": { "destinationWallet": { "description": "Destination wallet address", "type": "string", "example": "3JQiwG88SQvwihDAHg9M2EnqEisharz49c", "nullable": true } }, "type": "object" }, "CustomerEngagement": { "additionalProperties": false, "description": "This reflects the level of customer engagement with the store and its items.", "properties": { "aboutMe": { "description": "True if customer added a short bio or about me to the profile", "type": "boolean", "example": false, "nullable": true }, "communityPostsWritten": { "allOf": [ { "$ref": "#/components/schemas/ListProperties", "description": "Posts written by customer in community areas of merchant's site (blog, forum, users' profiles)" }, { "type": "object", "nullable": true } ] }, "enableDeviceLocation": { "description": "Set to True if the user has allowed the app to track their location.", "type": "boolean", "example": false, "nullable": true }, "extendedBioOrDescription": { "description": "True if account owner added an extended info/bio/description paragraph to their profile", "type": "boolean", "example": false, "nullable": true }, "followersCount": { "description": "Number of followers of customer's account, or number of likes to user's profile", "type": "integer", "example": 105, "nullable": true }, "followingCount": { "description": "Number of other users the customer is following, or number of likes customer gave to other users' profiles", "type": "integer", "example": 230, "nullable": true }, "invites": { "description": "Invites to merchant's site customer sent and received", "items": { "$ref": "#/components/schemas/Invite" }, "type": "array", "nullable": true }, "likedItems": { "allOf": [ { "$ref": "#/components/schemas/ListProperties", "description": "Items liked or favorited by customer" }, { "type": "object", "nullable": true } ] }, "messagesReceived": { "allOf": [ { "$ref": "#/components/schemas/ListProperties", "description": "Messages received by customer from other users or sellers within merchant's site" }, { "type": "object", "nullable": true } ] }, "messagesSent": { "allOf": [ { "$ref": "#/components/schemas/ListProperties", "description": "Messages sent by customer to other users or sellers within merchant's site" }, { "type": "object", "nullable": true } ] }, "newsletters": { "allOf": [ { "$ref": "#/components/schemas/ListProperties", "description": "Newsletters and catalogs customer chose to receive" }, { "type": "object", "nullable": true } ] }, "profileLogo": { "description": "True if account owner added a non-default logo to their account", "type": "boolean", "example": false, "nullable": true }, "profilePicture": { "description": "True if customer added a profile picture", "type": "boolean", "example": true, "nullable": true }, "requestedDemo": { "description": "True if account owner requested to schedule a walthrough or demo of the site", "type": "boolean", "example": true, "nullable": true }, "reviewsWritten": { "allOf": [ { "$ref": "#/components/schemas/ListProperties", "description": "Reviews written by customer on products or other users within merchant's site" }, { "type": "object", "nullable": true } ] }, "savedLocations": { "description": "Saved locations in account.", "items": { "$ref": "#/components/schemas/ExactLocation" }, "type": "array", "nullable": true }, "sharedItems": { "allOf": [ { "$ref": "#/components/schemas/ListProperties", "description": "Items shared by customer" }, { "type": "object", "nullable": true } ] }, "signedUpForPushNotifications": { "description": "True if customer asked to receive push notifications from the merchant.", "type": "boolean", "example": true, "nullable": true }, "signedUpForSMSUpdates": { "description": "True if customer asked to receive SMS updates from the merchant regarding discounts, promotions, etc.", "type": "boolean", "example": true, "nullable": true }, "wishlist": { "allOf": [ { "$ref": "#/components/schemas/ListProperties", "description": "Items added to wishlist or registry by customer" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "DeliveryDetails": { "additionalProperties": false, "description": "Delivery Details provides further information about the kind of delivery chosen by the customer.", "properties": { "delayedDeliveryDate": { "description": "Use only if customer explicitly selected a delayed delivery date beyond the merchant’s standard options. Use YYYY-MM-DD format.", "format": "date", "type": "string", "x-conditional": true, "example": "2014-12-15", "nullable": true }, "delayedDeliveryTime": { "description": "Use only if customer explicitly selected a delayed delivery date, with specific time of day, beyond the merchant’s standard options. Should be sent in seconds since unix epoch (UTC, Jan 1, 1970).", "type": "number", "x-conditional": true, "example": 1415273168, "nullable": true }, "deliveryComments": { "description": "Any comments or requests customer had for delivery", "maxLength": 255, "type": "string", "example": "Please call before arriving, Thanks!", "nullable": true }, "deliveryMethod": { "description": "Delivery method chosen by customer such as postal service, email, in game transfer, etc.", "maxLength": 80, "type": "string", "example": "USPS - Ground Mail" }, "deliveryPrice": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Cost of delivery" }, { "type": "object", "nullable": true } ] }, "deliveryType": { "description": "Type of delivery: PHYSICAL for any type of shipped goods. DIGITAL for non-shipped goods (services, gift cards etc.)", "enum": [ "DIGITAL", "PHYSICAL", "HYBRID" ], "example": "PHYSICAL" } }, "required": [ "deliveryType", "deliveryMethod" ], "type": "object" }, "Discount": { "additionalProperties": false, "description": "This provides information relating to any kind of offer, coupon or other discount used by the customer.", "properties": { "couponCodeUsed": { "description": "Coupon code used", "maxLength": 150, "type": "string", "example": "FATHERSDAY2015" }, "couponDiscountAmount": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Coupon discount amount" }, { "type": "object", "nullable": true } ] }, "couponDiscountPercent": { "description": "Coupon discount amount", "type": "string", "nullable": true } }, "required": [ "couponCodeUsed" ], "type": "object" }, "Duration": { "additionalProperties": false, "description": "An object that represents a duration in days. Note that the endDate must be greater than or equal to the startDate.\nThe required date format is YYYY-MM-DD.", "properties": { "endDate": { "description": "Date service/item ends or becomes unavailable. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "2014-11-15" }, "startDate": { "description": "Date service/item begins or becomes available. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "2014-10-28" } }, "required": [ "startDate", "endDate" ], "type": "object" }, "ExactDuration": { "additionalProperties": false, "description": "An object that represents exact duration in seconds. Note that the endTime must be greater than or equal to the startTime.\nThe required timestamp format is seconds since unix epoch (UTC, Jan 1, 1970)", "properties": { "endTime": { "description": "Unix timestamp in seconds of when service/item ends or becomes unavailable in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "integer", "example": 1420294711 }, "startTime": { "description": "Unix timestamp in seconds of when service/item begins or becomes available in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1412345911 } }, "required": [ "startTime", "endTime" ], "type": "object" }, "ExactLocation": { "additionalProperties": false, "description": "Details of a location in lat/long coordinates", "properties": { "latitude": { "description": "Latitude in Decimal Degrees (WGS84)", "type": "number", "example": 32.07332, "nullable": true }, "longitude": { "description": "Longitude in Decimal Degrees (WGS84)", "type": "number", "example": 34.79675, "nullable": true }, "source": { "description": "Source of location data", "maxLength": 50, "type": "string", "example": "MOBILE", "nullable": true } }, "type": "object" }, "FoodItem": { "additionalProperties": false, "description": "If the item purchased is somekind of food, this gives further details describing the item more precisely.", "properties": { "restaurantAddress": { "allOf": [ { "$ref": "#/components/schemas/Address", "description": "the restaurant's address details", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "restaurantId": { "description": "Restaurant unique identifier", "maxLength": 50, "type": "string", "example": "eh674df9", "nullable": true }, "restaurantName": { "description": "The name of the restaurant", "maxLength": 100, "type": "string", "example": "Ron's Steak House", "nullable": true }, "tipAmount": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Tip paid in advanced by customer" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "GamingItem": { "additionalProperties": false, "description": "This includes details relevant to computer gaming related items, the player involved and how it is being played by the customer.", "properties": { "characterName": { "description": "In-game character name", "maxLength": 100, "type": "string", "x-conditional": true, "example": "JohnTheGamer", "nullable": true }, "characterRole": { "description": "Character's role in the game", "maxLength": 100, "type": "string", "example": "Warrior", "nullable": true }, "gameGenre": { "description": "Game type/genre", "maxLength": 50, "type": "string", "example": "MMORPG", "nullable": true }, "gameItemAmount": { "description": "Number of game items or commodities bought (100 coins, 2000 gold, 10 experience points, etc.)", "type": "number", "example": 1000, "nullable": true }, "gameName": { "description": "Game name", "maxLength": 50, "type": "string", "example": "WorldOfSampleGamecrat" }, "gamePlatform": { "description": "Game platform", "maxLength": 50, "type": "string", "example": "XBOX", "nullable": true }, "gameServerCountry": { "description": "Country, two-letter ISO 3166-1 alpha-2 country code", "maxLength": 2, "pattern": "[A-Za-z]{2}", "type": "string", "x-conditional": true, "example": "DK", "nullable": true }, "gameServerName": { "description": "Game server name", "maxLength": 100, "type": "string", "example": "5ample5erver", "nullable": true }, "inGameTradeLocation": { "description": "In-Game trade location", "type": "string", "example": "At the mouth of the Sampletradelocation river", "nullable": true }, "playerFaction": { "description": "Player's in-game faction/clan/group", "maxLength": 100, "type": "string", "example": "TestC1an", "nullable": true }, "playerLeague": { "description": "Player's in-game league", "maxLength": 100, "type": "string", "example": "TestLeauge", "nullable": true }, "playerLevel": { "description": "Player's in-game level", "maxLength": 50, "type": "string", "x-conditional": true, "example": "59", "nullable": true }, "playerPosition": { "description": "Player's in-game position", "maxLength": 50, "type": "string", "example": "10", "nullable": true } }, "required": [ "gameName" ], "type": "object" }, "IP": { "additionalProperties": false, "description": "This provides information about the IP address associated with the customer or transaction.", "properties": { "ip": { "description": "Customer IP address in v4 format", "type": "string", "example": "10.0.0.128" }, "updateTimes": { "allOf": [ { "$ref": "#/components/schemas/UpdateTimes", "description": "First and last times this IP address was used" }, { "type": "object", "nullable": true } ] } }, "required": [ "ip" ], "type": "object" }, "Invite": { "additionalProperties": false, "description": "If the customer was gained through an invitation or has sent others invitations to join, this gives further details relating to that invitation.", "properties": { "invitationCounterpartyPhone": { "description": "Invitation sender/recipient phone number", "maxLength": 25, "type": "string", "example": "+12126667777", "nullable": true }, "sent": { "description": "Time invite was sent in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "x-conditional": true, "example": 1420955538, "nullable": true }, "type": { "description": "Type of invite", "enum": [ "SENT", "RECEIVED" ], "example": "SENT", "nullable": true } }, "type": "object" }, "Item": { "additionalProperties": false, "description": "This is an item associated with the customer or transaction.", "properties": { "basicItemData": { "$ref": "#/components/schemas/BasicItemData", "description": "General data regarding item such as name, price, etc." }, "beneficiaries": { "description": "List of all entities receiving or using purchased item (Recipients of physical or digital goods, passengers of transport services, guests of accommodation services, etc.)", "items": { "$ref": "#/components/schemas/Beneficiary" }, "type": "array", "nullable": true }, "deliveryDetails": { "allOf": [ { "$ref": "#/components/schemas/DeliveryDetails", "description": "Delivery details used for this item. Required if different items have different delivery information not specified in primaryDeliveryDetails" }, { "type": "object", "nullable": true } ] }, "itemReturnData": { "allOf": [ { "$ref": "#/components/schemas/ReturnData", "description": "Data relating to the return of the item" }, { "type": "object", "nullable": true } ] }, "itemSpecificData": { "allOf": [ { "$ref": "#/components/schemas/ItemSpecificData" }, { "type": "object", "nullable": true } ] }, "pendingAddition": { "description": "Indicates whether the item is pending decision to be added to cart", "type": "boolean", "nullable": true }, "seller": { "allOf": [ { "$ref": "#/components/schemas/SellerData", "description": "Data relating to vendor or other marketplace participant selling this item" }, { "type": "object", "nullable": true } ] }, "shopifyAdditionalItemData": { "allOf": [ { "$ref": "#/components/schemas/ShopifyAdditionalItemData", "description": "Additional data regarding Shopify cart item" }, { "type": "object", "nullable": true } ] } }, "required": [ "basicItemData" ], "type": "object" }, "ItemSpecificData": { "additionalProperties": false, "description": "These are the details relating to the particular item purchased. This object should be used whenever additional industry specific data is available on a cart item", "properties": { "accommodation": { "allOf": [ { "$ref": "#/components/schemas/AccommodationItem", "description": "Additional information regarding accommodation services or products" }, { "type": "object", "nullable": true } ] }, "cryptocurrency": { "allOf": [ { "$ref": "#/components/schemas/CryptoItem", "description": "Additional information regarding cryptocurrency purchases" }, { "type": "object", "nullable": true } ] }, "digitalGoodsAndServices": { "allOf": [ { "$ref": "#/components/schemas/ServiceItem", "description": "Additional information regarding digital goods and services" }, { "type": "object", "nullable": true } ] }, "food": { "allOf": [ { "$ref": "#/components/schemas/FoodItem", "description": "Additional information regarding food orders" }, { "type": "object", "nullable": true } ] }, "gaming": { "allOf": [ { "$ref": "#/components/schemas/GamingItem", "description": "Additional information regarding gaming related items or products" }, { "type": "object", "nullable": true } ] }, "personNameRecord": { "description": "Person Name Record (PNR). Combined with a passenger name, it serves as an identifier for a flight reservation (also for multiple passengers)", "maxLength": 20, "type": "string", "example": "P52DKC", "nullable": true }, "physicalGoods": { "allOf": [ { "$ref": "#/components/schemas/PhysicalItem", "description": "Additional information regarding physical goods" }, { "type": "object", "nullable": true } ] }, "professionalServices": { "allOf": [ { "$ref": "#/components/schemas/ProfessionalServices", "description": "Additional information regarding professional services, such as event planning, web design, etc." }, { "type": "object", "nullable": true } ] }, "ticketsAndEvents": { "allOf": [ { "$ref": "#/components/schemas/TicketItem", "description": "Additional information regarding ticket and events related items or products" }, { "type": "object", "nullable": true } ] }, "transport": { "description": "Additional information regarding transportation services or products", "items": { "$ref": "#/components/schemas/TransportItem" }, "type": "array", "nullable": true } }, "type": "object" }, "ListProperties": { "additionalProperties": false, "description": "An abstract representation of a list of items such as a wishlist.", "properties": { "inUse": { "description": "Indicates whether the feature is in use, for example if a customer is subscribed to a newsletter, has items in his wishlist etc.", "type": "boolean", "example": true, "nullable": true }, "itemInListCount": { "description": "Number of items in the list", "type": "integer", "example": 4, "nullable": true }, "updateTimes": { "allOf": [ { "$ref": "#/components/schemas/UpdateTimes", "description": "Times of first and last usage or addition to the list" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "Location": { "additionalProperties": false, "description": "An object that contains either exact or broad information about a physical location associated with the transaction or customer.", "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address", "description": "Address details" }, { "type": "object", "nullable": true } ] }, "exactLocation": { "allOf": [ { "$ref": "#/components/schemas/ExactLocation", "description": "Exact location details (Lat/Lon)" }, { "type": "object", "nullable": true } ] }, "locationName": { "allOf": [ { "$ref": "#/components/schemas/LocationName", "description": "Specific location name details" }, { "type": "object", "nullable": true } ] }, "roughLocation": { "allOf": [ { "$ref": "#/components/schemas/RoughLocation", "description": "General location details (city-level)", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "savedLocation": { "allOf": [ { "$ref": "#/components/schemas/SavedData", "description": "Additional information about a location in case it has been saved in the user account preferences" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "LocationName": { "additionalProperties": false, "description": "An object that contains the name of a physical location, either as submitted by the end-user, or as assigned by the merchant.", "properties": { "isTextSearchResult": { "description": "Set to true if the user searched for the location name to find the exact location (as opposed to location being generated by the app based on device location)", "type": "boolean", "example": false, "nullable": true }, "specificLocationName": { "description": "Specific location name. Can be used for locations named by the end-user (e.g. \"Beth's office\") or for merchant assigned names (based on 3rd party tools or other sources)", "type": "string", "example": "Times Square", "nullable": true }, "specificLocationType": { "description": "Specific location type.", "type": "string", "example": "Event", "nullable": true } }, "type": "object" }, "PhysicalItem": { "additionalProperties": false, "description": "If the item purchased is a physical item, this gives further details describing the item more precisely.", "properties": { "wrapAsGift": { "description": "True if customer chose to have item wrapped as a gift", "type": "boolean", "example": true, "nullable": true } }, "type": "object" }, "PointOfSaleDetails": { "additionalProperties": false, "description": "Point of sale information.", "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address", "description": "Store address details", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "cardEntryMethod": { "description": "Credit card entry method", "enum": [ "SCANNED", "HAND_KEYED", "CHIP_READ", "UNKNOWN", "SAVED_IN_ACCOUNT", "SWIPED" ], "example": "SCANNED" }, "cashierId": { "description": "Employee identifier", "maxLength": 40, "type": "string", "example": "fgh5e0rr48923d" }, "departmentId": { "description": "Unique store department identifier", "maxLength": 40, "type": "string", "example": "e0r4592356fds" }, "storeBusinessUnit": { "description": "Store business unit", "maxLength": 40, "type": "string", "example": "Full Line" }, "storeId": { "description": "Unique store identifier", "maxLength": 40, "type": "string", "example": "2356fdse0rr489" }, "storeName": { "description": "Store name", "maxLength": 40, "type": "string", "example": "Union Square" }, "workStationId": { "description": "Unique work-station identifier", "maxLength": 40, "type": "string", "example": "923e5th5e0rr48" } }, "required": [ "storeId", "storeName", "storeBusinessUnit", "departmentId", "cashierId", "workStationId", "cardEntryMethod" ], "type": "object" }, "ProfessionalServices": { "additionalProperties": false, "description": "Additional information regarding professional services, such as event planning, web design, etc.", "properties": { "numberOfParticipatingClients": { "description": "Number of clients associated with this service. Would be greater than 1 in cases where the service is given to multiple clients, for example, a bride and a groom at a wedding.", "type": "number", "x-conditional": true, "example": 1, "nullable": true }, "numberOfParticipatingVendors": { "description": "Number of vendors associated with this service. Would be greater than 1 in cases where several vendors collaborate to offer the service.", "type": "number", "x-conditional": true, "example": 1, "nullable": true }, "tipAmount": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Tip paid in advanced by customer", "x-conditional": true }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "Rating": { "additionalProperties": false, "description": "With the increasingly peer-led, peer-reviewed, highly social nature of online commerce, ratings are often available connected to the customer or the purchase.", "properties": { "score": { "description": "Rating score (numeric - 97 or textual - 'Excellent')", "maxLength": 25, "type": "string", "example": "4.5", "nullable": true }, "source": { "description": "Source of rating, for example tripAdvisor, yelp, etc.", "maxLength": 50, "type": "string", "example": "yelp", "nullable": true }, "type": { "description": "Rating type. Internal if rating was generated within the merchant's site or community, otherwise external.", "enum": [ "INTERNAL_PEERS", "INTERNAL_MERCHANT", "EXTERNAL_PEERS", "EXTERNAL_INDEPENDENT" ], "example": "INTERNAL_PEERS", "nullable": true } }, "type": "object" }, "ReturnData": { "additionalProperties": false, "description": "Additional data about the return", "properties": { "posDetails": { "allOf": [ { "$ref": "#/components/schemas/PointOfSaleDetails", "description": "Point of sale details for items returned in-store" }, { "type": "object", "nullable": true } ] }, "returnCondition": { "description": "Condition of the item returned", "maxLength": 40, "type": "string", "example": "DAMAGED", "nullable": true }, "returnInternalReasonCategory": { "description": "The reason for the return as defined by the merchant", "maxLength": 40, "type": "string", "example": "defective item", "nullable": true }, "returnMethod": { "description": "Method of return, e.g. online, in-store", "enum": [ "ONLINE", "IN-STORE" ], "example": "ONLINE", "nullable": true }, "returnReasonCategory": { "description": "Reason for return", "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", "ENTIRE_ORDER_NOT_RECEIVED", "OUTBOUND_ISSUE_CARRIER", "OUTBOUND_ISSUE_MERCHANT", "FAILED_DELIVERY", "INBOUND_LOSS", "INBOUND_ISSUE_CARRIER" ], "example": "CHANGED_MY_MIND", "nullable": true }, "returnSegment": { "description": "Specific return segment as defined by the merchant", "maxLength": 40, "type": "string", "example": "GENERAL", "nullable": true }, "returnStatusLog": { "allOf": [ { "$ref": "#/components/schemas/ReturnStatusLog", "description": "Status of the return process (e.g. initiated by customer, shipped, arrived to warehouse)", "maxLength": 40 }, { "type": "object", "nullable": true } ] }, "typeOfCompensationRequested": { "description": "Indicates whether the customer requested a refund, store credit, replacement etc.", "enum": [ "REPLACEMENT", "REFUND", "REFUND_UPON_RETURN", "CREDIT", "MIXED", "UNKNOWN", "NO_COMPENSATION" ], "example": "REFUND", "nullable": true }, "updatedReturnStatus": { "description": "The updated status of the return on the merchant's side", "enum": [ "ACCEPTED_BY_MERCHANT", "REJECTED_BY_MERCHANT", "PARTIALLY_ACCEPTED_BY_MERCHANT" ], "x-conditional": true, "example": "ACCEPTED_BY_MERCHANT", "nullable": true } }, "type": "object" }, "ReturnStatusLog": { "additionalProperties": false, "description": "Status of the return process", "properties": { "arrivedToWarehouse": { "description": "Indicates that the returned items arrived to the merchant's warehouse", "type": "boolean", "example": true, "nullable": true }, "arrivedToWarehouseTime": { "description": "Time returned items arrived to the merchant's warehouse", "type": "number", "example": 1420070400000, "nullable": true }, "returnInitiated": { "description": "Indicates that the customer initiated a return process online", "type": "boolean", "example": true, "nullable": true }, "returnInitiationTime": { "description": "Time online return was initiated", "type": "number", "example": 1420070400000, "nullable": true }, "shippedByCustomer": { "description": "Indicates that the customer has shipped the returned items back to the merchant", "type": "boolean", "example": true, "nullable": true }, "shippedByCustomerTime": { "description": "Time returned items were shipped by the customer", "type": "number", "example": 1420070400000, "nullable": true } }, "type": "object" }, "RoughLocation": { "additionalProperties": false, "description": "General location (city level)", "properties": { "airportCode": { "description": "Three letter IATA airport code", "pattern": "[A-Z]{3}", "type": "string", "x-conditional": true, "example": "JFK", "nullable": true }, "city": { "description": "City", "type": "string", "example": "Anytown", "nullable": true }, "country": { "description": "Country, two-letter ISO 3166-1 alpha-2 country code", "maxLength": 2, "pattern": "[A-Za-z]{2}", "type": "string", "x-conditional": true, "example": "DK", "nullable": true }, "region": { "description": "Top-level administrative subdivision - state/province/department/etc.", "type": "string", "x-conditional": true, "example": "New York", "nullable": true }, "seaportCode": { "description": "Five letter seaport code", "pattern": "[A-Z]{5}", "type": "string", "x-conditional": true, "example": "USNYC", "nullable": true } }, "type": "object" }, "SellerData": { "additionalProperties": false, "description": "This reflects the information known about the seller.", "properties": { "sellerBusinessWebsite": { "description": "Seller's business website URL", "type": "string", "example": "www.acme-events.net", "nullable": true }, "sellerCategory": { "description": "Type of service offered by the seller", "type": "string", "example": "Event Planner", "nullable": true }, "sellerDetails": { "$ref": "#/components/schemas/BasicSellerData", "description": "Basic information regarding seller" }, "sellerVendorName": { "description": "Name of the vendor", "type": "string", "example": "Acme Event Planners Inc.", "nullable": true } }, "required": [ "sellerDetails" ], "type": "object" }, "ServiceItem": { "additionalProperties": false, "description": "Service Item is used for services sold such as subscriptions, outsourcing projects, etc.", "properties": { "automaticRenewal": { "description": "True if customer chose to have service automatically renewed once current service ends", "type": "boolean", "example": true, "nullable": true }, "billingFrequency": { "description": "The frequency customer has chosen for billing", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "SEMI_ANNUAL", "ANNUAL", "MULTI_ANNUAL", "OTHER" ], "x-conditional": true, "example": "MONTHLY", "nullable": true }, "duration": { "allOf": [ { "$ref": "#/components/schemas/Duration", "description": "Duration service or item is available" }, { "type": "object", "nullable": true } ] }, "isTrial": { "description": "True if the product\\service begins with a free trial", "type": "boolean", "x-conditional": true, "example": false, "nullable": true }, "webHosting": { "allOf": [ { "$ref": "#/components/schemas/WebHostingItem", "description": "Extra information for webhosting services" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "ShopifyAdditionalItemData": { "additionalProperties": false, "description": "Object for additional Shopify cart item data", "properties": { "properties": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Shopify cart item properties" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "TicketItem": { "additionalProperties": false, "description": "Ticket Item is used for tickets and events.", "properties": { "eventLocation": { "allOf": [ { "$ref": "#/components/schemas/Address", "description": "Location of the event. If not held in one place, use starting point" }, { "type": "object", "nullable": true } ] }, "eventName": { "description": "Name of the event", "type": "string", "example": "FIFA World Cup Final" }, "eventTime": { "description": "Time of event in seconds since unix epoch (UTC, Jan 1, 1970). For example, 01/01/2015 00:00 is 1420070400", "type": "number", "example": 1420070400, "nullable": true }, "eventType": { "description": "Type of event (movie, concert, sports, etc.)", "maxLength": 100, "type": "string", "example": "sports", "nullable": true }, "eventVenueName": { "description": "Name of venue where event takes place", "type": "string", "example": "Maracana Stadium", "nullable": true }, "ticketCategory": { "description": "Ticket category (adult, student, senior, child, etc.)", "enum": [ "ADULT", "CHILD", "ENFANT", "SENIOR", "STUDENT", "VETERAN", "OTHER" ], "maxLength": 25, "example": "ADULT", "nullable": true }, "ticketClass": { "description": "Class of tickets purchased (Standing, VIP, Platinum, etc.)", "maxLength": 25, "type": "string", "example": "court side", "nullable": true } }, "required": [ "eventName" ], "type": "object" }, "TransportItem": { "additionalProperties": false, "description": "In cases where transport of some sort has been purchased, Transport Item gives further information regarding the details of the purchased transportation.", "properties": { "bookingSource": { "description": "Use to indicate the affiliate, origin, internal source or flow that this part of the booking is associated with", "type": "string", "x-conditional": true, "example": "82", "nullable": true }, "carrier": { "description": "Company operating transportation service purchased (airline, car rental company, etc.)", "type": "string", "x-conditional": true, "example": "Forter airlines", "nullable": true }, "class": { "description": "Seating class (Tourist, business, first, etc.)", "maxLength": 100, "type": "string", "example": "BUSINESS", "nullable": true }, "driverDetails": { "allOf": [ { "$ref": "#/components/schemas/BasicSellerData", "description": "Basic information regarding driver" }, { "type": "object", "nullable": true } ] }, "duration": { "allOf": [ { "$ref": "#/components/schemas/ExactDuration", "description": "Duration of trip", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "endPoint": { "allOf": [ { "$ref": "#/components/schemas/Location", "description": "Trip end point", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "expeditedBoarding": { "description": "True if customer paid extra for expedited boarding", "type": "boolean", "example": false, "nullable": true }, "extraBaggage": { "description": "True if customer paid extra to bring extra baggage", "type": "boolean", "example": false, "nullable": true }, "leg": { "description": "Use to indicate the order of arrival to each point on the route. Original departure point should get leg=0, first connection should get leg=1, etc. final destination should get leg=(number of stops-1)", "type": "integer", "x-conditional": true, "example": 2, "nullable": true }, "locationAtTimeOfReservation": { "allOf": [ { "$ref": "#/components/schemas/Location", "description": "Location of customer as recorded at the time of reservation (through mobile phone GPS or equivalent)" }, { "type": "object", "nullable": true } ] }, "passengers": { "description": "Number of passengers", "type": "number", "example": 2, "nullable": true }, "purchasedMeals": { "description": "True if customer paid extra to receive meals on board", "type": "boolean", "example": false, "nullable": true }, "selectSeat": { "description": "True if customer paid extra to select a seat", "type": "boolean", "example": false, "nullable": true }, "startPoint": { "$ref": "#/components/schemas/Location", "description": "Trip starting point" }, "type": { "description": "Type of transportation service", "enum": [ "PRIVATE_TAXI", "PRIVATE_VIP_TAXI", "PRIVATE_LARGE_TAXI", "SHARED_RIDE", "SHARED_RIDE_DISCOUNT", "AIR_TRAVEL", "RAIL", "FERRY", "BUS", "CAR_RENTAL", "PARKING", "CRUISE_LINE" ], "example": "AIR_TRAVEL" } }, "required": [ "type", "startPoint" ], "type": "object" }, "UpdateTimes": { "additionalProperties": false, "description": "This provides information regarding the times associated with any updates made to the account or transaction.", "properties": { "creationTime": { "description": "Time item was first entered by customer in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1448549922, "nullable": true }, "lastModifiedTime": { "description": "Time item was last modified by the customer in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1448549922, "nullable": true }, "lastUsed": { "description": "Time item was last used by customer in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1448560456, "nullable": true }, "removalTime": { "description": "Time item was removed by customer in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1448895522, "nullable": true } }, "type": "object" }, "WebHostingItem": { "additionalProperties": false, "description": "Details relating to web hosting related items or products", "properties": { "SSLcertificates": { "description": "True if customer asked or paid extra for SSL certificates to be included", "type": "boolean", "x-conditional": true, "example": false, "nullable": true }, "domains": { "description": "List of domains purchased", "items": { "type": "string" }, "type": "array", "example": [ "testforterdomain.com", "testforterdomain.me" ], "nullable": true }, "emailService": { "description": "True if customer asked or paid extra for Email functionality", "type": "boolean", "x-conditional": true, "example": false, "nullable": true }, "privateRegistration": { "description": "True if customer asked or paid extra to hide registrant details from whois services", "type": "boolean", "x-conditional": true, "example": false, "nullable": true }, "sercurityUpgrades": { "description": "True if customer asked or paid extra for security upgrades (antivirus, firewall, etc.)", "type": "boolean", "x-conditional": true, "example": false, "nullable": true }, "webPromotion": { "description": "True if customer asked or paid extra for promotion services such as SEO", "type": "boolean", "x-conditional": true, "example": false, "nullable": true }, "websiteBuilder": { "description": "True if customer asked or paid extra for website builder wizard services", "type": "boolean", "x-conditional": true, "example": false, "nullable": true } }, "type": "object" }, "accountItemListingRequest": { "additionalProperties": false, "description": "Send information about a seller's new inventory in order to receive a fraud or abuse decision.", "properties": { "accountData": { "allOf": [ { "$ref": "#/components/schemas/AccountData", "description": "Details about the buyer/seller account, including account status" }, { "type": "object", "nullable": true } ] }, "accountId": { "description": "Customer's account UID in merchant's site. Should not be the user email.", "maxLength": 100, "type": "string", "example": "e520-ba9a-367-60b" }, "additionalInformation": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Additional information not described in the documentation." }, { "type": "object", "nullable": true } ] }, "channelType": { "description": "The source channel through which the user added the item listing. Note that some of the enum values are not relevant for this interaction.", "enum": [ "WEB", "PHONE", "DYNAMIC_PHONE", "MOBILE", "MOBILE_IN_STORE", "IOS", "ANDROID", "WAP", "STORE", "MERCHANT_EMPLOYEE", "MAIL_ORDER", "AUTOMATIC_RENEWAL_OR_INSTALLMENT_PAYMENT", "MERCHANT_INITIATED", "UNKNOWN", "POS", "API_ONLY", "PERSONAL_POS", "PHONE_LINK", "AI_AGENT" ], "x-conditional": true, "example": "WEB", "nullable": true }, "connectionInformation": { "$ref": "#/components/schemas/ConnectionInformation", "description": "Connection information about the customer typically found in the HTTP request header." }, "eventTime": { "description": "The time that the trigger event occurred in MILLISECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1415287568000 }, "listedItems": { "description": "A list of all newly listed items in the seller account", "items": { "$ref": "#/components/schemas/Item" }, "type": "array" }, "merchantIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/MerchantIdentifiers", "description": "General identifiers of the transaction from the merchant's systems" }, { "type": "object", "nullable": true } ] } }, "required": [ "accountId", "eventTime", "connectionInformation", "listedItems" ], "type": "object" }, "CustomerRegistrationSources": { "additionalProperties": false, "description": "Customer Signed-In Using -", "properties": { "facebook": { "description": "Facebook", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "google": { "description": "Google", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "linkedin": { "description": "LinkedIn", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "otherSocialNetwork": { "description": "Other Social Network", "maxLength": 50, "type": "string", "example": "VK", "nullable": true }, "paypal": { "description": "PayPal", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "twitter": { "description": "Twitter", "maxLength": 50, "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "UserLoginInput": { "additionalProperties": false, "description": "Input details submitted by the user", "properties": { "additionalInformation": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Additional information not described in the documentation." }, { "type": "object", "nullable": true } ] }, "customerSignedInUsingSocialNetworkAccount": { "allOf": [ { "$ref": "#/components/schemas/CustomerRegistrationSources", "description": "Account owner logged-in using a Social Network account", "maxLength": 50 }, { "type": "object", "nullable": true } ] }, "email": { "description": "Email address. Required when the input type is EMAIL.", "maxLength": 75, "type": "string", "x-conditional": true, "example": "john_s@test.com", "nullable": true }, "inputType": { "description": "The type of identifier used by the user to login", "enum": [ "USERNAME", "EMAIL", "PHONE", "SOCIAL" ], "example": "EMAIL" }, "phone": { "description": "Phone number including all country and local access codes. Required when the input type is PHONE.", "maxLength": 25, "type": "string", "x-conditional": true, "example": "15557654321", "nullable": true } }, "required": [ "inputType" ], "type": "object" }, "accountLoginRequest": { "additionalProperties": false, "description": "Send login attempt information to receive an account takeover decision. May also be used to determine whether to extend a user's idle session without prompting user for credentials. The response may also include recommendations for additional authentication (MFA) and a correlation ID to include with the authentication result.", "properties": { "accountData": { "allOf": [ { "$ref": "#/components/schemas/AccountData", "description": "Details about the buyer/seller account, including account status" }, { "type": "object", "nullable": true } ] }, "accountId": { "description": "Customer's account UID in merchant's site. Should not be the user email.", "maxLength": 100, "type": "string", "example": "e520-ba9a-367-60b" }, "additionalAuthenticationMethod": { "allOf": [ { "$ref": "#/components/schemas/AdvancedAuthenticationMethod", "description": "Additional details in case advanced authentication methods were used (e.g. MFA, OTP)", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "channelType": { "description": "The source channel through which the customer conducted the login. Note that some of the enum values are not relevant for this interaction.", "enum": [ "WEB", "PHONE", "DYNAMIC_PHONE", "MOBILE", "MOBILE_IN_STORE", "IOS", "ANDROID", "WAP", "STORE", "MERCHANT_EMPLOYEE", "MAIL_ORDER", "AUTOMATIC_RENEWAL_OR_INSTALLMENT_PAYMENT", "MERCHANT_INITIATED", "UNKNOWN", "POS", "API_ONLY", "PERSONAL_POS", "PHONE_LINK", "AI_AGENT" ], "x-conditional": true, "example": "WEB", "nullable": true }, "connectionInformation": { "$ref": "#/components/schemas/ConnectionInformation", "description": "Connection information about the customer typically found in the HTTP request header." }, "eventTime": { "description": "The time that the trigger event occurred in MILLISECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1415287568000 }, "loginMethodType": { "description": "The authentication method used to login", "enum": [ "PASSWORD", "SMS", "SOCIAL", "EMAIL_LINK_OTP", "AUTH_TOKEN_REFRESH", "APPLE", "MFA_CODE_REFRESH", "EMAIL_MAGIC_LINK", "PASSKEY", "QR", "OTHER" ], "example": "PASSWORD" }, "loginStatus": { "description": "The status of the Login attempt", "enum": [ "SUCCESS", "FAILED", "BLOCKED_BY_MERCHANT", "ACCOUNT_DOES_NOT_EXIST" ], "example": "SUCCESS" }, "merchantIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/MerchantIdentifiers", "description": "If a merchant operates a number of sites, Merchant Identifiers help Forter's system to identify the right site." }, { "type": "object", "nullable": true } ] }, "userInput": { "$ref": "#/components/schemas/UserLoginInput", "description": "Input details submitted by the user. Required in case Forter does not have a full list of merchant account details" } }, "required": [ "accountId", "eventTime", "connectionInformation", "loginMethodType", "loginStatus", "userInput" ], "type": "object" }, "accountSignupRequest": { "additionalProperties": false, "description": "Send account registration information at signup to receive a fraud or abuse decision.", "properties": { "accountData": { "allOf": [ { "$ref": "#/components/schemas/AccountData", "description": "Details about the buyer/seller account collected during the registration process", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "accountId": { "description": "Customer's account UID in merchant's site. Should not be the user email. If no account ID is available send NO_ACCOUNT_ID", "maxLength": 100, "type": "string", "example": "e520-ba9a-367-60b" }, "additionalAccountEventIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/AdditionalAccountEventIdentifiers", "description": "Additional identifiers of the account event." }, { "type": "object", "nullable": true } ] }, "additionalInformation": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Additional information not described in the documentation." }, { "type": "object", "nullable": true } ] }, "channelType": { "description": "The source channel through which the customer conducted the signup. Note that some of the enum values are not relevant for this interaction.", "enum": [ "WEB", "PHONE", "DYNAMIC_PHONE", "MOBILE", "MOBILE_IN_STORE", "IOS", "ANDROID", "WAP", "STORE", "MERCHANT_EMPLOYEE", "MAIL_ORDER", "AUTOMATIC_RENEWAL_OR_INSTALLMENT_PAYMENT", "MERCHANT_INITIATED", "UNKNOWN", "POS", "API_ONLY", "PERSONAL_POS", "PHONE_LINK", "AI_AGENT" ], "x-conditional": true, "example": "WEB", "nullable": true }, "connectionInformation": { "$ref": "#/components/schemas/ConnectionInformation", "description": "Connection information about the customer typically found in the HTTP request header." }, "customerSignedInUsingSocialNetworkAccount": { "allOf": [ { "$ref": "#/components/schemas/CustomerRegistrationSources", "description": "Account owner signed-in using a Social Network account", "maxLength": 50, "x-conditional": true }, { "type": "object", "nullable": true } ] }, "eventTime": { "description": "The time that the trigger event occurred in MILLISECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1415287568000 }, "merchantIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/MerchantIdentifiers", "description": "If a merchant operates a number of sites, Merchant Identifiers help Forter's system to identify the right site." }, { "type": "object", "nullable": true } ] }, "promotions": { "allOf": [ { "$ref": "#/components/schemas/Discount", "description": "Coupons or promotion codes used by the user when creating the account" }, { "type": "object", "nullable": true } ] }, "signupStatus": { "description": "The status of the Signup attempt", "enum": [ "SUCCESS", "FAILED", "BLOCKED_BY_MERCHANT" ], "example": "SUCCESS", "nullable": true } }, "required": [ "accountId", "eventTime", "connectionInformation" ], "type": "object" }, "accountStatusUpdateRequest": { "additionalProperties": false, "description": "Inform of updates to the status of an account. While no decision is provided on this request, it improves the decision model.", "properties": { "accountEmail": { "description": "Customer's email address", "maxLength": 75, "type": "string", "example": "john_s@test.com", "nullable": true }, "accountId": { "description": "Customer's account UID in merchant's site. Should not be the user email.", "maxLength": 100, "type": "string", "example": "e520-ba9a-367-60b" }, "additionalInformation": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Additional information not described in the documentation." }, { "type": "object", "nullable": true } ] }, "connectionInformation": { "allOf": [ { "$ref": "#/components/schemas/ConnectionInformation", "description": "Connection information about the customer typically found in the HTTP request header. Required when the user conducts the update.", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "eventTime": { "description": "The time that the trigger event occurred in MILLISECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1415287568000 }, "merchantAccountStatus": { "description": "Account status as defined in the merchant's system", "type": "string", "x-conditional": true, "example": "open", "nullable": true }, "merchantIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/MerchantIdentifiers", "description": "If a merchant operates a number of sites, Merchant Identifiers help Forter's system to identify the right site." }, { "type": "object", "nullable": true } ] }, "status": { "description": "Account status", "enum": [ "ACTIVE", "SUSPENDED", "CLOSED", "GUEST", "PENDING" ], "example": "ACTIVE" }, "statusChangeBy": { "description": "The entity responsible for triggering the status change", "enum": [ "MERCHANT_ADMIN", "END_USER", "FORTER" ], "x-conditional": true, "example": "MERCHANT_ADMIN", "nullable": true }, "statusChangeReason": { "description": "The reason for the account status change. Required in case the update includes an account status change.", "type": "string", "x-conditional": true, "example": "user violation of coupon abuse policy", "nullable": true }, "type": { "description": "Account type (a business account, a private account, a merchant-operated account)", "enum": [ "GUEST", "PRIVATE", "BUSINESS", "VIP", "MERCHANT_OPERATED", "TRIAL", "MERCHANT_EMPLOYEE", "PREMIUM_PAID", "SMALL_BUSINESS", "AGENT", "BUSINESS_PRIVATE", "BUSINESS_PREMIUM_PAID" ], "x-conditional": true, "example": "BUSINESS", "nullable": true } }, "required": [ "accountId", "eventTime", "status" ], "type": "object" }, "ThreeDSecureResponse": { "additionalProperties": false, "description": "Complete 3DSecure payload", "properties": { "ACSUrl": { "description": "In case of challange, this url is needed to be passed to client side and trigger ftr__.init3DS function", "maxLength": 2048, "type": "string", "example": "https:/ /acs-us-east-1.nd.nds-sandbox-issuer.com/api/v1/acs/browser_sdk_challenges" }, "ECIValue": { "description": "Electronic Commerce Indicator (ECI) is a value that is returned from the Directory Server (Visa, MasterCard, etc) to indicate the authentication results of your customer's credit card payment on 3D Secure. ECI only available when the challenge is not needed or after challenge had been completed. Possible values: 00, 01, 02, 04, 05, 06, 07", "maxLength": 300, "type": "string", "example": "02" }, "acsChallengeMandated": { "description": "Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable (Y - Challenge is mandated, N - Challenge is not mandated)", "maxLength": 1, "type": "string", "example": "Y" }, "acsReferenceNumber": { "description": "Unique identifier assigned by the EMVCo Secretariat = required for mobile app implementation", "maxLength": 32, "type": "string", "example": "ftr-internal-acs-approval" }, "acsSignedContent": { "description": "ACS Signed Content required for mobile app implementation", "maxLength": 1000, "type": "string", "example": "" }, "acsTransID": { "description": "Universally Unique transaction identifier assigned by the ACS to identify a single transaction - required for mobile app implementation", "maxLength": 36, "type": "string", "example": "6fd30e89-8171-4cc3-b86e-3d59582af2f6" }, "authenticationType": { "description": "Optional authentication type (01 - Static, 02 - Dynamic, 03 - OOB, 04 - Decoupled)", "maxLength": 2, "type": "string", "example": "01" }, "authenticationValue": { "description": "3DS Authentication value (AV) should be sent to the payment gateway in the authorization call", "maxLength": 28, "type": "string", "example": "tSvPDt3PINNaoL+ERXdg0jVrmWc=" }, "bankLiabilityShift": { "description": "Indicates whether transaction is supposed to get liability shift from issuer", "maxLength": 1, "type": "boolean", "example": true }, "cardEnrolled": { "description": "3DS transaction card Enrolled status - should be sent to the payment gateway in the authorization call in some payment gateways", "maxLength": 1, "type": "string", "example": "Y" }, "cavvAlgorithm": { "description": "3DS Authentication value algorithm - should be sent to the payment gateway in the authorization call in some payment gateways. Possible values (3DS1 only): 0, 1, 2, 3, 4, 7", "maxLength": 1, "type": "string", "example": "3" }, "challengeCancel": { "description": "Indicator informing the ACS and the DS that the authentication has been canceled. Possible values: 01-99", "maxLength": 2, "type": "string", "example": "01" }, "challengeStatus": { "description": "Ares transStatus value (Possible values: U, N, Y, A, C, D, R, I)", "maxLength": 1, "type": "string", "example": "Y" }, "dsTransID": { "description": "Universally unique transaction identifier assigned by the DS to identify a single transaction", "maxLength": 100, "type": "string", "example": "38bbf46f-c023-4f4c-ae2c-35fb301632a5" }, "encodedChallengeRequest": { "description": "This value will only be available when challenge is needed, in the challenge flow - this must be passed to browser in order to trigger the challenge", "type": "string", "example": "eyJhY3NUcmFuc0lEIjoiMTEyY2RiNWItMGFlYy00MTY5LThjMWYtYWMyN2JlNjAxMjhhIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0IiwibWVzc2FnZVZlcnNpb24iOiIyLjEuMCIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiZWRhM2MwMzYtZWMyYS00NmZkLTlmYWItNzBlZTgyYjJjNzQ5In0=" }, "exemption": { "description": "Exemption that should be used during the authorization process", "enum": [ "LOW_VALUE", "TRANSACTION_RISK_ANALYSIS", "SECURE_CORPORATE", "TRUSTED_BENEFICIARY" ], "example": "TRANSACTION_RISK_ANALYSIS", "nullable": true }, "interactionCounter": { "description": "Indicates the number of authentication cycles attempted by the Cardholder", "maxLength": 2, "type": "string", "example": "01" }, "isFallback": { "description": "Indication of whether a 3DS1 challenge was performed as a fallback to 3DS2 error", "maxLength": 5, "type": "boolean", "example": false }, "messageCategory": { "description": "Identifies the category of the message for a specific use case (01 - PA, 02 - NPA)", "maxLength": 2, "type": "string", "example": "01" }, "outOfScopeForPSD2": { "description": "This field indicate if transaction is out of scope for PSD2 and exclusion should be requested", "enum": [ "ANONYMOUS_PREPAID_CARD", "MERCHANT_INITIATED_TRANSACTIONS", "ONE_LEG_OUT_EEA", "MAIL_ORDER_TELEPHONE_ORDER" ], "example": "ANONYMOUS_PREPAID_CARD", "nullable": true }, "threeDSServerTransID": { "description": "Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction (in 3DS1 equal to XID)", "maxLength": 100, "type": "string", "example": "26d648a9-da8a-4f8b-a76d-094801d2fd45" }, "threeDSecureMode": { "description": "Indicate if the transaction is Frictionless or SCA. Being used by some payment gateways. Possible values: sca, frictionless", "maxLength": 15, "type": "string", "example": "sca" }, "threeDSecurePreference": { "description": "The challenge indicator used. Being used by some payment gateways. Possible values: nopref, frictionless, sca, scamandate", "maxLength": 15, "type": "string", "example": "nopref" }, "threeDSecureResult": { "description": "This field is relevant for 3DS1 and being used by some payment gateways", "maxLength": 6, "type": "string", "example": "590040" }, "transStatus": { "description": "3DS transStatus value - Indicates whether a transaction qualifies as an authenticated transaction or account verification. should be sent to the payment gateway in the authorization call (Possible values: U, N, Y, A, C, D, R, I)", "maxLength": 1, "type": "string", "example": "Y" }, "transStatusReason": { "description": "Provides information on why the Transaction Status field has the specified value. Possible values: 01-99", "maxLength": 2, "type": "string", "example": "01" }, "verifyStatus": { "description": "Cres transStatus value (Possible values: U, N, Y, A, C, D, R, I, null)", "maxLength": 1, "type": "string", "example": "Y" }, "version": { "description": "Version. Possible values: 1.0.2, 2.1.0, 2.2.0", "maxLength": 50, "type": "string", "example": "2.1.0" } }, "required": [ "encodedChallengeRequest", "ACSUrl", "ECIValue", "version", "authenticationValue", "authenticationType", "transStatus", "challengeStatus", "verifyStatus", "bankLiabilityShift", "cavvAlgorithm", "cardEnrolled", "acsTransID", "acsReferenceNumber", "acsSignedContent", "dsTransID", "threeDSServerTransID", "messageCategory", "transStatusReason", "challengeCancel", "interactionCounter", "acsChallengeMandated", "isFallback", "threeDSecureMode", "threeDSecureResult", "threeDSecurePreference" ], "type": "object" }, "VerificationData": { "additionalProperties": false, "description": "Details of the specific element that requires verification", "properties": { "ThreeDS": { "allOf": [ { "$ref": "#/components/schemas/ThreeDSecureResponse", "description": "3DS data", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "email": { "allOf": [ { "$ref": "#/components/schemas/Email", "description": "Email data", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "phone": { "allOf": [ { "$ref": "#/components/schemas/Phone", "description": "Phone data", "x-conditional": true }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "VerificationMethod": { "additionalProperties": false, "description": "A specific element that requires verification in order to approve a transaction, and its current status in the verification process", "properties": { "correlationId": { "description": "A forter unique identifier that was provided as part of a Forter API response recommending additional authentication measures. Used to correlate between the user action which triggered the recommendation and the authentication attempt result. Required when the additional authentication was triggered by Forter's recommendation.", "type": "string", "example": "HGJ7512345H3DE" }, "status": { "description": "Verification status", "maxLength": 50, "type": "string", "example": "FRICTIONLESS" }, "statusCode": { "description": "Verification status code", "maxLength": 50, "type": "string", "example": "100" }, "statusMessage": { "description": "Text describes the verification status", "maxLength": 50, "type": "string", "example": "Verification code sent" }, "type": { "description": "Verification method type", "enum": [ "OTP_SMS", "OTP_EMAIL", "THREE_DS" ], "maxLength": 50, "example": "THREE_DS" }, "verificationId": { "description": "A unique identifier assigned to that specific verification", "type": "string", "example": "345H3DEHGJ7512" }, "verificationSpecificData": { "$ref": "#/components/schemas/VerificationData", "description": "Data specific to the verification type performed" } }, "required": [ "verificationId", "correlationId", "type", "status", "verificationSpecificData", "statusCode", "statusMessage" ], "type": "object" }, "adaptiveAuthAccountsResponse": { "additionalProperties": false, "description": "Response structure for adaptive auth account requests", "properties": { "accountId": { "description": "When applicable, the customer's account UID in merchant's site", "type": "string", "example": "e520-ba9a-367-60b" }, "correlationId": { "description": "A forter unique identifier that should be sent to Forter as part of the AdvancedAuthenticationMethod object to correlate the MFA recommendation given in this response with the relevant additional authentication attempt result", "type": "string", "example": "HGJ7512345H3DE" }, "decisionReason": { "description": "The main reason behind the Forter decision", "maxLength": 1000, "type": "string", "example": "" }, "forterDecision": { "description": "The latest Forter decision regarding the attempted action", "enum": [ "APPROVE", "DECLINE", "VERIFICATION_REQUIRED", "NOT_REVIEWED" ], "example": "APPROVE" }, "merchantPolicyId": { "description": "UID of the custom policy created in Forter's Policies tool that resulted in this decision", "type": "string", "example": "0ee8ba28a8654c659addbae9253b707c" }, "recommendation": { "description": "A specific recommendation for an action that might help the customer to complete their transaction/action (e.g. verify phone via SMS, verify via push notification, verify email, perform a 3DS check, etc.)", "maxLength": 1000, "type": "string", "example": "" }, "verificationMethod": { "$ref": "#/components/schemas/VerificationMethod", "description": "The specific verification method to be used when verification is required according to \"recommendation\" field", "maxLength": 1000 } }, "required": [ "forterDecision", "recommendation", "verificationMethod", "decisionReason", "merchantPolicyId", "accountId", "correlationId" ], "type": "object" }, "ChargebackShippingInfo": { "additionalProperties": false, "description": "Chargeback Shipping Info", "properties": { "additionalShippingInfo": { "description": "Aditional identification document details and verification", "maxLength": 100, "type": "string", "example": "PO Box 3297", "nullable": true }, "carrier": { "description": "Shipping carrier name", "maxLength": 50, "type": "string", "example": "UPS", "nullable": true }, "proofOfShippingURL": { "description": "URL to the proof of shipping in the merchant's system", "maxLength": 1024, "type": "string", "example": "true", "nullable": true }, "signedProofOfShipping": { "description": "Whether the user has signed a proof of shipping", "type": "boolean", "example": true, "nullable": true }, "trackingNumber": { "description": "Order tracking number", "maxLength": 50, "type": "string", "example": "123456", "nullable": true } }, "type": "object" }, "claimRequest": { "additionalProperties": false, "description": "Inform of a dispute initiated by a customer. This endpoint should be used to report any disputes not already reported via webhook from the payment processor. While no decision is provided on this request, it is a required input that both improves the decision model and enables chargeback recovery.", "properties": { "additionalCost": { "$ref": "#/components/schemas/Amount", "description": "Additional fees associated with the claim such as processor fees or shipping recovery fees." }, "amount": { "$ref": "#/components/schemas/Amount", "description": "The amount representing the value of the goods that were not retrieved." }, "chargeId": { "description": "The unique identifier of the payment, such as Acquirer Reference Number (ARN).", "maxLength": 100, "type": "string", "example": "111111111", "nullable": true }, "chargebackShippingInfo": { "allOf": [ { "$ref": "#/components/schemas/ChargebackShippingInfo", "description": "Shipping information" }, { "type": "object", "nullable": true } ] }, "comments": { "description": "Additional comments by the merchant", "maxLength": 255, "type": "string", "x-conditional": true, "example": "Contacted customer via phone", "nullable": true }, "dueDate": { "description": "Due date for disputing the claim which was stated by the processor in case of a chargeback. Otherwise, the issue date. Use YYYY-MM-DD format.\nThe expected date timezone is UTC.", "format": "date", "type": "string", "example": "2016-01-30" }, "externalClaimStatus": { "description": "Detailed claim status in the claim source system", "maxLength": 100, "type": "string", "x-conditional": true, "example": "pending merchant response", "nullable": true }, "goodsRecovered": { "description": "Relevant only for the prechargeback claim type, in case the goods were not sent or delivered yet. Indication of whether or not the goods were recovered", "type": "boolean", "x-conditional": true, "example": false, "nullable": true }, "invoiceURL": { "description": "url to a copy of the invoice sent to the customer", "maxLength": 1024, "type": "string", "x-conditional": true, "example": "mystore.com/invoices/abc123", "nullable": true }, "issueDate": { "description": "Date the chargeback was issued / the prechargeback notification was sent. Use YYYY-MM-DD format.\nThe expected date timezone is UTC.", "format": "date", "type": "string", "example": "2016-01-20" }, "orderId": { "description": "Unique order/transaction identifier. Should match the order id sent to Forter at checkout. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.", "maxLength": 54, "type": "string", "x-conditional": true, "example": "4306795", "nullable": true }, "originalPayload": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Original payload from received from the claim source notification API" }, { "type": "object", "nullable": true } ] }, "processorChargebackCaseId": { "description": "The case number from the payment processor. (for BrainTree, please map the disputeId instead of caseNumber)", "maxLength": 75, "type": "string", "x-conditional": true, "example": "CB-4343343219", "nullable": true }, "processorName": { "description": "Payment processor name.", "enum": [ "Adyen", "Airwallex", "AmazonPay", "AMEX", "AuthorizeNet", "Be2bill", "BlueSnap", "Braintree", "BusinessTrack", "Chase", "Checkout", "Citcon", "Citibank", "ConcoraCredit", "Credorax", "Cybersource", "Dalenys", "Discover", "Dlocal", "Ebanx", "Elavon", "Fidelity", "FirstData", "Fiserv", "Fortis", "Globalpay", "Ingenico", "IQ", "Klarna", "MCP", "MerchantConnect", "Merlink", "MidTrans", "NCR", "Nuvei", "OceanPay", "OmniPayGroup", "Paymentech", "Paymenttech", "PayPal", "PayPlus", "PaySafe", "PayU", "PayUEastEurope", "PayULatam", "Privvy", "Przelewy", "Revolut", "Safecharge", "Shift4", "Shopify", "Sofort", "Sprint", "Square", "Stripe", "Vantiv", "Wirecard", "Worldline", "Worldnet", "WorldpayAccertify", "WorldpayDisputes", "WorldpayMAI", "WorldpayWDP", "Xendit", "Zen" ], "maxLength": 50, "example": "Braintree", "nullable": true }, "reason": { "description": "The claim reason as supplied by the claim source. For example, the chargeback reason provided in the chargeback notification.", "maxLength": 100, "type": "string", "x-conditional": true, "example": "Fraudulent Transaction: Card Not Present Environment", "nullable": true }, "reasonCode": { "description": "The claim code as supplied by the claim source. For example, the chargeback reason provided in the chargeback notification.", "maxLength": 50, "type": "string", "x-conditional": true, "example": "83", "nullable": true }, "reasonType": { "description": "The claim reason category type.", "enum": [ "FRAUD", "SERVICE", "OTHER", "AUTHORIZATION", "PROCESSING_ERROR" ], "example": "FRAUD" }, "sourceDetails": { "description": "Specifics about the source of the claim such as the processor name / 3rd party name, etc.", "type": "string", "x-conditional": true, "example": "UPS", "nullable": true }, "sourceType": { "description": "The category of the source of the claim.", "enum": [ "PROCESSOR_CB", "AMEX", "DISCOVER", "PAYPAL", "PROCESSOR_INQUIRY", "CUSTOMER_SUPPORT", "SHIPPING_CARRIER", "THIRD_PARTY", "FORTER", "OTHER" ], "example": "PROCESSOR_CB" }, "status": { "description": "Claim status mapping from the current status of the claim. For example, a mapping of the processor chargeback dispute status.", "enum": [ "OPEN", "IN_DISPUTE", "WON", "LOST", "CANCELED" ], "example": "OPEN" }, "type": { "description": "Type of claim.", "enum": [ "CHARGEBACK", "PRE_CHARGEBACK", "DEBIT_MEMO", "REQUEST_FOR_INFORMATION", "FRAUD_ALERT" ], "example": "CHARGEBACK" }, "wasRefunded": { "description": "Relevant only for the prechargeback claim type. Indication of whether or not the buyer was refunded", "type": "boolean", "x-conditional": true, "example": false, "nullable": true } }, "required": [ "status", "amount", "additionalCost", "type", "sourceType", "reasonType", "issueDate", "dueDate" ], "type": "object" }, "claimResponse": { "additionalProperties": false, "description": "The response object following claims request to the system", "properties": { "message": { "description": "The message containing status response text", "maxLength": 1000, "type": "string", "example": "Claim received" }, "status": { "description": "Status of the request processing", "maxLength": 50, "type": "string", "example": "success" } }, "required": [ "message", "status" ], "type": "object" }, "CustomerCorrespondence": { "additionalProperties": false, "properties": { "contactDateTime": { "description": "Date and time of the contact", "format": "date", "type": "string", "example": "2022-11-15", "nullable": true }, "contactDescription": { "description": "Description of the contact", "maxLength": 1000, "type": "string", "example": "Customer called to cancel the order", "nullable": true }, "contactId": { "description": "Contact ID", "maxLength": 100, "type": "string", "example": "contact-123" }, "contactReason": { "description": "Reason for the contact", "enum": [ "CANCELING", "EXCHANGE", "SICKNESS", "NAME_CHANGE", "INR", "OTHER" ], "example": "CANCELING", "nullable": true } }, "required": [ "contactId" ], "type": "object" }, "ProofOfCreditBalance": { "additionalProperties": false, "properties": { "amount": { "description": "Amount of the credit balance", "maxLength": 20, "type": "number", "example": 105.55, "nullable": true }, "appliedDate": { "description": "Date the credit balance was applied. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "2022-11-15" }, "currency": { "description": "Currency of the credit balance, 3-letter ISO-4217 format currency code", "maxLength": 3, "minLength": 3, "pattern": "[A-Z]{3}", "type": "string", "example": "USD", "nullable": true } }, "required": [ "appliedDate" ], "type": "object" }, "ProofOfDelivery": { "additionalProperties": false, "properties": { "carrier": { "description": "Shipping carrier name", "maxLength": 50, "type": "string", "x-conditional": true, "example": "UPS", "nullable": true }, "date": { "description": "Delivery date. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "2022-11-15", "nullable": true }, "deliveryStatus": { "description": "Current status of the delivery", "maxLength": 50, "type": "string", "example": "Delivered", "nullable": true }, "didCustomerSignForDelivery": { "description": "Whether the customer signed for the delivery", "type": "boolean", "example": false, "nullable": true }, "trackingNumber": { "description": "Order tracking number", "maxLength": 50, "type": "string", "example": "123456", "nullable": true } }, "type": "object" }, "ProofOfPickup": { "additionalProperties": false, "properties": { "pickupDate": { "description": "Date of the pickup. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "2022-11-15", "nullable": true }, "providedIdentityVerificationMethods": { "description": "List of methods used to verify customer identity", "items": { "enum": [ "PERSONAL_ID", "EMAIL_RECEIPT", "PAYMENT_METHOD", "ORDER_NUMBER" ] }, "type": "array", "example": [ "ORDER_NUMBER" ], "nullable": true }, "status": { "description": "Current status of the pickup", "enum": [ "NOT_PICKED_UP", "PICKED_UP" ], "example": "NOT_PICKED_UP" } }, "required": [ "status" ], "type": "object" }, "ProofOfRefund": { "additionalProperties": false, "properties": { "refundAmount": { "description": "Refund amount in currency chosen by the buyer", "maxLength": 20, "type": "number", "x-conditional": true, "example": 105.55, "nullable": true }, "refundAuthorizationCode": { "description": "Refund authorization code from payment gateway", "maxLength": 255, "type": "string", "x-conditional": true, "example": "B44233", "nullable": true }, "refundChargeId": { "description": "The unique identifier associated with the refund charge.\nFor example: ARN in Adyen, charge ID in Stripe, referenceNumber in Braintree, etc.", "maxLength": 100, "type": "string", "example": "111111111", "nullable": true }, "refundCurrency": { "description": "Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code", "maxLength": 3, "minLength": 3, "pattern": "[A-Z]{3}", "type": "string", "x-conditional": true, "example": "USD", "nullable": true }, "refundDate": { "description": "Date the refund was paid. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "2015-06-12", "nullable": true }, "refundTransactionId": { "description": "Refund transaction id", "maxLength": 50, "type": "string", "example": "ABC123" }, "replacementItems": { "description": "List of items that were replaced as part of the refund", "items": { "type": "string" }, "maxLength": 1000, "type": "array", "example": [ "Item XYZ", "Item ABC" ], "nullable": true } }, "required": [ "refundTransactionId" ], "type": "object" }, "ProofOfReplacement": { "additionalProperties": false, "properties": { "replacementAmount": { "description": "Amount of the replacement order", "maxLength": 20, "type": "number", "example": 105.55, "nullable": true }, "replacementCurrency": { "description": "Currency of the replacement order, 3-letter ISO-4217 format currency code", "maxLength": 3, "minLength": 3, "pattern": "[A-Z]{3}", "type": "string", "example": "USD", "nullable": true }, "replacementDate": { "description": "Date the replacement was processed. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "2022-11-15", "nullable": true }, "replacementId": { "description": "Unique identifier for the replacement order", "maxLength": 50, "type": "string", "example": "REP-123456" }, "replacementItems": { "description": "List of items that were replaced", "items": { "type": "string" }, "maxLength": 1000, "type": "array", "example": [ "Item XYZ", "Item ABC" ], "nullable": true }, "replacementTrackingNumber": { "description": "Tracking number for the replacement shipment", "maxLength": 50, "type": "string", "example": "123456", "nullable": true }, "shippingCarrier": { "description": "Shipping carrier name for the replacement", "maxLength": 50, "type": "string", "example": "UPS", "nullable": true } }, "required": [ "replacementId" ], "type": "object" }, "SubscriptionDetails": { "additionalProperties": false, "properties": { "billingAgreementPolicy": { "description": "The merchant's recurring billing agreement policy", "maxLength": 1000, "type": "string", "example": "Customer can cancel anytime before the next billing cycle", "nullable": true }, "isRecurringCharge": { "description": "Whether this is a recurring subscription charge", "type": "boolean", "example": false } }, "required": [ "isRecurringCharge" ], "type": "object" }, "disputeEvidenceDatapointsRequestRequest": { "additionalProperties": false, "description": "Submit structured textual datapoints for a dispute.", "properties": { "airlineTicketNumbers": { "description": "Array of airline ticket numbers for the order", "items": { "type": "string" }, "maxLength": 50, "type": "array", "example": [ "TK123456", "TK789012" ], "nullable": true }, "customerCorrespondences": { "description": "Array of objects describing correspondence between the merchant and the customer.", "items": { "$ref": "#/components/schemas/CustomerCorrespondence" }, "type": "array", "nullable": true }, "itemsHeldInCustoms": { "description": "Array of item names that are being held in customs", "items": { "type": "string" }, "maxLength": 100, "type": "array", "example": [ "iPhone 15 Pro", "Leather Jacket" ], "nullable": true }, "orderId": { "description": "Unique order/transaction identifier. Should match the order id sent to Forter at checkout. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.", "maxLength": 54, "type": "string", "x-conditional": true, "example": "4306795", "nullable": true }, "processorCaseNumber": { "description": "The case number from the payment processor.", "maxLength": 40, "type": "string", "x-conditional": true, "example": "CB-4343343219", "nullable": true }, "processorChargeId": { "description": "The unique identifier of the payment, such as Acquirer Reference Number (ARN).", "maxLength": 100, "type": "string", "example": "111111111", "nullable": true }, "proofsOfCreditBalance": { "description": "Array of objects describing credit balance applications", "items": { "$ref": "#/components/schemas/ProofOfCreditBalance" }, "type": "array", "nullable": true }, "proofsOfDelivery": { "description": "Data proofs of delivery - array of objects with details of deliveries made.", "items": { "$ref": "#/components/schemas/ProofOfDelivery" }, "type": "array", "nullable": true }, "proofsOfPickup": { "description": "Array of objects describing pickup details", "items": { "$ref": "#/components/schemas/ProofOfPickup" }, "type": "array", "nullable": true }, "proofsOfRefund": { "description": "Data proofs of refund - Array of objects describing refunds issued.", "items": { "$ref": "#/components/schemas/ProofOfRefund" }, "type": "array", "nullable": true }, "proofsOfReplacement": { "description": "Array of objects describing order replacements", "items": { "$ref": "#/components/schemas/ProofOfReplacement" }, "type": "array", "nullable": true }, "reservationIds": { "description": "Array of reservation IDs for the order", "items": { "type": "string" }, "maxLength": 50, "type": "array", "example": [ "RES-123456", "RES-789012" ], "nullable": true }, "subscriptionDetails": { "description": "Array of objects describing subscription details", "items": { "$ref": "#/components/schemas/SubscriptionDetails" }, "type": "array", "nullable": true } }, "type": "object" }, "InvalidEvidenceDataPoint": { "additionalProperties": false, "description": "Describes an invalid evidence entry with details about the failure.", "properties": { "datapointPath": { "description": "The path to the faulty datapoint in the evidence file\nex: /customerCorrespondences/0/contactReason", "type": "string" }, "failureReason": { "description": "The reason why the evidence was considered invalid", "maxLength": 255, "type": "string", "example": "Missing required field" } }, "required": [ "datapointPath", "failureReason" ], "type": "object" }, "disputeEvidenceDatapointsResponse": { "additionalProperties": false, "description": "The response object for dispute evidence datapoints uploads.", "properties": { "invalidEvidenceDatapoints": { "description": "Array of invalid datapoint entries, if any", "items": { "$ref": "#/components/schemas/InvalidEvidenceDataPoint" }, "type": "array", "nullable": true }, "message": { "description": "The message containing status response text", "enum": [ "EVIDENCE_UPLOADED", "SERVICE_UNAVAILABLE", "SCHEMA_VALIDATION_FAILED", "CLAIM_NOT_FOUND" ], "maxLength": 1000, "example": "EVIDENCE_UPLOADED" }, "status": { "description": "Status of the request processing", "enum": [ "SUCCESS", "FAILED" ], "maxLength": 50, "example": "SUCCESS" } }, "required": [ "message", "status" ], "type": "object" }, "disputeEvidenceFileRequestRequest": { "additionalProperties": false, "description": "Upload a single file as dispute evidence.", "properties": { "evidenceType": { "description": "The type of evidence being uploaded.\nThe following types are supported:\n- ACCEPTANCE_OF_RECURRING_BILLING_AGREEMENT\n- AUTHENTICATION_CERTIFICATE\n- BUYER_REVIEW_SURVEY\n- CARDHOLDER_VERIFICATION_DOCUMENT\n- CHARGEBACK_NOTIFICATION\n- CONTRACT_PAGE\n- CREDIT_BALANCE\n- CUSTOMER_CORRESPONDENCE\n- DELAY_DISCLOSURE\n- DISPUTE_LETTER\n- EMAIL_CONFIRMATION\n- FLIGHT_MANIFEST\n- HOTEL_NO_SHOW\n- INVOICE\n- OTHER\n- PASSENGER_OR_CUSTOMER_DETAILS\n- PROOF_OF_DELIVERY\n- PROOF_OF_ORDER_REPLACEMENT\n- PROOF_OF_POSSESSION_OR_USAGE\n- PROOF_OF_RECURRING_AGREEMENT_NOTICE\n- PROOF_OF_REFUND\n- PROOF_OF_REQUESTED_CANCELLATION\n- PROOF_OF_RESIDENCE\n- PURCHASE_HELD_IN_CUSTOMS\n- RECEIPT\n- RECURRING_BILLING_AGREEMENT\n- RELATED_INVOICE_HISTORY\n- SIGNED_DELIVERY_FORM\n- SIGNED_ORDER_FORM\n- SOCIAL_NETWORK_REPUTATION\n- STATEMENT_OF_UNAUTHORIZED_DEBIT\n- TERMS_AND_CONDITIONS\n- USER_TERMS_AND_CONDITION_ACCEPTANCE", "enum": [ "ACCEPTANCE_OF_RECURRING_BILLING_AGREEMENT", "AUTHENTICATION_CERTIFICATE", "BUYER_REVIEW_SURVEY", "CARDHOLDER_VERIFICATION_DOCUMENT", "CHARGEBACK_NOTIFICATION", "CONTRACT_PAGE", "CREDIT_BALANCE", "CUSTOMER_CORRESPONDENCE", "DELAY_DISCLOSURE", "DISPUTE_LETTER", "EMAIL_CONFIRMATION", "FLIGHT_MANIFEST", "HOTEL_NO_SHOW", "INVOICE", "OTHER", "PASSENGER_OR_CUSTOMER_DETAILS", "PROOF_OF_DELIVERY", "PROOF_OF_ORDER_REPLACEMENT", "PROOF_OF_POSSESSION_OR_USAGE", "PROOF_OF_RECURRING_AGREEMENT_NOTICE", "PROOF_OF_REFUND", "PROOF_OF_REQUESTED_CANCELLATION", "PROOF_OF_RESIDENCE", "PURCHASE_HELD_IN_CUSTOMS", "RECEIPT", "RECURRING_BILLING_AGREEMENT", "RELATED_INVOICE_HISTORY", "SIGNED_DELIVERY_FORM", "SIGNED_ORDER_FORM", "SOCIAL_NETWORK_REPUTATION", "STATEMENT_OF_UNAUTHORIZED_DEBIT", "TERMS_AND_CONDITIONS", "USER_TERMS_AND_CONDITION_ACCEPTANCE" ], "example": "PROOF_OF_DELIVERY" }, "filePath": { "description": "An S3 pointer for the file", "pattern": "s3:.+\\.(pdf|jpg|jpeg|png|PDF|JPG|JPEG|PNG)", "type": "string", "example": "s3:/ ///example-16451.pdf" }, "orderId": { "description": "Unique order/transaction identifier. Should match the order id sent to Forter at checkout. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.", "maxLength": 54, "type": "string", "x-conditional": true, "example": "4306795", "nullable": true }, "processorCaseNumber": { "description": "The case number from the payment processor.", "maxLength": 40, "type": "string", "x-conditional": true, "example": "CB-4343343219", "nullable": true }, "processorChargeId": { "description": "The unique identifier of the payment, such as Acquirer Reference Number (ARN).", "maxLength": 100, "type": "string", "example": "111111111", "nullable": true } }, "required": [ "evidenceType", "filePath" ], "type": "object" }, "disputeEvidenceFileResponse": { "additionalProperties": false, "description": "The response object following uploading dispute evidence file request to the system", "properties": { "message": { "description": "The message containing status response text", "enum": [ "EVIDENCE_UPLOADED", "SERVICE_UNAVAILABLE", "SCHEMA_VALIDATION_FAILED", "CLAIM_NOT_FOUND" ], "maxLength": 1000, "example": "EVIDENCE_UPLOADED" }, "status": { "description": "Status of the request processing", "enum": [ "SUCCESS", "FAILED" ], "maxLength": 50, "example": "SUCCESS" } }, "required": [ "message", "status" ], "type": "object" }, "MerchantAccountCreationFields": { "additionalProperties": false, "description": "Merchant account creation fields", "properties": { "ip": { "description": "IP address used by the account owner at the time of registration (in v4 format)", "maxLength": 45, "type": "string", "example": "10.0.0.128", "nullable": true }, "timestamp": { "description": "Date merchant account was created in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1415273179, "nullable": true } }, "type": "object" }, "merchantCreationRequest": { "additionalProperties": false, "description": "Create a new merchant within your Forter account. The response will include a Forter-assigned merchant subsite ID to be included in the API header on future requests.", "properties": { "defaultMerchantCategoryCode": { "description": "A Merchant Category Code (MCC) is a four-digit number listed in ISO 18245 for retail financial services. MCC is used to classify the business by the type of goods or services it provides", "maxLength": 4, "type": "string", "example": "5655" }, "merchantAccountCreation": { "allOf": [ { "$ref": "#/components/schemas/MerchantAccountCreationFields", "description": "Merchant account details on the PSP's platform" }, { "type": "object", "nullable": true } ] }, "merchantId": { "description": "The merchant's internal ID in the PSP's systems", "maxLength": 50, "type": "string", "example": "eh629dK9" }, "name": { "description": "The merchant's name in the PSP's systems. The name needs to be unique within the PSP's portfolio, and can include only letters (A-Z, a-z), numbers (0-9), spaces, and the following special characters: . _ & , ^ -.", "maxLength": 70, "type": "string", "example": "T-Shirts Express" } }, "required": [ "merchantId", "defaultMerchantCategoryCode", "name" ], "type": "object" }, "merchantCreationResponse": { "additionalProperties": false, "description": "Response structure for merchant registration requests", "properties": { "defaultMerchantCategoryCode": { "description": "A Merchant Category Code (MCC) is a four-digit number listed in ISO 18245 for retail financial services. MCC is used to classify the business by the type of goods or services it provides", "maxLength": 4, "type": "string", "example": "5655" }, "id": { "description": "The merchant's Site-ID in Forter's systems. Should be used for each call related to the merchant", "type": "string", "example": "aab42345bba2" }, "merchantAccountCreation": { "allOf": [ { "$ref": "#/components/schemas/MerchantAccountCreationFields", "description": "Merchant account details on the PSP's platform" }, { "type": "object", "nullable": true } ] }, "merchantId": { "description": "The merchant's internal ID in the PSP's systems", "maxLength": 50, "type": "string", "example": "eh629dK9" }, "name": { "description": "The merchant's Site Name", "type": "string", "example": "T-Shirts Express" } }, "required": [ "merchantId", "defaultMerchantCategoryCode", "id", "name" ], "type": "object" }, "privacyDownloadRequestRequest": { "additionalProperties": false, "description": "Retrieve the customer data from a previously submitted privacy request for data access.", "properties": {}, "type": "object" }, "privacyDownloadResponse": { "additionalProperties": false, "description": "Output file for a given access privacy request.", "properties": { "addresses": { "description": "List of known addresses.", "items": { "$ref": "#/components/schemas/GeneralPayloadMap" }, "type": "array", "example": [] }, "emails": { "description": "List of known email addresses.", "items": { "$ref": "#/components/schemas/GeneralPayloadMap" }, "type": "array", "example": [] }, "ips": { "description": "List of known IP addresses.", "items": { "$ref": "#/components/schemas/GeneralPayloadMap" }, "type": "array", "example": [] }, "phones": { "description": "List of known phone numbers.", "items": { "$ref": "#/components/schemas/GeneralPayloadMap" }, "type": "array", "example": [] }, "requests": { "description": "List of objects that represent requests sent to Forter.", "items": { "$ref": "#/components/schemas/GeneralPayloadMap" }, "type": "array", "example": [] } }, "required": [ "requests", "phones", "ips", "emails", "addresses" ], "type": "object" }, "Identifier": { "additionalProperties": false, "description": "An object that represents identifier of a data subject for the privacy requests purposes.", "properties": { "type": { "description": "Type of identifier", "enum": [ "EMAIL" ], "example": "EMAIL" }, "value": { "description": "Identifier value", "maxLength": 75, "type": "string", "example": "user@test.com" } }, "required": [ "type", "value" ], "type": "object" }, "privacyRequestRequest": { "additionalProperties": false, "description": "In compliance with privacy laws, request access or deletion of customer data on behalf of the customer. \nThis endpoint should only be used if a data subject has specifically asked that their personal data be accessed or deleted, and their identity has been verified. \nThe response will include a unique ID assigned to this request.", "properties": { "identifier": { "$ref": "#/components/schemas/Identifier", "description": "Request identifier details" }, "requestType": { "description": "Type of this privacy request", "enum": [ "DELETE", "ACCESS" ], "example": "ACCESS" } }, "required": [ "identifier", "requestType" ], "type": "object" }, "privacyResponse": { "additionalProperties": false, "description": "Response object for creation of a new privacy request.", "properties": { "requestUniqueId": { "description": "A Forter unique identifier that was assigned to a privacy request. It can be used to retrieve the status information and download the output data in case of an access request.", "type": "string", "example": "2023-04-23T060200931-ax32-privacy" } }, "required": [ "requestUniqueId" ], "type": "object" }, "privacyStatusRequestRequest": { "additionalProperties": false, "description": "Check the status of a previously submitted privacy request.", "properties": {}, "type": "object" }, "privacyStatusResponse": { "additionalProperties": false, "description": "Response object containing status information of a given privacy request.", "properties": { "requestUniqueId": { "description": "Unique identifier of this privacy request", "type": "string", "example": "2023-04-23T060200931-ax32-privacy" }, "status": { "description": "Current status of this privacy request", "enum": [ "IN_PROGRESS", "COMPLETED", "CANCELED" ], "example": "IN_PROGRESS" } }, "required": [ "requestUniqueId", "status" ], "type": "object" }, "CompensationStatus": { "additionalProperties": false, "description": "Status of the compensation request", "properties": { "hasProofOfPurchase": { "type": "boolean", "nullable": true }, "itemStatus": { "description": "A list of all items for which compensation was requested", "items": { "$ref": "#/components/schemas/ItemCompensationStatus" }, "type": "array" }, "merchantAgentData": { "allOf": [ { "$ref": "#/components/schemas/MerchantAgentData", "description": "Name and Id of merchant agent processing the compensation request" }, { "type": "object", "nullable": true } ] }, "replacementOrderId": { "description": "Unique order/transaction identifier for a replacement order issued by the merchant in response to this request", "maxLength": 54, "type": "string", "x-conditional": true, "example": "2356fdse0rr489", "nullable": true }, "shippingRefunded": { "description": "Indicates whether merchant reimbursed the customer for shipping expenses", "type": "boolean", "nullable": true }, "shippingRefundedAmount": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Amount of reimbursement for shipping expenses (in excess of totalGrantedCompensationAmount)" }, { "type": "object", "nullable": true } ] }, "statusData": { "allOf": [ { "$ref": "#/components/schemas/ItemCompensationStatusData", "description": "Data relating to the return of the item" }, { "type": "object", "nullable": true } ] }, "totalGrantedAmount": { "$ref": "#/components/schemas/Amount", "description": "Total amount of the compensation granted to customer (excluding shippingRefundedAmount)" } }, "required": [ "itemStatus", "totalGrantedAmount" ], "type": "object" }, "CompensationStatusLog": { "additionalProperties": false, "description": "Status of the return process per item", "properties": { "arrivedToWarehouseTime": { "description": "Time returned items arrived to the merchant's warehouse", "type": "number", "example": 1420070400000, "nullable": true }, "initiationTime": { "description": "The time that the customer initiated the request for compensation in MILLISECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1415287568000, "nullable": true }, "initiationType": { "description": "What channel did the customer use to initiate the request for compensation", "enum": [ "CALL_CENTER", "IN_STORE", "CHAT", "ONLINE", "SELF_SERVICE" ], "example": "CALL_CENTER", "nullable": true }, "shippedByCustomerTime": { "description": "Time returned items were shipped by the customer", "type": "number", "example": 1420070400000, "nullable": true } }, "type": "object" }, "ItemCompensationStatus": { "additionalProperties": false, "description": "This is an item for which the customer requested compensation and is now updating the status.", "properties": { "basicItemData": { "$ref": "#/components/schemas/BasicItemData", "description": "General data regarding item such as name, price, etc." }, "statusData": { "$ref": "#/components/schemas/ItemCompensationStatusData", "description": "Data relating to the return of the item" } }, "required": [ "basicItemData", "statusData" ], "type": "object" }, "ItemCompensationStatusData": { "additionalProperties": false, "description": "This is update on the specific data regarding the compensation requested by the customer for this item.", "properties": { "compensationTypeGranted": { "description": "Indicates whether the customer was granted a refund, store credit, replacement etc.", "enum": [ "REPLACEMENT", "REFUND", "REFUND_UPON_RETURN", "CREDIT", "MIXED", "UNKNOWN", "NO_COMPENSATION" ], "example": "REFUND" }, "internalReasonCategory": { "description": "The reason for the request as defined by the merchant", "maxLength": 40, "type": "string", "example": "defective item", "nullable": true }, "reasonCategory": { "description": "Reason for compensation request", "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" ], "example": "CHANGED_MY_MIND" }, "returnCondition": { "description": "Condition of the item returned", "enum": [ "GOOD_CONDITION", "DAMAGED", "WRONG_ITEM", "NO_ITEM", "NOT_ARRIVED", "NO_RETURN" ], "maxLength": 40, "example": "DAMAGED", "nullable": true }, "returnMethodGranted": { "description": "Method of return granted to customer", "enum": [ "SHIP_TO_WAREHOUSE", "IN_STORE", "NO_RETURN" ], "example": "SHIP_TO_WAREHOUSE" }, "statusLog": { "allOf": [ { "$ref": "#/components/schemas/CompensationStatusLog", "description": "Timestamp logs of the status of the return process (e.g. shipped, arrived to warehouse)", "maxLength": 40 }, { "type": "object", "nullable": true } ] }, "updatedStatus": { "description": "The updated compensation request status", "enum": [ "ACCEPTED_BY_MERCHANT", "REJECTED_BY_MERCHANT", "WITHDRAWN_BY_CUSTOMER" ], "example": "ACCEPTED_BY_MERCHANT" } }, "required": [ "updatedStatus", "compensationTypeGranted", "reasonCategory", "returnMethodGranted" ], "type": "object" }, "MerchantAgentData": { "additionalProperties": false, "description": "Name and Id of the merchant's agent processing the compensation request", "properties": { "merchantAgentId": { "description": "Unique identifier of the agent processing the customer's request", "type": "string", "example": "HG36885TZ", "nullable": true }, "merchantAgentName": { "description": "Name of the agent processing the customer's request", "type": "string", "example": "John Smith", "nullable": true } }, "type": "object" }, "OrderShippingInfo": { "additionalProperties": false, "description": "Order Shipping Info", "properties": { "additionalShippingInfo": { "description": "Aditional identification document details and verification", "maxLength": 100, "type": "string", "example": "PO Box 3297", "nullable": true }, "carrier": { "description": "Shipping carrier name", "maxLength": 50, "type": "string", "example": "UPS", "nullable": true }, "customerOpenedEmail": { "description": "True if there's an indication that the customer opened the purchase confirmation email sent by the merchant", "type": "boolean", "example": false, "nullable": true }, "downloadTime": { "description": "The time when the buyer downloaded the digital item to their device in SECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1415273168, "nullable": true }, "proofOfShippingURL": { "description": "URL to the proof of shipping in the merchant's system", "maxLength": 1024, "type": "string", "example": "true", "nullable": true }, "signedProofOfShipping": { "description": "Whether the user has signed a proof of shipping", "type": "boolean", "example": true, "nullable": true }, "trackingNumber": { "description": "Order tracking number", "maxLength": 50, "type": "string", "example": "123456", "nullable": true } }, "type": "object" }, "RefundInformation": { "additionalProperties": false, "description": "Details regarding the refund if the transaction has been refunded.", "properties": { "isAutomatedRefund": { "description": "True if automated - cases where refund is generated automatically by merchnat. For example where end user changed ordered item into a cheaper one", "type": "boolean", "x-conditional": true, "example": false, "nullable": true }, "isFullRefund": { "description": "True, if refund is for the full transaction amount. False, if refund is only for partial amount of transaction.", "type": "boolean", "x-conditional": true, "example": false, "nullable": true }, "refundAmount": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Final amount refunded to client.", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "refundAuthorizationCode": { "description": "Refund authorization code from payment gateway", "maxLength": 255, "type": "string", "x-conditional": true, "example": "B44233", "nullable": true }, "refundDate": { "description": "Date the refund was payed. Use YYYY-MM-DD format.", "format": "date", "type": "string", "example": "2015-06-12", "nullable": true }, "refundInitiatedBy": { "description": "By whom the refund was intitiated (merchant or customer).", "enum": [ "MERCHANT", "CUSTOMER" ], "x-conditional": true, "example": "MERCHANT", "nullable": true }, "refundMethod": { "description": "Description of the type of return method (bank, gift card points, loyalty points, etc.).", "enum": [ "BANK", "PAYPAL", "STORE_CREDIT", "ORIGINAL_PAYMENT_METHOD", "DIFFERENT_PAYMENT_METHOD" ], "x-conditional": true, "example": "ORIGINAL_PAYMENT_METHOD", "nullable": true }, "refundStatus": { "description": "The updated refund request status (When refund status is COMPLETED order status type should be RETURNED)", "enum": [ "REQUESTED", "DECLINED", "COMPLETED" ], "x-conditional": true, "example": "COMPLETED", "nullable": true } }, "type": "object" }, "statusRequest": { "additionalProperties": false, "description": "Inform of updates to the status of an order, including payment authorization, fulfillment, shipping details, and compensation granted. For pre-authorization flows, use this endpoint to supply Forter with authorization results from your payment processor. While no decision is provided on this request, it is a required input that improves the decision model.", "properties": { "additionalInformation": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Additional information not described in the documentation." }, { "type": "object", "nullable": true } ] }, "additionalOrderId": { "description": "Additional order/transaction identifier. Used primarily for IDs received after processing the order, such as settlement ID, capture ID, or any other type of ID that may help relate an order to financial data.", "maxLength": 100, "type": "string", "example": "12fdsh09820fdvr65", "nullable": true }, "cartItems": { "description": "An updated list of all items purchased and shipping details. Required only if one or more items have changed.", "items": { "$ref": "#/components/schemas/Item" }, "type": "array", "nullable": true }, "compensationStatus": { "allOf": [ { "$ref": "#/components/schemas/CompensationStatus", "description": "Object containing updates about the final status of a customer's request for compensation" }, { "type": "object", "nullable": true } ] }, "correlationId": { "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", "type": "string", "example": "HGJ7512345H3DE", "nullable": true }, "deliveryStatusInfo": { "allOf": [ { "$ref": "#/components/schemas/OrderShippingInfo", "description": "Delivery status information" }, { "type": "object", "nullable": true } ] }, "endPointLocation": { "allOf": [ { "$ref": "#/components/schemas/Location", "description": "Trip end point" }, { "type": "object", "nullable": true } ] }, "eventId": { "description": "Unique identifier of compensation update, should match previous compensation request identifier, if applicable, and any subsequent status updates of the same compensation request", "maxLength": 40, "type": "string", "x-conditional": true, "example": "r48987fgdse0r", "nullable": true }, "eventTime": { "description": "The time the status change event took place in MILLISECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1415287568000 }, "itemIds": { "description": "/**\nUnique item identifiers. Should match the item ids as described under the BasicItemData object.", "items": { "type": "string" }, "type": "array", "example": [ "a98751422", "a98751423" ], "nullable": true }, "orderId": { "description": "Unique order/transaction identifier. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order. **Must be identical to the orderId used in the order validation API**", "maxLength": 54, "type": "string", "example": "2356fdse0rr489" }, "payment": { "description": "An updated list of all payment methods and billing details used in the transaction. Required only if there has been a change to the payment.", "items": { "$ref": "#/components/schemas/Payment" }, "type": "array", "nullable": true }, "refundInformation": { "allOf": [ { "$ref": "#/components/schemas/RefundInformation", "description": "Refund information if the transaction is refunded." }, { "type": "object", "nullable": true } ] }, "returnedCartItems": { "description": "A list of returned items. Required only if one or more items have been returned.", "items": { "$ref": "#/components/schemas/Item" }, "type": "array", "nullable": true }, "statusChangeReason": { "description": "Reason the status changed, if applicable. Mainly relevant for cases an order was canceled (due to a fraud decision / stock / customer request / etc)", "maxLength": 150, "type": "string", "example": "Fraud_Team_Manual_Decline", "nullable": true }, "updatedMerchantStatus": { "description": "The new status as defined in the merchant's system", "maxLength": 150, "type": "string", "example": "Shipped", "nullable": true }, "updatedStatus": { "description": "The updated order status type", "enum": [ "PROCESSING", "SENT", "COMPLETED", "CANCELED_BY_MERCHANT", "CANCELED_BY_CUSTOMER", "RETURNED", "NO_SHOW", "REPLACED" ], "example": "SENT" }, "updatedTotalAmount": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Updated total amount of the transaction (after reducing any discount). Required only if the order's total amount has changed.", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "updatedTotalDiscount": { "allOf": [ { "$ref": "#/components/schemas/Discount", "description": "Updated discount that was given to the customer. Required only if one order's total discount has changed." }, { "type": "object", "nullable": true } ] }, "updatedTryOutStatus": { "description": "The updated TryOut flow status type", "enum": [ "NONE", "EMAIL_SENT_TO_CUSTOMER", "CALLED_TO_CUSTOMER", "CUSTOMER_VISITED_PAGE", "CUSTOMER_DECLARED_SENDBACK", "SHIPPING_REPORTED_SENDBACK", "RETURNED_ITEMS_ARRIVED_PENDING", "MISSING_ITEMS", "MANUAL_RESOLUTION", "CHARGE_ATTEMPT", "FORFEIT", "COMPLETED" ], "example": "EMAIL_SENT_TO_CUSTOMER", "nullable": true }, "verificationResults": { "allOf": [ { "$ref": "#/components/schemas/CreditCardVerification", "description": "Credit card verification data" }, { "type": "object", "nullable": true } ] } }, "required": [ "orderId", "eventTime", "updatedStatus" ], "type": "object" }, "statusResponse": { "additionalProperties": false, "description": "The response object following status request to the system", "properties": { "message": { "description": "The message containing status response text", "maxLength": 1000, "type": "string", "example": "Transaction #:id status recieved" }, "status": { "description": "Status of the request processing", "maxLength": 50, "type": "string", "example": "success" } }, "required": [ "message", "status" ], "type": "object" }, "CardParameter": { "additionalProperties": false, "properties": { "cardScheme": { "enum": [ "MASTERCARD", "VISA", "AMEX", "MAESTRO", "DINERS", "DISCOVER", "JCB" ], "example": "VISA" }, "value": { "type": "string", "example": "string" } }, "required": [ "cardScheme", "value" ], "type": "object" }, "JpAcquireSetting": { "additionalProperties": false, "description": "Settings for a specific acquirer in the JP regulation context.", "properties": { "acquirer": { "description": "The name of the acquirer.", "maxLength": 50, "minLength": 1, "type": "string", "example": "Acquirer Name" }, "force_3ds_on_guest_checkout": { "description": "If true, forces 3DS on guest checkout flows.\nThis will take effect only for scenario '3DS_NEW_CARD_S2'", "type": "boolean", "example": false, "nullable": true }, "scenario": { "description": "The scenario for the JP regulation offering", "enum": [ "3DS_HIGH_RISK_S1", "3DS_NEW_CARD_S2", "3DS_MANDATORY_S3" ], "example": "3DS_HIGH_RISK_S1" } }, "required": [ "acquirer", "scenario" ], "type": "object" }, "JpRegulationOffering": { "additionalProperties": false, "description": "Represents the JP regulation offering configuration.\nIncludes whether the feature is enabled and the acquirer settings.", "properties": { "acquirer_settings": { "description": "Acquirer-specific settings for JP regulation.\nIf not provided, the setting will be inherited from the parent site.", "items": { "$ref": "#/components/schemas/JpAcquireSetting" }, "type": "array", "nullable": true }, "enabled": { "description": "Register for JP regulation.", "type": "boolean", "example": true } }, "required": [ "enabled" ], "type": "object" }, "MerchantIdentifierFor3ds": { "additionalProperties": false, "properties": { "acquirerId": { "description": "Internal Forter ID for your Acquirer. Ask it from your Implementation Manager.", "type": "string" }, "acquirerMerchantName": { "description": "Acquirer's merchant name for each card scheme", "items": { "$ref": "#/components/schemas/CardParameter" }, "type": "array" }, "acquirerMid": { "description": "Acquirer Merchant Identifier (MID)", "type": "string", "example": "123456789" }, "merchantCategoryCode": { "description": "The merchants category code (MCC)", "maxLength": 4, "minLength": 4, "type": "string", "example": "5661" }, "merchantEntityCountryNumericCode": { "description": "Merchant entity country code", "maxLength": 3, "minLength": 3, "type": "string", "example": "840" }, "requestorId": { "description": "Requestor ids by card schema", "items": { "$ref": "#/components/schemas/CardParameter" }, "type": "array" }, "requestorName": { "description": "Requestor ids by card schema", "items": { "$ref": "#/components/schemas/CardParameter" }, "type": "array" }, "requestorUrl": { "description": "Requestor urls per card scheme", "items": { "$ref": "#/components/schemas/CardParameter" }, "type": "array" }, "supportedCurrencies": { "description": "Supported currency codes", "items": { "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTC", "BTN", "BWP", "BYN", "BZD", "BYR", "CAD", "CDF", "CHF", "CLF", "CLP", "CNH", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STD", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VEF", "VES", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "YER", "ZAR", "ZMW", "ZWL" ] }, "type": "array", "example": [ "USD" ], "nullable": true }, "supportedSchemes": { "description": "Supported card schemes", "items": { "enum": [ "MASTERCARD", "VISA", "AMEX", "MAESTRO", "DINERS", "DISCOVER", "JCB" ] }, "type": "array", "example": [ "VISA" ], "nullable": true }, "supportedStates": { "description": "Supported states", "items": { "type": "string" }, "type": "array", "nullable": true } }, "required": [ "requestorId", "requestorName", "requestorUrl", "merchantCategoryCode", "acquirerId", "acquirerMid", "acquirerMerchantName", "merchantEntityCountryNumericCode" ], "type": "object" }, "Processor": { "additionalProperties": false, "properties": { "id": { "description": "Internal Forter ID for your Processor. Ask it from your Implementation Manager.", "type": "string" }, "mids": { "description": "Mids - merchant identifiers for 3DS", "items": { "$ref": "#/components/schemas/MerchantIdentifierFor3ds" }, "type": "array" } }, "required": [ "id", "mids" ], "type": "object" }, "ThreeDsConfiguration": { "additionalProperties": false, "properties": { "processors": { "items": { "$ref": "#/components/schemas/Processor" }, "type": "array" } }, "required": [ "processors" ], "type": "object" }, "ThreeDsOfferings": { "additionalProperties": false, "properties": { "jp_regulation": { "allOf": [ { "$ref": "#/components/schemas/JpRegulationOffering", "description": "Register for JP regulation" }, { "type": "object", "nullable": true } ] }, "policy_3ds": { "description": "Register 3DS for policy", "type": "boolean", "example": true }, "psd2": { "description": "Register 3DS for PSD2 regulation", "type": "boolean", "example": true }, "risk_3ds": { "description": "Register 3DS for risk", "type": "boolean", "example": true } }, "required": [ "psd2", "risk_3ds", "policy_3ds" ], "type": "object" }, "threeDsExecutionOnboardingRequest": { "additionalProperties": false, "description": "Enroll a merchant in Forter's 3DS execution services on their future orders. \nThe response will include a request ID that can be used to check on the status.", "properties": { "offerings": { "$ref": "#/components/schemas/ThreeDsOfferings", "description": "Selection of offerings the merchant signed up for" }, "threeDsConfiguration": { "$ref": "#/components/schemas/ThreeDsConfiguration", "description": "The 3DS configuration" } }, "required": [ "offerings", "threeDsConfiguration" ], "type": "object" }, "threeDsExecutionOnboardingRequestAccepted": { "additionalProperties": false, "description": "Response structure for merchant onboarding requests", "properties": { "requestId": { "type": "string", "example": "my-request-id-1234" }, "status": { "type": "string", "example": "success" } }, "required": [ "status", "requestId" ], "type": "object" }, "threeDsExecutionOnboardingStatusRequest": { "additionalProperties": false, "description": "Check the status of a previous request to enroll a merchant in Forter's 3DS execution services.", "properties": {}, "type": "object" }, "threeDsExecutionOnboardingStatusResponse": { "additionalProperties": false, "description": "Response structure for merchant onboarding requests", "properties": { "status": { "description": "Status of the onboarding request - IN_PROGRESS (request is pending processing) / COMPLETE (request completed) / REJECTED (invalid request is rejected) / FAILED (request is valid but failed for some reason)", "type": "string", "example": "IN_PROGRESS" } }, "required": [ "status" ], "type": "object" }, "threeDsRecommendationOnboardingRequest": { "additionalProperties": false, "description": "Enroll a merchant in Forter's 3DS recommendation services on their future orders.\nThe response will include a request ID that can be used to check on the status.", "properties": { "offerings": { "$ref": "#/components/schemas/ThreeDsOfferings", "description": "Selection of offerings the merchant signed up for" } }, "required": [ "offerings" ], "type": "object" }, "threeDsRecommendationOnboardingRequestAccepted": { "additionalProperties": false, "description": "Response structure for merchant onboarding requests", "properties": { "requestId": { "type": "string", "example": "my-request-id-1234" }, "status": { "type": "string", "example": "success" } }, "required": [ "status", "requestId" ], "type": "object" }, "threeDsRecommendationOnboardingStatusRequest": { "additionalProperties": false, "description": "Check the status of a previous request to enroll a merchant in Forter's 3DS recommendation services.", "properties": {}, "type": "object" }, "threeDsRecommendationOnboardingStatusResponse": { "additionalProperties": false, "description": "Response structure for merchant onboarding requests", "properties": { "status": { "description": "Status of the onboarding request - IN_PROGRESS (request is pending processing) / COMPLETE (request completed) / REJECTED (invalid request is rejected) / FAILED (request is valid but failed for some reason)", "type": "string", "example": "IN_PROGRESS" } }, "required": [ "status" ], "type": "object" }, "CompensationData": { "additionalProperties": false, "description": "This is specific data regarding the compensation requested by the customer. Depending on the type of integration, this data could be provided at the order level or per item.", "properties": { "compensationTypeRequested": { "description": "Indicates whether the customer requested a refund, store credit, replacement etc.", "enum": [ "REPLACEMENT", "REFUND", "REFUND_UPON_RETURN", "CREDIT", "MIXED", "UNKNOWN", "NO_COMPENSATION" ], "x-conditional": true, "example": "REFUND", "nullable": true }, "initiationTime": { "description": "The time that the customer initiated the request for compensation in MILLISECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1415287568000 }, "internalReasonCategory": { "description": "The reason for the request as defined by the merchant", "maxLength": 40, "type": "string", "example": "defective item", "nullable": true }, "reasonCategory": { "description": "Reason for compensation request", "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" ], "x-conditional": true, "example": "CHANGED_MY_MIND", "nullable": true }, "requestedReturnType": { "description": "Method of return requested by customer (or the request to not return item at all)", "enum": [ "SHIP_TO_WAREHOUSE", "IN_STORE", "NO_RETURN" ], "example": "SHIP_TO_WAREHOUSE" } }, "required": [ "initiationTime", "requestedReturnType" ], "type": "object" }, "CompensationItem": { "additionalProperties": false, "description": "This is an item for which the customer is requesting compensation.", "properties": { "basicItemData": { "$ref": "#/components/schemas/BasicItemData", "description": "General data regarding item such as name, price, etc." }, "itemCompensationData": { "$ref": "#/components/schemas/CompensationData", "description": "Data relating to the return of the item" } }, "required": [ "basicItemData", "itemCompensationData" ], "type": "object" }, "CompensationRequest": { "additionalProperties": false, "description": "Includes specific details of the compensation request (type of compensation requested, on which items, for what reasons, etc.)", "properties": { "initiationType": { "description": "What channel did the customer use to initiate the request for compensation", "enum": [ "CALL_CENTER", "IN_STORE", "CHAT", "ONLINE", "SELF_SERVICE" ], "example": "CALL_CENTER" }, "items": { "description": "A list of all items for which compensation is being requested", "items": { "$ref": "#/components/schemas/CompensationItem" }, "type": "array" }, "orderCompensationData": { "allOf": [ { "$ref": "#/components/schemas/CompensationData", "description": "Data relating to the return of the item" }, { "type": "object", "nullable": true } ] }, "totalRequestedAmount": { "$ref": "#/components/schemas/Amount", "description": "Total amount of the compensation requested by customer" } }, "required": [ "initiationType", "items", "totalRequestedAmount" ], "type": "object" }, "unifiedCompensationRequestRequest": { "additionalProperties": false, "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.", "properties": { "accountId": { "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'.", "maxLength": 100, "type": "string", "example": "e520-ba9a-367-60b" }, "additionalEventIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/AdditionalAccountEventIdentifiers", "description": "Additional identifiers of the event.", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "additionalInformation": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Additional information not described in the documentation." }, { "type": "object", "nullable": true } ] }, "compensationRequest": { "$ref": "#/components/schemas/CompensationRequest", "description": "Details of compensation request (type of compensation requested, items for which compensation is requested, etc.)" }, "connectionInformation": { "$ref": "#/components/schemas/ConnectionInformation", "description": "Connection information about the customer typically found in the HTTP request header, if the compensation was initiated online" }, "eventId": { "description": "Unique identifier of this compensation request", "maxLength": 40, "type": "string", "example": "r48987fgdse0r" }, "eventTime": { "description": "The time that the trigger event occurred in MILLISECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1415287568000 }, "hasProofOfPurchase": { "description": "Whether the user has a proof of purchase", "type": "boolean", "example": true, "nullable": true }, "isGuestAccount": { "description": "Boolean field indicating if account is a guest account.", "type": "boolean", "example": false }, "merchantAgentData": { "allOf": [ { "$ref": "#/components/schemas/MerchantAgentData", "description": "Name and Id of merchant agent processing the compensation request", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "merchantIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/MerchantIdentifiers", "description": "If a merchant operates a number of sites, Merchant Identifiers help Forter's system to identify the right site.", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "originalOrderId": { "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.", "maxLength": 54, "type": "string", "example": "2356fdse0rr489" }, "status": { "allOf": [ { "$ref": "#/components/schemas/CompensationStatus", "description": "Status of compensation request for offline use and in-store returns where status is available at the time the request is sent to Forter" }, { "type": "object", "nullable": true } ] } }, "required": [ "eventId", "eventTime", "connectionInformation", "originalOrderId", "accountId", "isGuestAccount", "compensationRequest" ], "type": "object" }, "unifiedCompensationRequestResponse": { "additionalProperties": false, "description": "The response object of a forter compensation request call", "properties": { "correlationId": { "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", "type": "string", "example": "HGJ7512345H3DE" }, "decisionReason": { "maxLength": 1000, "type": "string", "example": "" }, "forterDecision": { "description": "The message containing the decision", "maxLength": 1000, "type": "string", "example": "approve" }, "merchantPolicyId": { "description": "UID of the custom policy created in Forter's Policies tool that resulted in this decision", "type": "string", "example": "0ee8ba28a8654c659addbae9253b707c" }, "recommendations": { "description": "Forter's recommendations for the optimal way of proceeding with the compensation request", "items": { "type": "string" }, "maxLength": 1000, "type": "array", "example": [] }, "status": { "description": "Status of the request processing", "maxLength": 50, "type": "string", "example": "success" } }, "required": [ "forterDecision", "correlationId", "recommendations", "decisionReason", "merchantPolicyId", "status" ], "type": "object" }, "AdditionalOrderIdentifiers": { "additionalProperties": false, "description": "Additional identifiers of the order which are used for identifying the order in various systems.", "properties": { "additionalOrderId": { "description": "Secondary or additional order/transaction identifier. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.", "maxLength": 50, "type": "string", "example": "4306795", "nullable": true }, "agenticCommercePlatform": { "allOf": [ { "$ref": "#/components/schemas/agenticCommercePlatform", "description": "AI Agent data related to the order", "maxLength": 50 }, { "type": "object", "nullable": true } ] }, "bigCommerceAdditionalOrderData": { "allOf": [ { "$ref": "#/components/schemas/BigCommerceAdditionalOrderData", "description": "Additional Data related to the Big Commerce Order API. This field should only exist for customers using the Big Commerce extension" }, { "type": "object", "nullable": true } ] }, "customerReferralMethod": { "description": "The way a customer was referred to the site, such as an affiliate referral, a whitelabel partnership, Facilitated booking - bookings coming from partners where the FE is not under the merchant control.", "enum": [ "DIRECT", "REDIRECT_TO_MERCHANT", "WHITELABEL_SERVICE", "FACILITATED_BOOKING", "PAID_TRAFFIC" ], "example": "REDIRECT_TO_MERCHANT", "nullable": true }, "customerReferralName": { "description": "The name of the affiliate having referred a customer to the site.", "type": "string", "example": "ForterFlights.com", "nullable": true }, "hybrisAdditionalOrderData": { "allOf": [ { "$ref": "#/components/schemas/HybrisAdditionalOrderData", "description": "Additional Data related to the SAP Hybris Order API. This field should only exist for customers using the Hybris extension" }, { "type": "object", "nullable": true } ] }, "isSplitOrder": { "description": "True if original order was split into multiple API calls", "type": "boolean", "example": false, "nullable": true }, "magentoAdditionalOrderData": { "allOf": [ { "$ref": "#/components/schemas/MagentoAdditionalOrderData", "description": "Additional Data related to the Forter Magento Extension. This field should only exist for customers using the Magento extension" }, { "type": "object", "nullable": true } ] }, "merchant": { "allOf": [ { "$ref": "#/components/schemas/MerchantIdentifiers", "description": "Merchant identification details", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "orderSegment": { "description": "Name of segment/program this order is related to. Relevant when there are different order options, such as Try & Buy, Regular checkout, Gifting, etc.", "maxLength": 50, "type": "string", "example": "Regular Checkout", "nullable": true }, "portalDisplayCustomField1": { "description": "First custom field available for you to send Forter information about an order that we otherwise do not have a field for in our API. Data sent in this field will not factor into any decisions, but can be made available on the Forter Portal grids and Forter Data Studio", "maxLength": 2048, "type": "string", "example": "identifier-1", "nullable": true }, "portalDisplayCustomField2": { "description": "Second custom field available for you to send Forter information about an order that we otherwise do not have a field for in our API. Data sent in this field will not factor into any decisions, but can be made available on the Forter Portal grids and Forter Data Studio", "maxLength": 2048, "type": "string", "example": "identifier-2", "nullable": true }, "portalDisplayCustomField3": { "description": "Third custom field available for you to send Forter information about an order that we otherwise do not have a field for in our API. Data sent in this field will not factor into any decisions, but can be made available on the Forter Portal grids and Forter Data Studio", "maxLength": 2048, "type": "string", "example": "identifier-3", "nullable": true }, "portalDisplayCustomField4": { "description": "Fourth custom field available for you to send Forter information about an order that we otherwise do not have a field for in our API. Data sent in this field will not factor into any decisions, but can be made available on the Forter Portal grids and Forter Data Studio", "maxLength": 2048, "type": "string", "example": "identifier-4", "nullable": true }, "shopifyAdditionalOrderData": { "allOf": [ { "$ref": "#/components/schemas/ShopifyAdditionalOrderData", "description": "Additional Data related to the Shopify Order API. This field should only exist for customers using the Shopify extension" }, { "type": "object", "nullable": true } ] }, "splitOrderIds": { "description": "List of order ID which originated from the same split order", "items": { "type": "string" }, "type": "array", "example": [ "6543545", "6545635" ], "nullable": true }, "splitOrderTotalAmount": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Total amount of parent order (e.g. if this is one of 3 split orders, each of 10$, the total sum of the parent order is 30$)", "maxLength": 12 }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "BigCommerceAdditionalOrderData": { "additionalProperties": false, "description": "Object for extra order data related to Big Commerce platform", "properties": { "cartId": { "description": "Big Commerce Cart ID", "type": "string", "example": "c52b1f7c-5083-4ff5-a37c-ff26dfab176a", "nullable": true } }, "type": "object" }, "HybrisAdditionalOrderData": { "additionalProperties": false, "description": "Object for extra order data related to SAP Hybris platform", "properties": { "hybrisOrderStage": { "description": "The stage of the order in the moment it is sent to Forter. Specific to the Hybris platform backend.", "enum": [ "PRE_AUTH", "POST_AUTH_SYNC", "POST_AUTH_ASYNC", "FAILED_AUTHORIZATION", "DATA_EXPORT" ], "example": "POST_AUTH_ASYNC", "nullable": true } }, "type": "object" }, "MagentoAdditionalOrderData": { "additionalProperties": false, "description": "Object for extra order data related to Magento extension", "properties": { "magentoOrderStage": { "description": "The stage of the order in the moment it is sent to Forter. Specific to the Magento platform backend.", "enum": [ "BEFORE_PAYMENT_ACTION", "AFTER_PAYMENT_ACTION", "PAYMENT_ACTION_FAILURE" ], "example": "AFTER_PAYMENT_ACTION", "nullable": true } }, "type": "object" }, "PhoneOrderInformation": { "additionalProperties": false, "description": "Information to be retrieved from the caller or the call center system about the order if placed over the phone.", "properties": { "callerFirstName": { "description": "The caller's first name", "maxLength": 75, "type": "string", "x-conditional": true, "example": "John", "nullable": true }, "callerId": { "description": "The caller's phone number as identified by the customer support system.", "maxLength": 50, "type": "string", "x-conditional": true, "example": "2121234567", "nullable": true }, "callerLastName": { "description": "The caller's last name", "maxLength": 75, "type": "string", "x-conditional": true, "example": "Smith", "nullable": true }, "customerWebId": { "description": "The webId value as injected by Forter's script", "maxLength": 50, "type": "string", "example": "123456789" } }, "required": [ "customerWebId" ], "type": "object" }, "ShopifyAdditionalOrderData": { "additionalProperties": false, "description": "Object for extra order data related to Shopify platform", "properties": { "cartToken": { "description": "Shopify Cart Token", "type": "string", "example": "49845384738223410", "nullable": true }, "checkoutToken": { "description": "Shopify Checkout Token", "type": "string", "example": "92233291239023300", "nullable": true }, "customerTags": { "description": "Shopify Customer Tags", "items": { "type": "string" }, "type": "array", "example": [ "tag1", "tag2" ], "nullable": true }, "fullShopifyOrderHeaders": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Shopify Full Stringified Order Header Data (Shopify Order API)" }, { "type": "object", "nullable": true } ] }, "fullShopifyOrderPayload": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Shopify Full Stringified Order Data (Shopify Order API)" }, { "type": "object", "nullable": true } ] }, "landingSite": { "description": "Shopify Landing Site", "type": "string", "nullable": true }, "locationId": { "description": "Shopify Location ID", "type": "string", "nullable": true }, "orderTags": { "description": "Shopify Order Tags", "items": { "type": "string" }, "type": "array", "example": [ "tag1", "tag2" ], "nullable": true }, "sourceName": { "description": "Shopify Source Name", "type": "string", "nullable": true } }, "type": "object" }, "agenticCommercePlatform": { "additionalProperties": false, "description": "This object contains data related to the AI agent that assisted in placing the order (if placed by an AI agent).", "properties": { "agentApp": { "description": "Use only if platform is not available in the agentPlatform enum list", "maxLength": 50, "type": "string", "example": "DBY", "nullable": true }, "agentId": { "description": "A unique identifier provided by the AI agent itself or the orchestration platform that placed the order", "maxLength": 50, "type": "string", "example": "eh629dK9", "nullable": true }, "agentPlatform": { "description": "Defines the specific purpose or flow of the AI agent application", "enum": [ "CHATGPT_INSTANT_CHECKOUT", "CHATGPT_AGENT", "CHATGPT_APPS_SDK", "BUY_WITH_PRO", "BUY_FOR_ME", "GENSMO", "ALEXA", "GEMINI", "AI_MODE", "COPILOT", "ADS", "CLAUDE_DESKTOP", "CLAUDE_CODE", "CLAUDE_AI", "SEARCH", "OTHER" ], "maxLength": 50, "example": "OTHER" }, "agentSourceType": { "description": "Specifies the general category or known vendor of the AI agent", "enum": [ "OPENAI", "GOOGLE", "META", "ANTHROPIC", "AMAZON", "MICROSOFT", "PERPLEXITY", "IN_HOUSE", "THIRD_PARTY", "HENRYLABS" ], "maxLength": 50, "example": "THIRD_PARTY" } }, "required": [ "agentSourceType", "agentPlatform" ], "type": "object" }, "v3OrderRequest": { "additionalProperties": false, "description": "Send order information at checkout to receive a fraud or abuse decision. The response may also include recommendations based on your payment optimization features or abuse prevention policies, or a managed order token to include when requesting the 3DS result.", "properties": { "accountOwner": { "allOf": [ { "$ref": "#/components/schemas/AccountOwner", "description": "The customer's basic information.", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "additionalIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/AdditionalOrderIdentifiers", "description": "Additional identifiers of the transaction" }, { "type": "object", "nullable": true } ] }, "additionalInformation": { "allOf": [ { "$ref": "#/components/schemas/GeneralPayloadMap", "description": "Additional information not described in the documentation." }, { "type": "object", "nullable": true } ] }, "authorizationStep": { "description": "Indicates whether the transaction sent pre credit card authorization or post authorization", "enum": [ "PRE_AUTHORIZATION", "POST_AUTHORIZATION" ], "example": "PRE_AUTHORIZATION", "nullable": true }, "cartItems": { "description": "A list of all items purchased and shipping details", "items": { "$ref": "#/components/schemas/Item" }, "type": "array" }, "checkoutTime": { "description": "The time when the buyer completed the checkout process in the merchant website in SECONDS since unix epoch (Jan 1, 1970).", "type": "number", "example": 1699916780 }, "connectionInformation": { "$ref": "#/components/schemas/ConnectionInformation", "description": "Connection information about the customer typically found in the HTTP request header" }, "customerAccountData": { "allOf": [ { "$ref": "#/components/schemas/AccountData", "description": "The customer's full account details. Required if not integrated with Forter's Account API.", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "discounts": { "description": "A list of all discounts that were given to the customer (Up to ten discounts per transaction)", "items": { "$ref": "#/components/schemas/Discount" }, "type": "array", "nullable": true }, "orderId": { "description": "Unique order/transaction identifier. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.", "maxLength": 54, "type": "string", "example": "2356fdse0rr489" }, "orderType": { "description": "Platform order was made through", "enum": [ "WEB", "PHONE", "DYNAMIC_PHONE", "MOBILE", "MOBILE_IN_STORE", "IOS", "ANDROID", "WAP", "STORE", "MERCHANT_EMPLOYEE", "MAIL_ORDER", "AUTOMATIC_RENEWAL_OR_INSTALLMENT_PAYMENT", "MERCHANT_INITIATED", "UNKNOWN", "POS", "API_ONLY", "PERSONAL_POS", "PHONE_LINK", "AI_AGENT" ], "example": "WEB" }, "payment": { "description": "A list of all payment methods and billing details used in the transaction", "items": { "$ref": "#/components/schemas/Payment" }, "type": "array" }, "phoneOrderInformation": { "allOf": [ { "$ref": "#/components/schemas/PhoneOrderInformation", "description": "Required information for orders that are placed over the phone." }, { "type": "object", "nullable": true } ] }, "primaryDeliveryDetails": { "$ref": "#/components/schemas/DeliveryDetails", "description": "Main details about the kind of delivery chosen by the customer. In case different items have different delivery methods, this should refer to the main delivery method and other methods should be specified per item." }, "primaryRecipient": { "$ref": "#/components/schemas/Beneficiary", "description": "Primary recipient of the transaction goods. It should correspond with the primary delivery method and can include notes the customer included as part of their transaction, whether directed to the merchant or to the intended recipient." }, "timeSentToForter": { "description": "The time the request was sent to Forter in MILLISECONDS since unix epoch (Jan 1, 1970)", "type": "number", "example": 1699916780000, "nullable": true }, "totalAmount": { "$ref": "#/components/schemas/Amount", "description": "Total amount of the transaction (after reducing any discount)" }, "totalDiscount": { "allOf": [ { "$ref": "#/components/schemas/Discount", "description": "Discount that was given to the customer" }, { "type": "object", "nullable": true } ] } }, "required": [ "orderId", "orderType", "checkoutTime", "connectionInformation", "totalAmount", "cartItems", "payment", "primaryDeliveryDetails", "primaryRecipient" ], "type": "object" }, "PaymentRecommendations": { "additionalProperties": false, "description": "PaymentRecommendations contains all types of payment recommendations Forter sends as part of the Payment Routing\nOptimization solution", "properties": { "action": { "description": "Action to take based on the recommendations", "enum": [ "no_processor_preference", "do_not_process", "process_payment" ], "nullable": true }, "processor_routing_reason": { "description": "The reason for the processor routing decision", "enum": [ "out_of_scope", "hard_fraud_decline", "model_recommendation", "exceeded_processing_attempts", "authorized_payment", "no_optional_processor" ], "nullable": true }, "processors": { "description": "Processor routing recommendations", "items": { "$ref": "#/components/schemas/ProcessorRecommendation" }, "type": "array", "nullable": true } }, "type": "object" }, "ProcessorRecommendation": { "additionalProperties": false, "description": "Forter's recommendation of which processor the merchant should complete the payment with", "properties": { "priority": { "description": "Recommendation with priority 1 should be tried first. Priority 2 should be tried if 1 fails.", "type": "number", "example": 1 }, "processorMid": { "description": "Processor MID", "type": "string" }, "processorName": { "description": "Processor Name", "type": "string" }, "recommend3DS": { "description": "In case 3DS should be tried, this will be true", "type": "boolean", "example": false }, "recommendationId": { "description": "Id of the recommendation - when merchants use our recommendation we expect them to report that by supplying this\nin the following request", "type": "string" } }, "required": [ "priority", "recommendationId", "recommend3DS", "processorMid", "processorName" ], "type": "object" }, "v3OrderResponse": { "additionalProperties": false, "description": "Response for managed order request can be either of shapes:\n1. {\"managedOrderToken\": \"...\"} - only `managedOrderToken` field and nothing else\n2. {\"forterDecision\": \"...\", ...} - all fields *but* `managedOrderToken`", "properties": { "decisionReason": { "description": "The main reason behind the Forter decision", "maxLength": 1000, "type": "string", "example": "" }, "forterDecision": { "description": "The latest Forter decision regarding the attempted action", "enum": [ "APPROVE", "DECLINE", "NOT REVIEWED" ], "example": "APPROVE" }, "linkToEventInDashboard": { "description": "Link to the event in the decision dashboard", "maxLength": 1000, "type": "string", "example": "https://portal.forter.com/dashboard/:id" }, "managedOrderToken": { "maxLength": 65536, "type": "string", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ2YWx1ZSIsImV4cCI6MTY4ODYyOTY4NX0.uIk2TYHkuIqk238neBRW3jurISWeqzkB7JDOH_-MwfSA1QZ7x6j8WWNGgwbqh-hs0-dZzP-EOvDc6rgjmN1fT8l4Ieo6_rDDYB8xyFrUPPijrUQbvKjl7FZXm7MlI_MNDtv3uhnjWlZAGcF03e4plZzcTVMiz6ai0z-VoIPU58hGC8FDKf-vWmu7e3E0Da1P_1pOgr-lWCLzntwkQ4BoVeVCTo8sF5wNm5QczB4EpXs4_0EP3MaCHKvQsNxHjV9LDJ-c94itloIgp2YuUIVtV49gE4FL4ZvbKQIQOPz4OaKXLzJuJZvjqQrAaHohSAh_APrpavFtNbnwCp0Lv3A8zv1lfwhJiMes8YYDzwjlArfbqS9Hz_ge267YbvLFHHyK_YHus6XDR3yPtHGQOAfKbBex9Lln9TWxwTDxBrfzQ4UT3eH-DXsf-mUvdC-8tHVRnNIbzYCZQggH00MgtBzqj5Gy5EuMO4jYpwP3mK6Z4EZCWEnk7YxzZe0dnpOT2JcJDec2jJbzBVYMrEGu-vq9jnnRQ416ZG3FxPZr_nyHs1FhuaHfE2LpfldpLGsnGZtrN5-qx8vQVuRyDaaOmtOiklewNNZ_ig0ebkVFrwLCR7Pn6226k1Dc_qAUU7xI2sQASZVk_Y_DH9sZENcmzNOcFpUxB1zf8ewc4YfNoe1fJsc", "nullable": true }, "merchantPolicyId": { "description": "UID of the custom policy created in Forter's Policies tool that resulted in this decision", "type": "string", "example": "0ee8ba28a8654c659addbae9253b707c" }, "orderId": { "description": "Transaction/order ID. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.", "type": "string", "example": "123456" }, "paymentRecommendations": { "allOf": [ { "$ref": "#/components/schemas/PaymentRecommendations" }, { "type": "object", "nullable": true } ] }, "recommendation": { "description": "A specific recommendation for an action that might help the customer to complete their transaction/action (e.g. verify phone via SMS, verify via push notification, verify email, perform a 3DS check, etc.)", "maxLength": 1000, "type": "string", "example": "" }, "verificationMethod": { "$ref": "#/components/schemas/VerificationMethod", "description": "The specific verification method to be used when verification is required according to \"recommendation\" field", "maxLength": 1000 } }, "required": [ "forterDecision", "recommendation", "verificationMethod", "decisionReason", "merchantPolicyId", "orderId", "linkToEventInDashboard" ], "type": "object" }, "v3OrderResultsRequest": { "additionalProperties": false, "description": "Check the 3DS results using the managed order token returned in Forter's response to the order request.", "properties": { "managedOrderToken": { "description": "The managedOrderToken returned from the create endpoint", "maxLength": 65536, "type": "string", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjIwMjMtMDUtMjMifQ.eyJmb3J0ZXJPcGFxdWVEYXRhIjoiZm9ydGVyT3BhcXVlRGF0YSIsImF1ZCI6ImNoZWNrb3V0dG9vbHMiLCJpc3MiOiJodHRwczovL2FwaS5jaGVja291dHRvb2xzLmNvbS92My9tYW5hZ2VkL29yZGVycyIsImV4cCI6MTczMzk0NzYxNH0.i3Q2KsUerRNQMfCGKQgoR_0AIENOKZ0C99kiRtlkuVQqbmhPRo0A4c42XHp0J_-kdJbCW2W1WckgglTy8GGRfwzVfZ2szSxJCB6QOd4uHwn0BN1GeTdY3qjtBHF48ihsDhfYXvII4Kl2zpL54aJfCePuYANedhxAWJZnUCcSKxFDYsj-gHGGApZbgPhnMI1QfUme2CHjpxu2vGTC0xC08OQuYO7vbESQU_YnLsc-xQYBrOy_4XuOEJDq8fK2O5saiZZEknNvLxouAzn16p5lzWJ3sp-tsJR-a9C_KgNqz_Nv4SaeSYQMhJwrYXXLhNP2ueTHdzEObtm7Skp_NQFdXBBF4vMO4HhKKBzNnfWjsKKCb6Utb__AZNbW4XYn9788wdHNVu-TVhiHRYOg19iOHaJS1l8DfHqMN0o-98Cmdu9prhGIvey64FrcEoAf9jhUjT4LN9u0zuH1jbwfpG-owmHEnpAY6dtZilK81zrf6A3OhRIB5_cECdutSa_UHXP1xapUsGoQMy3T5qaecnj6VqwXI1Cc3vrhsaewRCqJqDTeHG2slttrWBrigvXk4rFwWVazn_Y_PCy-WCfcazXK6nTCJTQ_mBoM24S-W6jRlOsfplDDl5cKGrvsulqXDuDqRzJnc_AmkVOWM9AvqqgkC5ef_2xcGprFi4xDjXkScz4" } }, "required": [ "managedOrderToken" ], "type": "object" }, "v3OrderResultsResponse": { "additionalProperties": false, "properties": { "decisionReason": { "description": "The main reason behind the Forter decision", "maxLength": 1000, "type": "string", "example": "" }, "forterDecision": { "description": "The latest Forter decision regarding the attempted action", "enum": [ "APPROVE", "DECLINE", "NOT REVIEWED" ], "example": "APPROVE" }, "linkToEventInDashboard": { "description": "Link to the event in the decision dashboard", "maxLength": 1000, "type": "string", "example": "https://portal.forter.com/dashboard/:id" }, "merchantPolicyId": { "description": "UID of the custom policy created in Forter's Policies tool that resulted in this decision", "type": "string", "example": "0ee8ba28a8654c659addbae9253b707c" }, "orderId": { "description": "Transaction/order ID. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.", "type": "string", "example": "123456" }, "paymentRecommendations": { "allOf": [ { "$ref": "#/components/schemas/PaymentRecommendations" }, { "type": "object", "nullable": true } ] }, "recommendation": { "description": "A specific recommendation for an action that might help the customer to complete their transaction/action (e.g. verify phone via SMS, verify via push notification, verify email, perform a 3DS check, etc.)", "maxLength": 1000, "type": "string", "example": "" }, "verificationMethod": { "$ref": "#/components/schemas/VerificationMethod", "description": "The specific verification method to be used when verification is required according to \"recommendation\" field", "maxLength": 1000 } }, "required": [ "forterDecision", "recommendation", "verificationMethod", "decisionReason", "merchantPolicyId", "orderId", "linkToEventInDashboard" ], "type": "object" }, "validationResponse": { "additionalProperties": false, "description": "The response object of a forter validations call", "properties": { "action": { "description": "The message containing the decision", "maxLength": 1000, "type": "string", "example": "approve" }, "message": { "description": "The message containing status response text", "maxLength": 1000, "type": "string", "example": "" }, "paymentRecommendations": { "allOf": [ { "$ref": "#/components/schemas/PaymentRecommendations" }, { "type": "object", "nullable": true } ] }, "reasonCode": { "maxLength": 1000, "type": "string", "example": "" }, "recommendations": { "description": "Forter's recommendations for the optimal way of proceeding with the order", "items": { "type": "string" }, "maxLength": 1000, "type": "array", "example": [] }, "status": { "description": "Status of the request processing", "maxLength": 50, "type": "string", "example": "success" }, "transaction": { "description": "Transaction id. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.", "maxLength": 100, "type": "string", "example": "123456" } }, "required": [ "message", "action", "recommendations", "reasonCode", "transaction", "status" ], "type": "object" }, "AccountIdentifiersForMerchant": { "additionalProperties": false, "description": "Account identifiers", "properties": { "accountEmail": { "description": "The email associated with the related account", "type": "string", "example": "johns.friend@gmail.com", "nullable": true }, "accountId": { "description": "ID of the related account", "type": "string", "example": "1fd95-ao4z00-4wsd153", "nullable": true } }, "type": "object" }, "AddressAndNameConnection": { "additionalProperties": false, "description": "I was able to connect the following address to the following name using information I found online -", "properties": { "addressRole": { "description": "I was able to connect this address -", "enum": [ "SHIPPING_ADDRESS", "BILLING_ADDRESS", "NA" ], "maxLength": 50, "example": "SHIPPING_ADDRESS", "nullable": true }, "dataSource": { "allOf": [ { "$ref": "#/components/schemas/MerchantAddressDataSources", "description": "Using information I found on this source -", "maxLength": 50 }, { "type": "object", "nullable": true } ] }, "nameRole": { "description": "To this name -", "enum": [ "CARDHOLDER", "BILLING_NAME", "SHIPPING_NAME", "ACCOUNT_HOLDER", "OTHER", "NA" ], "maxLength": 50, "example": "CARDHOLDER", "nullable": true } }, "type": "object" }, "ContactWithCustomer": { "additionalProperties": false, "description": "This object contains information relating to any customer service or customer support assistance or communication relating to the transaction.", "properties": { "contactCustomerIP": { "description": "Customer IP address used to contact the merchant in IPv4 or IPv6 format. Typically available when customer contact is via chat", "type": "string", "x-conditional": true, "example": "10.0.0.127", "nullable": true }, "contactEmailUsed": { "allOf": [ { "$ref": "#/components/schemas/MerchantContactedCustomerEmail", "description": "Email used by customer to contact customer support", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "contactMethodType": { "description": "Method used by customer to contact support", "enum": [ "PHONE", "EMAIL", "CHAT", "SUPPORT_FORM" ], "example": "PHONE" }, "contactNameUsed": { "allOf": [ { "$ref": "#/components/schemas/MerchantContactedCustomerName", "description": "Name of the customer who contacted/was contacted by customer support", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "contactPhoneUsed": { "allOf": [ { "$ref": "#/components/schemas/MerchantContactedCustomerPhone", "description": "Phone used by customer to contact customer support", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "contactTime": { "description": "Time of the latest consumer communication with customer support (e.g. a support ticket was submitted or a merchant agent reached out to the consumer) in seconds since unix epoch (UTC, Jan 1, 1970)", "type": "number", "example": 1430997968 }, "customerSupportChangeOrderDetails": { "allOf": [ { "$ref": "#/components/schemas/CustomerSupportChangeOrderDetails", "description": "Did the customer undergo any further verification?", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "customerSupportFurtherVerification": { "allOf": [ { "$ref": "#/components/schemas/CustomerSupportFurtherVerification", "description": "Did the customer undergo any further verification?", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "initiatedBy": { "description": "The initiator of the interaction", "enum": [ "MERCHANT", "CUSTOMER" ], "example": "CUSTOMER" }, "orderId": { "description": "Unique order id that the service ticket refers to. Should match the order id sent to Forter at checkout. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.", "maxLength": 54, "type": "string", "example": "4306795", "nullable": true }, "ticketId": { "description": "Customer service ticket identifier", "maxLength": 50, "type": "string", "example": "4306795", "nullable": true } }, "required": [ "contactTime", "initiatedBy", "contactMethodType" ], "type": "object" }, "CustomerSupportAdditionalVerificationDocuments": { "additionalProperties": false, "description": "Additional Verification Documents includes any details gained from identifying documents or materials which the customer has shared.", "properties": { "documentFirstName": { "description": "First name as appears on the document", "maxLength": 75, "type": "string", "example": "John", "nullable": true }, "documentLastName": { "description": "Last name as appears on the document", "maxLength": 75, "type": "string", "example": "Smith", "nullable": true }, "documentType": { "description": "Type of document (Passport, ID, Driving license)", "maxLength": 35, "type": "string", "example": "Passport" }, "documentVerified": { "description": "True if document was verified as authentic by merchant or 3rd party service", "type": "boolean", "x-conditional": true, "example": true, "nullable": true }, "nationality": { "description": "Document holder's nationality", "maxLength": 25, "type": "string", "x-conditional": true, "example": "US", "nullable": true } }, "required": [ "documentType" ], "type": "object" }, "CustomerSupportChangeOrderDetails": { "additionalProperties": false, "description": "Did the customer undergo any further verification?", "properties": { "customerSupportRequestPickupFromShippingCarrier": { "description": "The customer would like to pick up his order from the shipping carrier", "type": "boolean", "example": false, "nullable": true }, "customerSupportRequestPickupStoreZip": { "description": "The customer would like to pick up his order from the store located at this zipcode", "maxLength": 20, "type": "string", "example": "94104", "nullable": true }, "customerSupportRequestSwitchBillingAndShipping": { "description": "The customer accidentally typed the shipping address as the billing address. Would like to switch them.", "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "CustomerSupportFurtherVerification": { "additionalProperties": false, "description": "Did the customer undergo any further verification?", "properties": { "customerAnsweredSecurityQuestions": { "description": "The customer successfully answered security questions that only the cardholder should be able to answer", "type": "boolean", "example": true }, "customerSupportAdditionalVerificationDocuments": { "allOf": [ { "$ref": "#/components/schemas/CustomerSupportAdditionalVerificationDocuments", "description": "The customer provided additional documents to verify their identity" }, { "type": "object", "nullable": true } ] }, "customerSupportSMSverification": { "description": "The customer successfully SMS-verified this phone number", "maxLength": 50, "type": "string", "example": "+1-212-555-5555", "nullable": true } }, "required": [ "customerAnsweredSecurityQuestions" ], "type": "object" }, "EstablishedAccountDetails": { "additionalProperties": false, "description": "We believe the account is established because it has the following history with us -", "properties": { "accountAgeInMonths": { "description": "The account has been active for this many months -", "type": "number", "example": 18, "nullable": true }, "accountSpendUSD": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "The account has previously purchased the following total amount -" }, { "type": "object", "nullable": true } ] }, "otherReasonForEstablishedAccount": { "description": "We believe the account is established for another reason -", "type": "string", "example": "", "nullable": true } }, "type": "object" }, "FraudTypeSuspectedByMerchant": { "additionalProperties": false, "description": "I believe this order is likely fraud of this type", "properties": { "merchantInrAbuseType": { "description": "INR Abuse type as labeled by the merchant", "enum": [ "HIGHLIGHTED", "PREVENTED" ], "nullable": true }, "merchantReceivedFraudAlert": { "description": "Fraud Alert - Merchant was notified by a 3rd party tool or other source that the order is fraudulent", "type": "boolean", "nullable": true }, "merchantSuspectsAccountTakeOver": { "allOf": [ { "$ref": "#/components/schemas/ReasonMerchantSuspectsFraud", "description": "Account Take Over - I believe this order was made by a fraudster that committed account take over on an established account" }, { "type": "object", "nullable": true } ] }, "merchantSuspectsBuyerSellerCollusion": { "allOf": [ { "$ref": "#/components/schemas/ReasonMerchantSuspectsFraud", "description": "Buyer-Seller Collusion - I believe this order was made by a fraudster colluding with a seller on the marketplace to extract funds in an illegitimate way" }, { "type": "object", "nullable": true } ] }, "merchantSuspectsCouponAbuse": { "description": "Promotion Abuse - I believe this order was made by an individual trying to abuse our coupon policy (e.g. signing up with new accounts to get more coupons)", "type": "boolean", "nullable": true }, "merchantSuspectsFraudOther": { "allOf": [ { "$ref": "#/components/schemas/ReasonMerchantSuspectsFraud", "description": "Other - I believe this order is fraudulent in a different way" }, { "type": "object", "nullable": true } ] }, "merchantSuspectsFriendlyFraud": { "allOf": [ { "$ref": "#/components/schemas/ReasonMerchantSuspectsFraud", "description": "Friendly Fraud - I believe this order was made by an individual related to the cardholder, but without their authorization (e.g. a child using a parent's credit card without their permission)" }, { "type": "object", "nullable": true } ] }, "merchantSuspectsInrAbuse": { "description": "INR/Refund Abuse - Customer is suspected of INR/refund abuse", "type": "boolean", "nullable": true }, "merchantSuspectsOtherPolicyBreach": { "description": "Breach Of Policy - This order was made by an individual who is in breach of store policy. We do not wish to transact with this customer in the future.", "type": "boolean", "nullable": true }, "merchantSuspectsPromotionAbuse": { "description": "Promotion Abuse - Customer is suspected of promotion abuse", "type": "boolean", "nullable": true }, "merchantSuspectsResellerAbuse": { "description": "Reseller Abuse - Customer is suspected of reseller abuse", "type": "boolean", "nullable": true }, "merchantSuspectsReturnAbuse": { "description": "Returns Abuse - Customer is suspected of returns abuse", "type": "boolean", "nullable": true }, "merchantSuspectsStolenPaymentMethod": { "allOf": [ { "$ref": "#/components/schemas/ReasonMerchantSuspectsFraud", "description": "Stolen Payment Methods - I believe this order was made by a fraudster using a stolen payment method (credit card, or other)" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "GoodCustomerAccordingToMerchant": { "additionalProperties": false, "description": "I believe the customer's characteristics and history indicate this is likely a good order", "properties": { "establishedAccount": { "allOf": [ { "$ref": "#/components/schemas/MerchantConsidersAccountEstablished", "description": "This customer has a well established history with us, or is related to another well established account" }, { "type": "object", "nullable": true } ] }, "forterPreviouslyApproved": { "description": "Forter previously approved this customer", "type": "boolean", "nullable": true }, "knowCustomerPersonally": { "description": "I know this customer personally (company employee, family member, etc.)", "enum": [ "COMPANY_EMPLOYEE_OR_RELATED_TO_ONE", "COMPANY_BUSINESS_ASSOCIATE_OR_SERVICE_PROVIDER", "TESTING_ACCOUNT", "OTHER", "NA" ], "nullable": true }, "merchantHasGoodScoreElsewhere": { "description": "This order has a good score on another fraud tool (internal or 3rd party) and I think it is probably a good order", "enum": [ "INTERNAL_SCORE", "THIRD_PARTY_TOOL", "NA" ], "example": "INTERNAL_SCORE", "nullable": true }, "previousPointOfSalePurchase": { "allOf": [ { "$ref": "#/components/schemas/PastPointOfSalePurchase", "description": "Customer previously made purchases in a physical store, and we believe that is a good indicator" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "GoodOrderCharachteristicsAccordingToMerchant": { "additionalProperties": false, "description": "I believe the customer and/or the order characteristics indicate this is likely a good order", "properties": { "goodCustomer": { "allOf": [ { "$ref": "#/components/schemas/GoodCustomerAccordingToMerchant", "description": "I believe the customer's characteristics and history indicate this is likely a good order" }, { "type": "object", "nullable": true } ] }, "lowRiskItem": { "description": "In our experience, the item purchased is a low-risk item", "type": "boolean", "example": false, "nullable": true }, "lowRiskPaymentMethod": { "allOf": [ { "$ref": "#/components/schemas/LowRiskPaymentMethodsAccordingToMerchant", "description": "In our experience, the payment method this customer used now, or in the past, is a good indicator" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "LowRiskPaymentMethodsAccordingToMerchant": { "additionalProperties": false, "description": "Payment method -", "properties": { "giftCard": { "description": "Gift Card", "type": "boolean", "example": false, "nullable": true }, "other": { "description": "Other payment method", "type": "string", "example": "Apple Pay", "nullable": true }, "storeCredit": { "description": "Store Credit", "type": "boolean", "example": false, "nullable": true }, "wireTransfer": { "description": "Wire transfer or other direct forms of payment", "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "MerchantAccountTakeOverFeedback": { "additionalProperties": false, "description": "This was declined because suspected Account Take Over, but I don't think this is the case", "properties": { "confirmedValidAccountOwnerUsingOldEmail": { "description": "I was able to confirm this order with the original account holder (or they contacted me) using the original EMAIL ADDRESS connected to the account", "type": "boolean", "example": false, "nullable": true }, "confirmedValidAccountOwnerUsingOldPhone": { "description": "I was able to confirm this order with the original account holder (or they contacted me) using the original PHONE connected to the account", "type": "boolean", "example": false, "nullable": true }, "notATOBecauseOfOtherReason": { "description": "I don't think this is an Account Take Over because of a different reason", "type": "string", "example": "Password wasn't reset", "nullable": true }, "notATOBecauseOldDeviceUsed": { "description": "I don't think this is an Account Take Over since the same or similar device is used as has been in previous orders by the original account holder", "type": "boolean", "example": false, "nullable": true }, "notATOBecauseOldIPUsed": { "description": "I don't think this is an Account Take Over since the same or similar IP is used as has been in previous orders by the original account holder", "type": "boolean", "example": false, "nullable": true }, "notATOBecauseSimilarItemPurchased": { "description": "I don't think this is an Account Take Over since the purchasing patterns are similar to those of the original account holder (same item, similar amounts and frequency, etc.)", "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "MerchantAddressDataSources": { "additionalProperties": false, "description": "Found datapoint on -", "properties": { "googleSearch": { "description": "Online search (Google, Bing, etc.)", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "otherSource": { "description": "Other", "maxLength": 50, "type": "string", "example": "SearchPerson.com", "nullable": true }, "whitePages": { "description": "White Pages", "maxLength": 50, "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "MerchantChargebackFeedback": { "additionalProperties": false, "description": "This was declined because of connection to previous chargebacks, but I don't think it should be declined", "properties": { "cannotFindRelatedChargebacks": { "description": "I can't find any chargeback related to this order or account", "type": "boolean", "example": false, "nullable": true }, "chbksResolved": { "description": "The chargebacks connected to this account were not truly fraud-related, and were already resolved with the customer", "type": "boolean", "example": false, "nullable": true }, "chbksResolvedOrderIds": { "description": "These are the IDs of the resolved chargebacks. After removing these chargebacks, they will no longer be covered by Forter, since they will be considered service-related", "items": { "type": "string" }, "type": "array", "nullable": true } }, "type": "object" }, "MerchantConsidersAccountEstablished": { "additionalProperties": false, "description": "This is an established account or it is related to another established account", "properties": { "establishedAccountDetails": { "allOf": [ { "$ref": "#/components/schemas/EstablishedAccountDetails", "description": "We believe the account is established because it has the following history with us -" }, { "type": "object", "nullable": true } ] }, "relatedAccountDetails": { "allOf": [ { "$ref": "#/components/schemas/AccountIdentifiersForMerchant", "description": "The established account is not the one that made the order, but it is related to it, and these are the established account's details" }, { "type": "object", "nullable": true } ] }, "relatedToAnEstablishedAccount": { "description": "The account that created this order is related to a well established account", "type": "boolean", "example": false, "nullable": true }, "thisIsAnEstablishedAccount": { "description": "The account that created this order is a well established account", "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "MerchantContactedCustomerEmail": { "additionalProperties": false, "description": "I was able to confirm the order with the customer over email", "properties": { "merchantContactedEmail": { "description": "email used to contact the customer (if not one of the emails used in the order)", "maxLength": 75, "type": "string", "example": "jsmith@gmail.com", "nullable": true }, "merchantContactedEmailRole": { "description": "I used the following phone to contact the customer", "enum": [ "BILLING_EMAIL", "SHIPPING_EMAIL", "ACCOUNT_EMAIL", "OTHER_EMAIL", "NA" ], "example": "BILLING_EMAIL", "nullable": true } }, "type": "object" }, "MerchantContactedCustomerName": { "additionalProperties": false, "description": "Details about the contact (name) used by customer to contact customer support.", "properties": { "customerContactNameType": { "description": "The role of the contact (name) that interacted with customer support.", "enum": [ "CARDHOLDER", "BILLING_NAME", "SHIPPING_NAME", "ACCOUNT_HOLDER", "OTHER", "NA" ], "example": "OTHER" }, "customerFirstName": { "description": "First name of the person who contacted the merchant's customer support", "maxLength": 75, "type": "string", "x-conditional": true, "example": "John", "nullable": true }, "customerLastName": { "description": "Last name of the person who contacted the merchant's customer support", "maxLength": 75, "type": "string", "x-conditional": true, "example": "Smith", "nullable": true } }, "required": [ "customerContactNameType" ], "type": "object" }, "MerchantContactedCustomerPhone": { "additionalProperties": false, "description": "I was able to confirm the order with the customer over the phone", "properties": { "merchantContactedPhoneNumber": { "description": "Phone number used (if not one of the phones used in the order)", "type": "string", "example": "212-555-5555", "nullable": true }, "merchantContactedPhoneRole": { "description": "I used the following phone to contact the customer", "enum": [ "BILLING_PHONE", "SHIPPING_PHONE", "ACCOUNT_PHONE", "OTHER_PHONE", "NA" ], "example": "BILLING_PHONE", "nullable": true } }, "type": "object" }, "MerchantExposureSources": { "additionalProperties": false, "description": "Found datapoint on -", "properties": { "facebook": { "description": "Facebook", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "googlePlus": { "description": "Google+", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "googleSearch": { "description": "Online search (Google, Bing, etc.)", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "linkedin": { "description": "LinkedIn", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "otherSocialNetwork": { "description": "Other Social Network", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "otherSource": { "description": "Other", "maxLength": 50, "type": "string", "example": "SearchPerson.com", "nullable": true }, "whitePages": { "description": "White Pages", "maxLength": 50, "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "MerchantFeedback": { "additionalProperties": false, "description": "A Forter internal property to allow the Forter dashboard to receive merchant feedback and relay it back to the system in a structured way", "properties": { "agentGeneralImpression": { "description": "What is your general impression of the customer following your interaction/analysis (do you believe he is suspicious? do you believe he is legitimate?)", "enum": [ "CUSTOMER_IS_LEGIT", "I_DONT_KNOW", "CUSTOMER_IS_SUSPICIOUS" ], "maxLength": 75, "x-conditional": true, "example": "I_DONT_KNOW", "nullable": true }, "doesNotAffectFutureDecisions": { "description": "A property to allow the Forter dashboard to receive information from the risk agent in case the agent adds information for training the model with more data, without triggering a decision change", "type": "boolean", "nullable": true }, "feedbackAppliesToAllFutureDecisionsUntil": { "description": "Until this timestamp (epoch seconds), the feedback will apply to all future transactions of this type", "type": "number", "example": 1430997968, "nullable": true }, "isFutureDecision": { "description": "Use the new decision only for next order sent by the user. The current order fulfillment status will not change due to the new decision provided.", "type": "boolean", "nullable": true }, "isPolicyApprove": { "description": "Set to true if the customer has been previously declined, but should be approved as a matter of policy in their next transaction.", "type": "boolean", "nullable": true }, "merchantCustomerSupport": { "allOf": [ { "$ref": "#/components/schemas/ContactWithCustomer", "description": "A Forter internal property to allow Forter to receive details about merchant interactions with the customer after the order was submitted" }, { "type": "object", "nullable": true } ] }, "merchantWouldLikeApproved": { "allOf": [ { "$ref": "#/components/schemas/MerchantRiskAnalysisAdditionalPositiveIndicators", "description": "A Forter internal property to allow Forter to receive additional input from the risk agent in case the agent feels that the order should be approved and relay it to the system in a structured way" }, { "type": "object", "nullable": true } ] }, "merchantWouldLikeDeclined": { "allOf": [ { "$ref": "#/components/schemas/MerchantRiskAnalysisAdditionalNegativeIndicators", "description": "A Forter internal property to allow the Forter dashboard to receive input from the risk agent in case the agent feels that the order should be declined and relay it to the system in a structured way" }, { "type": "object", "nullable": true } ] }, "undoPreviousFeedback": { "description": "A property to allow the customer to reset all previous feedbacks given on the session, previous feedbacks will not affect the model anymore", "type": "boolean", "nullable": true } }, "type": "object" }, "MerchantFoundBuyerExposure": { "additionalProperties": false, "description": "I was able to validate some of the order's details online", "properties": { "customerSignedInUsingLegitSocialNetworkAccount": { "allOf": [ { "$ref": "#/components/schemas/CustomerRegistrationSources", "description": "Account owner signed-in using a legitimate, well established Social Network account", "maxLength": 50 }, { "type": "object", "nullable": true } ] }, "merchantFoundBuyerEmailOnline": { "allOf": [ { "$ref": "#/components/schemas/MerchantExposureSources", "description": "I was able to find the customer's Email address online, and link it to the card holder" }, { "type": "object", "nullable": true } ] }, "merchantFoundBuyerPhoneNumberOnline": { "allOf": [ { "$ref": "#/components/schemas/MerchantExposureSources", "description": "I was able to find the customer's phone number online, and link it to the card holder" }, { "type": "object", "nullable": true } ] }, "merchantFoundConnectionBetweenIndividualsInTheOrder": { "$ref": "#/components/schemas/NameAndNameConnection", "description": "I was able to find a connection between the cardholder and the recipient of the order -" }, "merchantFoundConnectionBetweenNameAndAddress": { "$ref": "#/components/schemas/AddressAndNameConnection", "description": "I was able to find a connection between some of the addresses in the order and some of the names -" }, "merchantFoundLegitShippingAddress": { "description": "I was able to identify the order's shipping address as a non-fraud indication", "enum": [ "AN_OFFICE_OR_OTHER_WORKPLACE_RELATED_TO_THE_CUSTOMER", "A_MILITARY_OR_OTHER_GOVERNMENT_FACILITY_OR_INSTITUTION", "SHIPPING_ADDRESS_IS_SAME_AS_BILLING_ADDRESS_AND_AVS_CHECK_MATCHES", "NA" ], "nullable": true }, "merchantFoundRecipientEmailOnline": { "allOf": [ { "$ref": "#/components/schemas/MerchantExposureSources", "description": "I was able to find the order's recipient Email address online, and link it to the card holder" }, { "type": "object", "nullable": true } ] }, "merchantFoundRecipientPhoneNumberOnline": { "allOf": [ { "$ref": "#/components/schemas/MerchantExposureSources", "description": "I was able to find the order's recipient phone number online, and link it to the card holder" }, { "type": "object", "nullable": true } ] } }, "required": [ "merchantFoundConnectionBetweenNameAndAddress", "merchantFoundConnectionBetweenIndividualsInTheOrder" ], "type": "object" }, "MerchantNameDataSources": { "additionalProperties": false, "description": "Found datapoint on -", "properties": { "googleSearch": { "description": "Online search (Google, Bing, etc.)", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "otherSource": { "description": "Other", "maxLength": 50, "type": "string", "example": "SearchPerson.com", "nullable": true }, "socialNetwork": { "description": "Social Network", "maxLength": 50, "type": "boolean", "example": false, "nullable": true }, "whitePages": { "description": "White Pages", "maxLength": 50, "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "MerchantRiskAnalysisAdditionalNegativeIndicators": { "additionalProperties": false, "description": "I believe the order is fraudulent and should be not be approved", "properties": { "fraudTypeSuspectedByMerchant": { "allOf": [ { "$ref": "#/components/schemas/FraudTypeSuspectedByMerchant", "description": "I believe this order is likely fraud of this type" }, { "type": "object", "nullable": true } ] }, "merchantConfidenceLevelThisIsFraud": { "description": "My level of confidence that this order is fraudulent", "enum": [ "NOT_SURE_COMMA_LOOKS_SUSPICIOUS", "HIGH_CONFIDENCE_THIS_IS_FRAUD", "VICTIM_CONFIRMED_THIS_IS_FRAUD" ], "example": "NOT_SURE_COMMA_LOOKS_SUSPICIOUS", "nullable": true }, "merchantThinksPolicyShouldApply": { "description": "I believe the order should not be approved since it is in breach of this business policy that we would like Forter to enforce", "maxLength": 200, "type": "string", "example": "Decline all non-US domestic orders", "nullable": true } }, "type": "object" }, "MerchantRiskAnalysisAdditionalPositiveIndicators": { "additionalProperties": false, "description": "Indicators found by the merchant risk team which leads the agent to believe the order is not fraudulent and should be approved", "properties": { "merchantContactedIssuer": { "allOf": [ { "$ref": "#/components/schemas/merchantContactedIssuer", "description": "I was able to verify the cardholder's details with the issuing bank" }, { "type": "object", "nullable": true } ] }, "merchantDisagreesWithSpecificDeclineReason": { "allOf": [ { "$ref": "#/components/schemas/MerchantSpecificReasonFeedback", "description": "I understand the specific decline reason, but I disagree (e.g. I don't think this is an ATO)" }, { "type": "object", "nullable": true } ] }, "merchantFoundBuyerExposure": { "allOf": [ { "$ref": "#/components/schemas/MerchantFoundBuyerExposure", "description": "I was able to validate some of the order's details online" }, { "type": "object", "nullable": true } ] }, "merchantPolicyDecisionNotApplicable": { "allOf": [ { "$ref": "#/components/schemas/merchantPolicyDecisionNotApplicable", "description": "I believe the policy does not apply to the customer" }, { "type": "object", "nullable": true } ] }, "merchantThinksOrderCharacteristicsAreLegit": { "allOf": [ { "$ref": "#/components/schemas/GoodOrderCharachteristicsAccordingToMerchant", "description": "I believe the customer and/or the order characteristics indicate this is likely a good order" }, { "type": "object", "nullable": true } ] } }, "type": "object" }, "MerchantSpecificReasonFeedback": { "additionalProperties": false, "description": "I understand the specific decline reason, but I disagree (e.g. I don't think this is an ATO)", "properties": { "atoIsIrrelevant": { "allOf": [ { "$ref": "#/components/schemas/MerchantAccountTakeOverFeedback", "description": "This was declined because suspected Account Take Over, but I don't think this is the case" }, { "type": "object", "nullable": true } ] }, "chbkIsIrrelevant": { "allOf": [ { "$ref": "#/components/schemas/MerchantChargebackFeedback", "description": "This was declined because of connection to previous chargebacks, but I don't think it should be declined" }, { "type": "object", "nullable": true } ] }, "couponAbuseIsIrrelevant": { "description": "This was declined because of suspected coupon abuse, but I think this is a legitimate use of coupons and would like to approve", "type": "boolean", "example": false, "nullable": true }, "multipleLinksAreIrrelevant": { "description": "Could not find multiple accounts related to this account holder (available only for account feedback)", "type": "boolean", "example": false, "nullable": true }, "policyNotApplicable": { "description": "This is marked as a merchant policy decline, but I don't think the policy is applicable here (e.g. a US order being declined under a international order blocking policy)", "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "NameAndNameConnection": { "additionalProperties": false, "description": "I was able to connect the two people involved in the order using the following data sources -", "properties": { "connectionType": { "description": "These people are connected because they are -", "enum": [ "FAMILY", "FRIENDS", "HAVE_A_PERSONAL_RELATIONSHIP", "WORK_TOGETHER", "HAVE_A_BUSINESS_RELATIONSHIP", "NA" ], "maxLength": 50, "example": "FAMILY", "nullable": true }, "dataSource": { "allOf": [ { "$ref": "#/components/schemas/MerchantNameDataSources", "description": "Using information I found on this source -", "maxLength": 50 }, { "type": "object", "nullable": true } ] }, "nameRole1": { "description": "I was able to connect this person -", "enum": [ "CARDHOLDER", "BILLING_NAME", "SHIPPING_NAME", "ACCOUNT_HOLDER", "OTHER", "NA" ], "maxLength": 50, "example": "CARDHOLDER", "nullable": true }, "nameRole2": { "description": "To this person -", "enum": [ "CARDHOLDER", "BILLING_NAME", "SHIPPING_NAME", "ACCOUNT_HOLDER", "OTHER", "NA" ], "maxLength": 50, "example": "SHIPPING_NAME", "nullable": true } }, "type": "object" }, "PastPointOfSalePurchase": { "additionalProperties": false, "description": "Customer previously made purchases in a physical store -", "properties": { "madePointOfSalePurchase": { "description": "Customer made purchases in a physical store in the past", "type": "boolean", "example": false, "nullable": true }, "pointOfSalePurchaseState": { "description": "Purchase was made in a store located in the following state / region", "type": "string", "example": "NY", "nullable": true }, "pointOfSalePurchaseZip": { "description": "Purchase was made in a store located in the following zipcode", "type": "string", "example": "10001", "nullable": true } }, "type": "object" }, "ReasonMerchantSuspectsFraud": { "additionalProperties": false, "description": "I believe the order is fraudulent and this is why", "properties": { "merchantSuspectsAccountDetails": { "allOf": [ { "$ref": "#/components/schemas/SuspiciousAccountDetails", "description": "The account's behavior seems suspicious" }, { "type": "object", "nullable": true } ] }, "merchantSuspectsOrderDetails": { "allOf": [ { "$ref": "#/components/schemas/SuspiciousOrderDetails", "description": "The order details seem suspicious, or cannot be connected to the card holder" }, { "type": "object", "nullable": true } ] }, "merchantWasContactedByVictim": { "description": "The victim of this fraud attempt contacted us to complain (cardholder, or account owner in case of account takeover)", "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "SuspiciousAccountDetails": { "additionalProperties": false, "description": "These are the fraud indicators I identify in this account", "properties": { "accountDetailsWereChanged": { "description": "Account details were recently changed in a way that is suspicious", "type": "boolean", "example": true, "nullable": true }, "highVelocity": { "description": "Purchase frequency and amount is too high, and is likely fraudulent", "type": "boolean", "example": true, "nullable": true }, "inactiveAccount": { "description": "Account was inactive for a very long time and is now displaying suspicious behaviour", "type": "boolean", "example": true, "nullable": true }, "linkedToMultipleAccounts": { "description": "Identified multiple accounts linked to this account holder (available only for account feedback)", "type": "boolean", "example": true, "nullable": true }, "other": { "description": "Other (available only for account feedback)", "type": "boolean", "example": true, "nullable": true } }, "type": "object" }, "SuspiciousOrderDetails": { "additionalProperties": false, "description": "These are the fraud indicators I identify in this order", "properties": { "badItem": { "description": "Item purchased is a strong fraud indicator", "type": "boolean", "example": true, "nullable": true }, "badShippingAddress": { "description": "Shipping address seems suspicious", "type": "boolean", "example": true, "nullable": true }, "fakeEmail": { "description": "The email seems fake, or related to a suspicious persona, or to a person completely unrelated to the order", "type": "boolean", "example": true, "nullable": true }, "other": { "description": "Other (this option will only be open for account feedback)", "type": "boolean", "example": true, "nullable": true } }, "type": "object" }, "merchantContactedIssuer": { "additionalProperties": false, "description": "I was able to verify the cardholder's details with the issuing bank", "properties": { "accessToBankAccountVerifiedByCustomer": { "description": "Using a strong verification method, the customer has verified access to the bank account", "type": "boolean", "example": false, "nullable": true }, "issuerNameOnCardMatch": { "description": "According to the issuing bank, the cardholder's name matches their records", "enum": [ "MATCH", "MISMATCH", "DID_NOT_CHECK", "UNKNOWN", "NA" ], "example": "UNKNOWN", "nullable": true }, "issuerPhoneMatch": { "description": "According to the issuing bank, the billing phone matches their records", "enum": [ "MATCH", "MISMATCH", "DID_NOT_CHECK", "UNKNOWN", "NA" ], "example": "UNKNOWN", "nullable": true }, "issuerStreetAddressMatch": { "description": "According to the issuing bank, the billing street address matches their records", "enum": [ "MATCH", "MISMATCH", "DID_NOT_CHECK", "UNKNOWN", "NA" ], "example": "UNKNOWN", "nullable": true }, "issuerZipMatch": { "description": "According to the issuing bank, the billing zip code matches their records", "enum": [ "MATCH", "MISMATCH", "DID_NOT_CHECK", "UNKNOWN", "NA" ], "example": "UNKNOWN", "nullable": true } }, "type": "object" }, "merchantPolicyDecisionNotApplicable": { "additionalProperties": false, "description": "Merchant does not think the following policies apply to the user", "properties": { "inrAbuseNotApplicable": { "description": "INR Abuse - INR/Refund abuse policy is not applicable", "type": "boolean", "nullable": true }, "multipleLinksPolicyNotApplicable": { "description": "Multiple Account Abuse - Merchant unique account policy is not applicable", "type": "boolean", "nullable": true }, "promotionAbuseNotApplicable": { "description": "Promotion Abuse - Promotion abuse policy is not applicable", "type": "boolean", "nullable": true }, "resellerAbuseNotApplicable": { "description": "Reseller Abuse - Reseller abuse policy is not applicable", "type": "boolean", "nullable": true }, "returnsAbuseNotApplicable": { "description": "Returns Abuse - Returns abuse policy is not applicable", "type": "boolean", "nullable": true } }, "type": "object" }, "validationUpdateRequest": { "additionalProperties": true, "description": "For orders placed over the phone, add the customer's connection information to receive a fraud or abuse decision.", "properties": { "connectionInformation": { "allOf": [ { "$ref": "#/components/schemas/ConnectionInformation", "description": "Connection information about the customer (typically found in the HTTP request header). Internal merchant system data should not be sent.", "x-conditional": true }, { "type": "object", "nullable": true } ] }, "merchantFeedback": { "allOf": [ { "$ref": "#/components/schemas/MerchantFeedback", "description": "Feedback submitted by the merchant's customer-support or risk agent. This will trigger a recalculation with the new information and will generate a new decision for the merchant" }, { "type": "object", "nullable": true } ] }, "orderId": { "description": "Unique order/transaction identifier. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.", "maxLength": 54, "type": "string", "example": "2356fdse0rr489" }, "orderType": { "description": "Platform order was made through", "enum": [ "WEB", "PHONE", "DYNAMIC_PHONE", "MOBILE", "MOBILE_IN_STORE", "IOS", "ANDROID", "WAP", "STORE", "MERCHANT_EMPLOYEE", "MAIL_ORDER", "AUTOMATIC_RENEWAL_OR_INSTALLMENT_PAYMENT", "MERCHANT_INITIATED", "UNKNOWN", "POS", "API_ONLY", "PERSONAL_POS", "PHONE_LINK", "AI_AGENT" ], "example": "PHONE_LINK", "nullable": true }, "payment": { "description": "A list of all payment methods and billing details used in the transaction", "items": { "$ref": "#/components/schemas/Payment" }, "type": "array", "nullable": true }, "primaryRecipient": { "allOf": [ { "$ref": "#/components/schemas/Beneficiary", "description": "Primary recipient of the transaction goods. It should correspond with the primary delivery method and can include notes the customer included as part of their transaction, whether directed to the merchant or to the intended recipient." }, { "type": "object", "nullable": true } ] }, "totalAmount": { "allOf": [ { "$ref": "#/components/schemas/Amount", "description": "Total amount of the transaction (after reducing any discount)" }, { "type": "object", "nullable": true } ] } }, "required": [ "orderId" ], "type": "object" }, "Error": { "type": "object", "description": "Canonical typed error envelope. Returned by every 4xx and 5xx response on the Forter REST API and the x402 / MPP demo surfaces. The five response components (BadRequest, Unauthorized, NotFound, ServerError, TooManyRequests) all wrap this schema. ACP-shaped error responses use the flat AcpError schema instead. Each error carries a stable `type` token, a human-readable `message`, a Forter-side `request_id` for support escalation, and a `retry_hint` indicating whether the call is safely retryable and after how long.", "required": [ "type", "message", "request_id", "retry_hint" ], "properties": { "type": { "type": "string", "description": "Stable, machine-readable error token.", "example": "rate_limited" }, "message": { "type": "string", "description": "Human-readable explanation, one sentence.", "example": "The client exceeded the request rate limit for this endpoint." }, "request_id": { "type": "string", "description": "Opaque request identifier; echo it when contacting Forter support." }, "retry_hint": { "type": "string", "description": "How the client should retry: retry_now, retry_after_seconds:N, or do_not_retry.", "example": "retry_after_seconds:30" }, "details": { "type": "array", "description": "Optional field-level validation errors.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "issue": { "type": "string" } } } } }, "examples": { "rate_limited": { "summary": "HTTP 429 - back off using Retry-After.", "value": { "type": "rate_limited", "message": "Request rate exceeded for this Site ID. Honor Retry-After before retrying.", "request_id": "01J5K8MQ9C2P3R4T5V6W7X8Y9Z", "retry_hint": { "retryable": true, "after_seconds": 60, "strategy": "exponential_backoff" } } }, "unauthorized": { "summary": "HTTP 401 - bad or missing credentials.", "value": { "type": "unauthorized", "message": "Invalid API key or missing X-Forter-SiteId / Api-Version header.", "request_id": "01J5K8MR0E2N5Q3T4V6W8X9Y1Z", "retry_hint": { "retryable": false, "remediation": "Re-issue credentials at https://portal.forter.com." } } }, "idempotency_conflict": { "summary": "HTTP 409 - same {id} previously completed.", "value": { "type": "idempotency_conflict", "message": "A request with this id has already been processed; the original response is canonical.", "request_id": "01J5K8MS1F3M6P4S5U7V9X0Y2Z", "retry_hint": { "retryable": false, "note": "Use a fresh {id} for a new logical order." } } }, "server_error": { "summary": "HTTP 5xx - Forter-side incident.", "value": { "type": "server_error", "message": "Forter is experiencing a service degradation.", "request_id": "01J5K8MT2G4L7P5R6U8W0Y1Z3A", "retry_hint": { "retryable": true, "strategy": "exponential_backoff" } } } } }, "DemoPaymentObject": { "type": "object", "description": "Canned, demo-only payment/quote object. Forter does not sell goods or take real payment.", "properties": { "object": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "availability": { "type": "object" } }, "additionalProperties": true }, "AcpError": { "type": "object", "description": "ACP (Agentic Commerce Protocol) error object - FLAT, not wrapped in an 'error' envelope. Returned by every error response on the ACP demo surfaces (/checkout_sessions* and /agentic_commerce/delegate_payment). The canonical Forter REST API uses the Error schema instead.", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "description": "ACP error type.", "enum": [ "invalid_request", "request_not_idempotent", "processing_error", "service_unavailable" ], "example": "invalid_request" }, "code": { "type": "string", "description": "Machine-readable error code.", "example": "missing_header" }, "message": { "type": "string", "description": "Human-readable explanation, one sentence." }, "param": { "type": "string", "description": "The offending request field or header, when applicable." }, "supported_versions": { "type": "array", "items": { "type": "string" }, "description": "ACP API versions this endpoint accepts.", "example": [ "2025-09-29" ] } } }, "CheckoutSession": { "type": "object", "description": "ACP checkout session (DEMO surface). Forter is a fraud-prevention platform and does not sell goods or take real payment - responses are canned demo objects.", "additionalProperties": true, "properties": { "id": { "type": "string", "example": "cs_demo_290caed9c8d1417e" }, "object": { "type": "string", "enum": [ "checkout_session" ] }, "status": { "type": "string", "enum": [ "open", "complete", "canceled" ] }, "intent": { "type": "object", "additionalProperties": true }, "payment_methods": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "fraud_decisioning": { "type": "object", "additionalProperties": true, "description": "Demo Forter decision block. decision is one of APPROVE, DECLINE, VERIFICATION_REQUIRED, NOT_REVIEWED." }, "idempotency_key": { "type": "string", "nullable": true }, "livemode": { "type": "boolean", "example": false }, "created": { "type": "integer", "description": "Unix timestamp (seconds)." } } }, "DelegatedPayment": { "type": "object", "description": "ACP delegated-payment result (DEMO surface). Returns a SYNTHETIC vault token - not PCI-compliant, test cards only.", "additionalProperties": true, "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "delegated_payment" ] }, "status": { "type": "string", "example": "demo-issued" }, "vault_token": { "type": "string", "description": "Synthetic demo vault token - never a real payment credential." }, "payment_method": { "type": "object", "additionalProperties": true }, "allowance": { "type": "object", "additionalProperties": true, "description": "Scoped spend allowance: max amount, currency, expiry, merchant scope." }, "risk_signals": { "type": "object", "additionalProperties": true, "nullable": true }, "livemode": { "type": "boolean", "example": false } } }, "PaymentRequiredChallenge": { "type": "object", "description": "HTTP 402 payment-required challenge body returned by the x402 / MPP demo surfaces.", "additionalProperties": true }, "PaginationEnvelope": { "type": "object", "description": "Cursor-pagination envelope. Forter REST endpoints return single-resource responses today and do not paginate; this schema documents the convention for future list endpoints.", "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null when there are no more results." }, "has_more": { "type": "boolean", "description": "True if more pages exist after the current one." } } }, "DemoBatchOperationItem": { "type": "object", "description": "One operation in a /batch request. DEMO-ONLY (responses are canned).", "required": [ "kind" ], "properties": { "id": { "type": "string", "maxLength": 64, "description": "Caller-assigned op id; echoed in the polling response so callers correlate." }, "kind": { "type": "string", "enum": [ "order", "login", "signup", "authentication-result", "order-update", "order-status", "nlweb_ask" ], "description": "Selects which canonical Forter operation shape this op simulates." }, "data": { "description": "Kind-specific payload. Hashed (SHA-256) into the job spec; never echoed in the polling response." } } }, "DemoBatchEnvelope": { "type": "object", "description": "Envelope form for /batch - equivalent to a bare array body.", "required": [ "operations" ], "properties": { "operations": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/DemoBatchOperationItem" } } } }, "DemoBatchIndex": { "type": "object", "description": "GET /batch response - surface inventory.", "properties": { "object": { "type": "string", "enum": [ "batch_index" ] }, "pattern": { "type": "string", "enum": [ "202-accepted-with-location" ] }, "request_shapes": { "type": "object" }, "supported_kinds": { "type": "array", "items": { "type": "string" } }, "max_operations": { "type": "integer" }, "poll_url_template": { "type": "string", "format": "uri" }, "example": { "type": "object" }, "availability": { "type": "object" } } }, "BatchRequest": { "type": "object", "description": "Forter batch / bulk request envelope. Forter REST endpoints are single-event today and do not accept batches; this schema documents the convention for future bulk endpoints.", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "description": "The per-item payloads to process in this batch. Order is preserved in the response.", "items": { "type": "object", "additionalProperties": true } } } }, "BatchItemResult": { "type": "object", "description": "Result for a single item in a batch / bulk response.", "required": [ "index", "status" ], "properties": { "index": { "type": "integer", "description": "0-based position of this item in the request `items` array." }, "status": { "type": "string", "enum": [ "succeeded", "failed" ], "description": "Per-item outcome - items succeed or fail independently." }, "data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "The single-item response payload when `status: succeeded`." }, "error": { "$ref": "#/components/schemas/Error", "description": "Typed error when `status: failed`." } } }, "BatchResponse": { "type": "object", "description": "Forter batch / bulk response envelope. Carries one result per input item; items succeed or fail independently - the top-level HTTP status is 200 unless the whole call could not be processed.", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchItemResult" }, "description": "Per-item results in the same order as the request `items` array." } } } }, "responses": { "BadRequest": { "description": "Bad Request (Often missing a required parameter)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Unauthorized (No valid API key provided)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not Found (The requested item doesn't exist)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "Server Error (Something went wrong on Forter's end)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Too Many Requests (The client exceeded a rate limit). Honor Retry-After before retrying.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request quota for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch (seconds) when the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated unique key that makes a write idempotent: a retry carrying the same key returns the original result instead of creating a duplicate. Required on ACP write operations.", "schema": { "type": "string", "example": "a1b2c3d4-0000-4000-8000-000000000000" } }, "AcpApiVersion": { "name": "API-Version", "in": "header", "required": true, "description": "ACP API version in YYYY-MM-DD form. If the version is unsupported the endpoint returns an ACP-shaped error carrying supported_versions so the agent can negotiate.", "schema": { "type": "string", "example": "2025-09-29" } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Forter cursor pagination - opaque cursor from a prior response. Reserved for future list endpoints.", "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Forter cursor pagination - maximum items per page. Reserved for future list endpoints.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } }, "BatchSize": { "name": "batch_size", "in": "query", "required": false, "description": "Forter batch convention - preferred per-batch item count for chunking large workloads. Reserved for future bulk endpoints.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } } }, "security": [], "paths": { "/batch": { "post": { "operationId": "DemoBatchSubmit", "summary": "DEMO - submit a batch of decisioning operations", "description": "**Demo-only batch surface published on www.forter.com for AI agent readiness, NOT on api.forter-secure.com.** Accepts an array of operations (or an `{ operations: [...] }` envelope) and returns 202 Accepted with `Location: /batch/jobs/` + `Retry-After: 1`. Poll the URL until `status=completed`. Per-operation responses are canned (decision=NOT_REVIEWED) - production batch decisioning requires the real REST API with credentials issued at https://portal.forter.com after a signed MSA. The canonical (production) Forter REST surface remains single-event today; this batch endpoint exists strictly so AI scanners can verify the 202+polling pattern end-to-end against a reachable URL. See also: the BatchRequest / BatchResponse / BatchItemResult / BatchSize component schemas and the root `x-batch` extension below.", "tags": [ "demo", "batch", "agent-readiness" ], "servers": [ { "url": "https://www.forter.com", "description": "Demo / agent-readiness sandbox (NOT the production REST API at api.forter-secure.com)" } ], "security": [], "x-demo-only": true, "x-production-alternative": { "host": "https://api.forter-secure.com", "credential_source": "https://portal.forter.com", "contact": "https://www.forter.com/contact-us/" }, "x-async-pattern": { "type": "202-accepted-with-location", "poll_url_template": "https://www.forter.com/batch/jobs/{job_id}", "terminal_status": "completed", "retry_after_seconds": 1 }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional. Folded into the returned job_id so a retry with the same key + body yields the same poll URL." } ], "requestBody": { "required": true, "description": "Array of batch operations. Each item is `{ id, kind, data }` where `kind` is one of: order, login, signup, authentication-result, order-update, order-status, nlweb_ask. Max 50 items per batch. An envelope form `{ \"operations\": [...] }` is also accepted (see DemoBatchEnvelope).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/DemoBatchOperationItem" } }, { "$ref": "#/components/schemas/DemoBatchEnvelope" } ] }, "examples": { "array": { "summary": "Array body", "value": [ { "id": "op-1", "kind": "order", "data": { "cardLast4": "4242", "totalAmount": { "amountUSD": 129.99 } } }, { "id": "op-2", "kind": "login", "data": { "email": "user@example.com" } } ] }, "envelope": { "summary": "Envelope body", "value": { "operations": [ { "id": "op-1", "kind": "order", "data": { "cardLast4": "4242" } } ] } } } } } }, "responses": { "202": { "description": "Batch accepted. Poll the URL in the Location header until `status=completed`.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Polling URL: https://www.forter.com/batch/jobs/{job_id}" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before polling. Always 1 for the demo surface." }, "Idempotency-Key": { "schema": { "type": "string" }, "description": "Echoed from the request when present." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "job_id", "status", "poll_url", "retry_after_seconds" ], "properties": { "object": { "type": "string", "enum": [ "batch_job" ] }, "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed" ] }, "op_count": { "type": "integer" }, "poll_url": { "type": "string", "format": "uri" }, "retry_after_seconds": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "ops_accepted": { "type": "array", "items": { "type": "object" } }, "availability": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "405": { "description": "Method Not Allowed. Use POST to create a batch, GET to discover the surface.", "headers": { "Allow": { "schema": { "type": "string", "example": "GET, POST, OPTIONS" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "DemoBatchIndex", "summary": "DEMO - batch surface discovery envelope", "description": "Returns an inventory of the batch surface - supported operation kinds, request shapes (array vs envelope), polling URL template, and an example exchange. Mirrors the GET-first discovery convention from the workos.com/auth-md spec.", "tags": [ "demo", "batch", "discovery" ], "servers": [ { "url": "https://www.forter.com" } ], "security": [], "x-demo-only": true, "responses": { "200": { "description": "Batch surface inventory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoBatchIndex" } } } } } } }, "/batch/jobs/{job_id}": { "get": { "operationId": "DemoBatchPoll", "summary": "DEMO - poll a batch job", "description": "Returns the batch job's status and (when completed) per-operation results. Stateless - the job_id is a base64url-encoded JSON spec so the response is recomputable from the id alone.", "tags": [ "demo", "batch", "polling" ], "servers": [ { "url": "https://www.forter.com" } ], "security": [], "x-demo-only": true, "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" }, "description": "Base64url-encoded job spec returned by POST /batch." } ], "responses": { "200": { "description": "Job status. `status=pending` within the first second after creation; `status=completed` thereafter with `results[]` populated.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Present only while status=pending." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "job_id", "status" ], "properties": { "object": { "type": "string", "enum": [ "batch_job" ] }, "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed" ] }, "op_count": { "type": "integer" }, "elapsed_seconds": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object" } }, "ops_pending": { "type": "array", "items": { "type": "object" } }, "availability": { "type": "object" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v2/accounts/profile-access/{id}": { "post": { "operationId": "AccountAccessRequest", "summary": "Profile access", "description": "Send information on an attempt to access or edit a customer profile to receive a fraud decision. Used for account takeover at profile touchpoint, card testing, and digital key use cases. The response may also include recommendations for additional authentication (MFA) and a correlation ID to include with the authentication result.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountAccessRequestRequest" } } } }, "responses": { "200": { "description": "Example adaptiveAuthAccountsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adaptiveAuthAccountsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/accounts/authentication-result/{id}": { "post": { "operationId": "AccountAuthenticationAttemptResult", "summary": "Authentication result", "description": "Inform of authentication results after an attempted login or profile access request, using the provided correlation ID. While no decision is provided on this request, it improves the decision model for login and access.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountAuthenticationRequest" } } } }, "responses": { "200": { "description": "Example adaptiveAuthAccountsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adaptiveAuthAccountsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/accounts/item-listing/{id}": { "post": { "operationId": "AccountItemListing", "summary": "Seller item listing", "description": "Send information about a seller's new inventory in order to receive a fraud or abuse decision.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountItemListingRequest" } } } }, "responses": { "200": { "description": "Example adaptiveAuthAccountsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adaptiveAuthAccountsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/accounts/login/{id}": { "post": { "operationId": "AccountLogin", "summary": "Login", "description": "Send login attempt information to receive an account takeover decision. May also be used to determine whether to extend a user's idle session without prompting user for credentials. The response may also include recommendations for additional authentication (MFA) and a correlation ID to include with the authentication result.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountLoginRequest" } } } }, "responses": { "200": { "description": "Example adaptiveAuthAccountsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adaptiveAuthAccountsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/accounts/signup/{id}": { "post": { "operationId": "AccountSignup", "summary": "Signup", "description": "Send account registration information at signup to receive a fraud or abuse decision.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountSignupRequest" } } } }, "responses": { "200": { "description": "Example adaptiveAuthAccountsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adaptiveAuthAccountsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/accounts/status/{id}": { "post": { "operationId": "AccountStatusUpdate", "summary": "Account status", "description": "Inform of updates to the status of an account. While no decision is provided on this request, it improves the decision model.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountStatusUpdateRequest" } } } }, "responses": { "200": { "description": "Example adaptiveAuthAccountsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adaptiveAuthAccountsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/claims": { "post": { "operationId": "Claim", "summary": "Dispute", "description": "Inform of a dispute initiated by a customer. This endpoint should be used to report any disputes not already reported via webhook from the payment processor. While no decision is provided on this request, it is a required input that both improves the decision model and enables chargeback recovery.", "parameters": [ { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Disputes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/claimRequest" } } } }, "responses": { "200": { "description": "Example claimResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/claimResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/disputes/evidence/datapoints": { "post": { "operationId": "DisputeEvidenceDatapointsRequest", "summary": "Evidence", "description": "Submit structured textual datapoints for a dispute.", "parameters": [ { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Disputes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/disputeEvidenceDatapointsRequestRequest" } } } }, "responses": { "200": { "description": "Example disputeEvidenceDatapointsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/disputeEvidenceDatapointsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/disputes/evidence/file": { "post": { "operationId": "DisputeEvidenceFileRequest", "summary": "Evidence file upload", "description": "Upload a single file as dispute evidence.", "parameters": [ { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Disputes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/disputeEvidenceFileRequestRequest" } } } }, "responses": { "200": { "description": "Example disputeEvidenceFileResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/disputeEvidenceFileResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/merchants": { "post": { "operationId": "MerchantCreation", "summary": "Merchant", "description": "Create a new merchant within your Forter account. The response will include a Forter-assigned merchant subsite ID to be included in the API header on future requests.", "parameters": [ { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Merchants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantCreationRequest" } } } }, "responses": { "200": { "description": "Example merchantCreationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantCreationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/privacy/requests/{id}/data": { "get": { "operationId": "PrivacyDownloadRequest", "summary": "Download requested data", "description": "Retrieve the customer data from a previously submitted privacy request for data access.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Data Privacy" ], "responses": { "200": { "description": "Example privacyDownloadResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacyDownloadResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/privacy/requests": { "post": { "operationId": "PrivacyRequest", "summary": "Privacy request", "description": "In compliance with privacy laws, request access or deletion of customer data on behalf of the customer. \nThis endpoint should only be used if a data subject has specifically asked that their personal data be accessed or deleted, and their identity has been verified. \nThe response will include a unique ID assigned to this request.", "parameters": [ { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Data Privacy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacyRequestRequest" } } } }, "responses": { "200": { "description": "Example privacyResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/privacy/requests/{id}/status": { "get": { "operationId": "PrivacyStatusRequest", "summary": "Privacy request status", "description": "Check the status of a previously submitted privacy request.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Data Privacy" ], "responses": { "200": { "description": "Example privacyStatusResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacyStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/status/{id}": { "post": { "operationId": "Status", "summary": "Order status", "description": "Inform of updates to the status of an order, including payment authorization, fulfillment, shipping details, and compensation granted. For pre-authorization flows, use this endpoint to supply Forter with authorization results from your payment processor. While no decision is provided on this request, it is a required input that improves the decision model.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/statusRequest" } } } }, "responses": { "200": { "description": "Example statusResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/statusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/merchants/{id}/3ds-execution": { "post": { "operationId": "ThreeDsExecutionOnboarding", "summary": "3DS execution enrollment", "description": "Enroll a merchant in Forter's 3DS execution services on their future orders. \nThe response will include a request ID that can be used to check on the status.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Merchants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/threeDsExecutionOnboardingRequest" } } } }, "responses": { "200": { "description": "Example threeDsExecutionOnboardingRequestAccepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/threeDsExecutionOnboardingRequestAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/merchants/:id/3ds-execution/{requestId}/status": { "get": { "operationId": "ThreeDsExecutionOnboardingStatus", "summary": "3DS execution enrollment status", "description": "Check the status of a previous request to enroll a merchant in Forter's 3DS execution services.", "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Merchants" ], "responses": { "200": { "description": "Example threeDsExecutionOnboardingStatusResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/threeDsExecutionOnboardingStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/merchants/{id}/3ds-recommendation": { "post": { "operationId": "ThreeDsRecommendationOnboarding", "summary": "3DS recommendation enrollment", "description": "Enroll a merchant in Forter's 3DS recommendation services on their future orders.\nThe response will include a request ID that can be used to check on the status.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Merchants" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/threeDsRecommendationOnboardingRequest" } } } }, "responses": { "200": { "description": "Example threeDsRecommendationOnboardingRequestAccepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/threeDsRecommendationOnboardingRequestAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/merchants/:id/3ds-recommendation/{requestId}/status": { "get": { "operationId": "ThreeDsRecommendationOnboardingStatus", "summary": "3DS recommendation enrollment status", "description": "Check the status of a previous request to enroll a merchant in Forter's 3DS recommendation services.", "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Merchants" ], "responses": { "200": { "description": "Example threeDsRecommendationOnboardingStatusResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/threeDsRecommendationOnboardingStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/unified-compensation-request/{id}": { "post": { "operationId": "UnifiedCompensationRequest", "summary": "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.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Compensation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/unifiedCompensationRequestRequest" } } } }, "responses": { "200": { "description": "Example unifiedCompensationRequestResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/unifiedCompensationRequestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/orders/{id}": { "post": { "operationId": "V3Order", "summary": "Order v3", "description": "Send order information at checkout to receive a fraud or abuse decision. The response may also include recommendations based on your payment optimization features or abuse prevention policies, or a managed order token to include when requesting the 3DS result.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v3OrderRequest" } } } }, "responses": { "200": { "description": "Example v3OrderResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v3OrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/orders/{id}/results": { "post": { "operationId": "V3OrderResults", "summary": "3DS result", "description": "Check the 3DS results using the managed order token returned in Forter's response to the order request.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "3DS" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v3OrderResultsRequest" } } } }, "responses": { "200": { "description": "Example v3OrderResultsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v3OrderResultsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/order-update/{id}": { "post": { "operationId": "ValidationUpdate", "summary": "Order update", "description": "For orders placed over the phone, add the customer's connection information to receive a fraud or abuse decision.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "api-version", "in": "header", "description": "Specify the version of the API to target.", "required": true, "schema": { "type": "string", "example": "10.1" } }, { "name": "x-forter-siteid", "in": "header", "description": "Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f6" } }, { "name": "Authorization", "in": "header", "description": "Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.", "required": true, "schema": { "type": "string", "example": "Basic " } } ], "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/validationUpdateRequest" } } } }, "responses": { "200": { "description": "Example validationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/validationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/api/mpp/demo/charge": { "post": { "operationId": "createMppDemoCharge", "summary": "Create a demo MPP charge", "description": "DEMO-ONLY MPP (Machine Payment Protocol) charge. A bare request returns HTTP 402 with MPP payment requirements; a retry carrying a Payment header returns a canned demo charge. The payment rail is the Tempo testnet (Stripe MPP testnet) and no settlement is verified. Forter is a fraud-prevention platform and does not sell goods or take real payment. MPP discovery for this operation is the x-payment-info extension below.", "x-payment-info": { "intent": "charge", "method": "tempo", "amount": "0.01", "currency": "USD", "network": "tempo:testnet", "pay_to": "0xBCDc332BDba9aD0387A4892D84c7dDfF7E3BDFe4", "availability": "demo-only", "description": "Demo-only MPP charge on the Tempo testnet. Not a production payable operation." }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Demo charge created (demo-settled).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoPaymentObject" } } } }, "402": { "description": "Payment Required - retry with a Payment header. Body carries MPP payment requirements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredChallenge" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "servers": [ { "url": "https://www.forter.com", "description": "Public agent-readiness sandbox (demo data, no authentication required, rate-limited). NOT the production REST API at api.forter-secure.com, which is provisioned per tenant under a signed MSA." } ] } }, "/api/v1": { "get": { "operationId": "getX402Resource", "summary": "x402-paywalled demo API resource", "description": "DEMO-ONLY x402 (HTTP 402 Payment Required) resource mounted at the /api/v1 path that x402 scanners probe. A bare request returns HTTP 402 with an x402 `accepts` block pointing at a testnet wallet; a retry carrying an X-PAYMENT header returns a canned demo response. x402 discovery is inline in the 402 response, so this operation carries no x-payment-info. No settlement is verified. Forter does not sell goods or take real payment.", "responses": { "200": { "description": "Demo quote (returned after an X-PAYMENT retry).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoPaymentObject" } } } }, "402": { "description": "Payment Required - body carries the x402 accepts block.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredChallenge" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "description": "Typed error envelope for any undeclared 4xx / 5xx status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "servers": [ { "url": "https://www.forter.com", "description": "Public agent-readiness sandbox (demo data, no authentication required, rate-limited). NOT the production REST API at api.forter-secure.com, which is provisioned per tenant under a signed MSA." } ] } }, "/checkout_sessions": { "servers": [ { "url": "https://www.forter.com", "description": "Demo ACP surface served on www.forter.com - NOT the production REST API at api.forter-secure.com." } ], "post": { "operationId": "createCheckoutSession", "tags": [ "Agentic Commerce (ACP) - demo" ], "summary": "Create an ACP checkout session", "description": "Agentic Commerce Protocol checkout-session create. DEMO-ONLY: canned responses, no real Forter risk decisioning, no real payment.", "parameters": [ { "name": "API-Version", "in": "header", "required": true, "description": "ACP API version in YYYY-MM-DD form. If the version is unsupported the endpoint returns an ACP-shaped error carrying supported_versions so the agent can negotiate.", "schema": { "type": "string", "example": "2025-09-29" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated unique key that makes a write idempotent: a retry carrying the same key returns the original result instead of creating a duplicate. Required on ACP write operations.", "schema": { "type": "string", "example": "a1b2c3d4-0000-4000-8000-000000000000" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success - demo ACP object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "description": "Missing/unsupported header or malformed body - ACP-shaped error with supported_versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "405": { "description": "Method not allowed on this ACP endpoint - ACP-shaped error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "description": "Typed ACP error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } } }, "security": [], "servers": [ { "url": "https://www.forter.com", "description": "Public agent-readiness sandbox (demo data, no authentication required, rate-limited). NOT the production REST API at api.forter-secure.com, which is provisioned per tenant under a signed MSA." } ] } }, "/checkout_sessions/{id}": { "servers": [ { "url": "https://www.forter.com", "description": "Demo ACP surface served on www.forter.com - NOT the production REST API at api.forter-secure.com." } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Checkout session id." } ], "get": { "operationId": "getCheckoutSession", "tags": [ "Agentic Commerce (ACP) - demo" ], "summary": "Retrieve an ACP checkout session", "description": "Fetch a checkout session by id. DEMO-ONLY: canned responses, no real Forter risk decisioning, no real payment.", "responses": { "200": { "description": "Success - demo ACP object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "description": "Missing/unsupported header or malformed body - ACP-shaped error with supported_versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "404": { "description": "Checkout session not found - ACP-shaped error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "405": { "description": "Method not allowed on this ACP endpoint - ACP-shaped error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "description": "Typed ACP error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } } }, "security": [], "servers": [ { "url": "https://www.forter.com", "description": "Public agent-readiness sandbox (demo data, no authentication required, rate-limited). NOT the production REST API at api.forter-secure.com, which is provisioned per tenant under a signed MSA." } ] }, "post": { "operationId": "updateCheckoutSession", "tags": [ "Agentic Commerce (ACP) - demo" ], "summary": "Update an ACP checkout session", "description": "Update a checkout session by id. DEMO-ONLY: canned responses, no real Forter risk decisioning, no real payment.", "parameters": [ { "name": "API-Version", "in": "header", "required": true, "description": "ACP API version in YYYY-MM-DD form. If the version is unsupported the endpoint returns an ACP-shaped error carrying supported_versions so the agent can negotiate.", "schema": { "type": "string", "example": "2025-09-29" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated unique key that makes a write idempotent: a retry carrying the same key returns the original result instead of creating a duplicate. Required on ACP write operations.", "schema": { "type": "string", "example": "a1b2c3d4-0000-4000-8000-000000000000" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success - demo ACP object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "description": "Missing/unsupported header or malformed body - ACP-shaped error with supported_versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "404": { "description": "Checkout session not found - ACP-shaped error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "405": { "description": "Method not allowed on this ACP endpoint - ACP-shaped error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "description": "Typed ACP error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } } }, "security": [], "servers": [ { "url": "https://www.forter.com", "description": "Public agent-readiness sandbox (demo data, no authentication required, rate-limited). NOT the production REST API at api.forter-secure.com, which is provisioned per tenant under a signed MSA." } ] } }, "/checkout_sessions/{id}/complete": { "servers": [ { "url": "https://www.forter.com", "description": "Demo ACP surface served on www.forter.com - NOT the production REST API at api.forter-secure.com." } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Checkout session id." } ], "post": { "operationId": "completeCheckoutSession", "tags": [ "Agentic Commerce (ACP) - demo" ], "summary": "Complete an ACP checkout session", "description": "Mark a checkout session complete. DEMO-ONLY: canned responses, no real Forter risk decisioning, no real payment.", "parameters": [ { "name": "API-Version", "in": "header", "required": true, "description": "ACP API version in YYYY-MM-DD form. If the version is unsupported the endpoint returns an ACP-shaped error carrying supported_versions so the agent can negotiate.", "schema": { "type": "string", "example": "2025-09-29" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated unique key that makes a write idempotent: a retry carrying the same key returns the original result instead of creating a duplicate. Required on ACP write operations.", "schema": { "type": "string", "example": "a1b2c3d4-0000-4000-8000-000000000000" } } ], "responses": { "200": { "description": "Success - demo ACP object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "description": "Missing/unsupported header or malformed body - ACP-shaped error with supported_versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "404": { "description": "Checkout session not found - ACP-shaped error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "405": { "description": "Method not allowed on this ACP endpoint - ACP-shaped error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "description": "Typed ACP error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } } }, "security": [], "servers": [ { "url": "https://www.forter.com", "description": "Public agent-readiness sandbox (demo data, no authentication required, rate-limited). NOT the production REST API at api.forter-secure.com, which is provisioned per tenant under a signed MSA." } ] } }, "/checkout_sessions/{id}/cancel": { "servers": [ { "url": "https://www.forter.com", "description": "Demo ACP surface served on www.forter.com - NOT the production REST API at api.forter-secure.com." } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Checkout session id." } ], "post": { "operationId": "cancelCheckoutSession", "tags": [ "Agentic Commerce (ACP) - demo" ], "summary": "Cancel an ACP checkout session", "description": "Mark a checkout session cancel. DEMO-ONLY: canned responses, no real Forter risk decisioning, no real payment.", "parameters": [ { "name": "API-Version", "in": "header", "required": true, "description": "ACP API version in YYYY-MM-DD form. If the version is unsupported the endpoint returns an ACP-shaped error carrying supported_versions so the agent can negotiate.", "schema": { "type": "string", "example": "2025-09-29" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated unique key that makes a write idempotent: a retry carrying the same key returns the original result instead of creating a duplicate. Required on ACP write operations.", "schema": { "type": "string", "example": "a1b2c3d4-0000-4000-8000-000000000000" } } ], "responses": { "200": { "description": "Success - demo ACP object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "description": "Missing/unsupported header or malformed body - ACP-shaped error with supported_versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "404": { "description": "Checkout session not found - ACP-shaped error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "405": { "description": "Method not allowed on this ACP endpoint - ACP-shaped error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "description": "Typed ACP error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } } }, "security": [], "servers": [ { "url": "https://www.forter.com", "description": "Public agent-readiness sandbox (demo data, no authentication required, rate-limited). NOT the production REST API at api.forter-secure.com, which is provisioned per tenant under a signed MSA." } ] } }, "/agentic_commerce/delegate_payment": { "servers": [ { "url": "https://www.forter.com", "description": "Demo ACP surface served on www.forter.com - NOT the production REST API at api.forter-secure.com." } ], "post": { "operationId": "delegatePayment", "tags": [ "Agentic Commerce (ACP) - demo" ], "summary": "ACP Delegate Payment", "description": "Agentic Commerce Protocol Delegate Payment: takes payment_method, allowance (max amount, currency, expiry, merchant scope) and risk_signals, returns a scoped vault token. DEMO-ONLY: canned responses, no real Forter risk decisioning, no real payment. The vault token is synthetic and NOT PCI-scoped.", "parameters": [ { "name": "API-Version", "in": "header", "required": true, "description": "ACP API version in YYYY-MM-DD form. If the version is unsupported the endpoint returns an ACP-shaped error carrying supported_versions so the agent can negotiate.", "schema": { "type": "string", "example": "2025-09-29" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated unique key that makes a write idempotent: a retry carrying the same key returns the original result instead of creating a duplicate. Required on ACP write operations.", "schema": { "type": "string", "example": "a1b2c3d4-0000-4000-8000-000000000000" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success - demo ACP object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegatedPayment" } } } }, "400": { "description": "Missing/unsupported header or malformed body - ACP-shaped error with supported_versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "405": { "description": "Method not allowed on this ACP endpoint - ACP-shaped error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "default": { "description": "Typed ACP error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } } }, "security": [], "servers": [ { "url": "https://www.forter.com", "description": "Public agent-readiness sandbox (demo data, no authentication required, rate-limited). NOT the production REST API at api.forter-secure.com, which is provisioned per tenant under a signed MSA." } ] } } }, "x-service-info": { "service": { "name": "Forter API", "publisher": "Forter", "publisher_url": "https://www.forter.com", "publisher_wikidata": "Q20988642", "version": "10.2", "description": "Forter's canonical REST surface for fraud / abuse decisioning, account protection, dispute resolution, and PSP onboarding. Forter PROTECTS e-commerce - it is not itself an e-commerce site. No canonical operation is payable; the only payable operations are the explicitly demo-only MPP and x402 surfaces under /api/*/demo/.", "homepage": "https://www.forter.com", "contact": { "email": "sales@forter.com", "url": "https://www.forter.com/contact-us/" }, "category": "fraud-prevention", "license": { "name": "Forter License", "url": "https://www.forter.com/legal/api-terms" }, "api_base_url": "https://api.forter-secure.com" }, "payments": { "supported": false, "rationale": "Forter's canonical REST API at api.forter-secure.com has NO payable operations - production access requires a signed Forter MSA. The only payable operations in this spec are explicitly demo-only surfaces on www.forter.com (see x-payment-info on POST /api/mpp/demo/charge, and the x402 resource at /api/x402/demo/quote). They settle on testnet wallets and verify nothing; they exist to demonstrate the MPP and x402 protocol handshakes only.", "demo_surfaces": { "mpp": "https://www.forter.com/api/mpp/demo/charge", "x402": "https://www.forter.com/api/v1" }, "mcp_demo_paywall": "https://mcp.forter.com/mcp" }, "related": { "agent_skills_index": "https://www.forter.com/.well-known/agent-skills/index.json", "agent_card": "https://www.forter.com/.well-known/agent-card.json", "mcp_server_card": "https://www.forter.com/.well-known/mcp/server-card.json", "acp_discovery": "https://www.forter.com/.well-known/acp.json", "tacp_spec": "https://github.com/forter/trusted-agentic-commerce-protocol", "llms_txt": "https://www.forter.com/llms.txt" } }, "x-pagination": { "style": "cursor", "note": "Forter REST endpoints return single-resource responses (one decision per request) and do not paginate today. If list endpoints are introduced, they will follow the cursor-based convention below.", "parameters": { "cursor": "Opaque cursor from a prior response; omit to start at the first page.", "limit": "Maximum items per page. Default 25, maximum 200." }, "response_fields": { "next_cursor": "Opaque cursor for the next page, or null when no more results.", "has_more": "Boolean - whether more pages exist after the current one." } }, "x-batch": { "style": "envelope", "note": "Forter REST endpoints are single-event today (one decision per request) - no batch / bulk operations exist. If bulk endpoints are introduced, they will follow the envelope convention below: a request carrying an `items` array, a response carrying a `results` array with one entry per input item (each entry independently succeeded or failed).", "request_shape": { "items": "Array of single-item payloads (max items per call: 100)." }, "response_shape": { "results": "Array of per-item results in input order; each carries either `data` or `error`." } }, "x-error-recovery": { "error_schema": "#/components/schemas/Error", "acp_error_schema": "#/components/schemas/AcpError", "rate_limit": { "test_environment_rps": 10, "production": "Per-tenant, negotiated. Honor Retry-After on 429.", "headers": [ "RateLimit-Limit", "RateLimit-Remaining", "RateLimit-Reset", "Retry-After" ], "spec": "RFC 9598" }, "retry_guidance": { "400": { "retry": false, "note": "Malformed request - fix and resubmit; do not retry as-is." }, "401": { "retry": false, "note": "Bad credentials - re-issue API key + Site ID at portal.forter.com." }, "403": { "retry": false, "note": "Site ID / scope mismatch - verify the key matches the Site ID and environment." }, "404": { "retry": false, "note": "Unknown resource - verify path parameters." }, "409": { "retry": false, "note": "Idempotency conflict - a request with the same idempotency key already completed." }, "429": { "retry": true, "note": "Rate-limited. Honor Retry-After (seconds) before retrying. Use exponential backoff for repeated 429s." }, "500": { "retry": true, "note": "Server-side failure. Retry once with exponential backoff." }, "502": { "retry": true, "note": "Upstream gateway failure. Retry once with backoff." }, "503": { "retry": true, "note": "Service unavailable. Honor Retry-After." }, "504": { "retry": true, "note": "Gateway timeout. Retry once with backoff." } }, "client_recommendations": { "timeout_seconds": 2, "idempotency": "Use a stable {id} per logical order - Forter treats the path {id} as the idempotency key on REST. ACP endpoints additionally accept an Idempotency-Key header.", "backoff": "Exponential backoff (e.g. 250ms, 500ms, 1s, 2s) capped at the Retry-After value when present.", "on_persistent_failure": "Open an incident referencing the response `trackingId` / `request_id`." } } }