アカウントの状態

POST

https://api.forter-secure.com/v2/accounts/status/{id}

Inform of updates to the status of an account. While no decision is provided on this request, it improves the decision model.

Path Parameters

idstringrequired

Header Parameters

api-versionstringrequired
Example
10.1
Description
Specify the version of the API to target.
Default
10.1
x-forter-siteidstringrequired
Example
a1b2c3d4e5f6
Description
Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.
Default
8b47c6d423ba

Body Parameters

bodyaccountStatusUpdateRequestrequired
Description
Inform of updates to the status of an account. While no decision is provided on this request, it improves the decision model.
- accountIdstringrequired
  Description
  Customer's account UID in merchant's site. Should not be the user email.
  Default
  e520-ba9a-367-60b
- additionalInformationobject
  - GeneralPayloadMap
- connectionInformationobject
  - ConnectionInformation
    - checkoutToolsSessionIdstring
      Description
      CheckoutToolsSessionId received from the SDK
      Default
      HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd
    - customerIPstringrequired
      Description
      Customer IP address in IPv4 or IPv6 format. If missing should be populated with 127.0.0.1
      Default
      10.0.0.127
    - forterMobileUIDstring
      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)
      Default
      6429751237891
    - forterTokenCookiestring
      Description
      Forter token cookie from request headers
      Default
      249453te8tbf9355186fet0ken547b95_2786972955236__UDE52-n5_8dg
    - merchantDeviceIdentifierstring
      Description
      A unique device identifier generated by merchant
      Default
      HGJ7512345H3
    - merchantProvidedSessionIdstring
      Description
      An identifier of the merchant session
      Default
      HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd
    - userAgentstringrequired
      Description
      Customer's User agent
      Default
      Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36
- eventTimenumberrequired
  Description
  The time that the trigger event occurred in MILLISECONDS since unix epoch (Jan 1, 1970)
  Default
  1415287568000
- merchantAccountStatusstring
  Description
  Account status as defined in the merchant's system
  Default
  open
- statusstring<ACTIVE | SUSPENDED | CLOSED | GUEST | PENDING>required
  Description
  Account status
  Default
  ACTIVE
- statusChangeBystring<MERCHANT_ADMIN | END_USER | FORTER>
  Description
  The entity responsible for triggering the status change
  Default
  MERCHANT_ADMIN
- statusChangeReasonstring
  Description
  The reason for the account status change. Required in case the update includes an account status change.
  Default
  user violation of coupon abuse policy
- typestring<GUEST | PRIVATE | BUSINESS | VIP | MERCHANT_OPERATED | TRIAL | MERCHANT_EMPLOYEE | PREMIUM_PAID | SMALL_BUSINESS | AGENT | BUSINESS_PRIVATE | BUSINESS_PREMIUM_PAID>
  Description
  Account type (a business account, a private account, a merchant-operated account)
  Default
  BUSINESS

Responses

200Example adaptiveAuthAccountsResponse

adaptiveAuthAccountsResponse
Description
Response structure for adaptive auth account requests
- accountIdstringrequired
  Description
  When applicable, the customer's account UID in merchant's site
  Default
  e520-ba9a-367-60b
- correlationIdstringrequired
  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
  Default
  HGJ7512345H3DE
- decisionReasonstringrequired
  Description
  The main reason behind the Forter decision
  Default
- forterDecisionstring<APPROVE | DECLINE | VERIFICATION_REQUIRED | NOT_REVIEWED>required
  Description
  The latest Forter decision regarding the attempted action
  Default
  APPROVE
- merchantPolicyIdstringrequired
  Description
  UID of the custom policy created in Forter's Policies tool that resulted in this decision
  Default
  0ee8ba28a8654c659addbae9253b707c
- recommendationstringrequired
  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.)
  Default
- verificationMethodVerificationMethodrequired
  Description
  The specific verification method to be used when verification is required according to "recommendation" field
  - correlationIdstringrequired
    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.
    Default
    HGJ7512345H3DE
  - statusstringrequired
    Description
    Verification status
    Default
    FRICTIONLESS
  - statusCodestringrequired
    Description
    Verification status code
    Default
    100
  - statusMessagestringrequired
    Description
    Text describes the verification status
    Default
    Verification code sent
  - typestring<OTP_SMS | OTP_EMAIL | THREE_DS>required
    Description
    Verification method type
    Default
    THREE_DS
  - verificationIdstringrequired
    Description
    A unique identifier assigned to that specific verification
    Default
    345H3DEHGJ7512
  - verificationSpecificDataVerificationDatarequired
    Description
    Data specific to the verification type performed
    - ThreeDSobject
      - ThreeDSecureResponse
        ACSUrlstringrequired
        Description
        In case of challange, this url is needed to be passed to client side and trigger ftr__.init3DS function
        Default
        https:/ /acs-us-east-1.nd.nds-sandbox-issuer.com/api/v1/acs/browser_sdk_challenges
        ECIValuestringrequired
        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
        Default
        02
        acsChallengeMandatedstringrequired
        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)
        Default
        Y
        acsReferenceNumberstringrequired
        Description
        Unique identifier assigned by the EMVCo Secretariat = required for mobile app implementation
        Default
        ftr-internal-acs-approval
        acsSignedContentstringrequired
        Description
        ACS Signed Content required for mobile app implementation
        Default
        acsTransIDstringrequired
        Description
        Universally Unique transaction identifier assigned by the ACS to identify a single transaction - required for mobile app implementation
        Default
        6fd30e89-8171-4cc3-b86e-3d59582af2f6
        authenticationTypestringrequired
        Description
        Optional authentication type (01 - Static, 02 - Dynamic, 03 - OOB, 04 - Decoupled)
        Default
        01
        authenticationValuestringrequired
        Description
        3DS Authentication value (AV) should be sent to the payment gateway in the authorization call
        Default
        tSvPDt3PINNaoL+ERXdg0jVrmWc=
        bankLiabilityShiftbooleanrequired
        Description
        Indicates whether transaction is supposed to get liability shift from issuer
        Default
        true
        cardEnrolledstringrequired
        Description
        3DS transaction card Enrolled status - should be sent to the payment gateway in the authorization call in some payment gateways
        Default
        Y
        cavvAlgorithmstringrequired
        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
        Default
        3
        challengeCancelstringrequired
        Description
        Indicator informing the ACS and the DS that the authentication has been canceled. Possible values: 01-99
        Default
        01
        challengeStatusstringrequired
        Description
        Ares transStatus value (Possible values: U, N, Y, A, C, D, R, I)
        Default
        Y
        dsTransIDstringrequired
        Description
        Universally unique transaction identifier assigned by the DS to identify a single transaction
        Default
        38bbf46f-c023-4f4c-ae2c-35fb301632a5
        encodedChallengeRequeststringrequired
        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
        Default
        eyJhY3NUcmFuc0lEIjoiMTEyY2RiNWItMGFlYy00MTY5LThjMWYtYWMyN2JlNjAxMjhhIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0IiwibWVzc2FnZVZlcnNpb24iOiIyLjEuMCIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiZWRhM2MwMzYtZWMyYS00NmZkLTlmYWItNzBlZTgyYjJjNzQ5In0=
        exemptionstring<LOW_VALUE | TRANSACTION_RISK_ANALYSIS | SECURE_CORPORATE | TRUSTED_BENEFICIARY>
        Description
        Exemption that should be used during the authorization process
        Default
        TRANSACTION_RISK_ANALYSIS
        interactionCounterstringrequired
        Description
        Indicates the number of authentication cycles attempted by the Cardholder
        Default
        01
        isFallbackbooleanrequired
        Description
        Indication of whether a 3DS1 challenge was performed as a fallback to 3DS2 error
        Default
        false
        messageCategorystringrequired
        Description
        Identifies the category of the message for a specific use case (01 - PA, 02 - NPA)
        Default
        01
        outOfScopeForPSD2string<ANONYMOUS_PREPAID_CARD | MERCHANT_INITIATED_TRANSACTIONS | ONE_LEG_OUT_EEA | MAIL_ORDER_TELEPHONE_ORDER>
        Description
        This field indicate if transaction is out of scope for PSD2 and exclusion should be requested
        Default
        ANONYMOUS_PREPAID_CARD
        threeDSServerTransIDstringrequired
        Description
        Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction (in 3DS1 equal to XID)
        Default
        26d648a9-da8a-4f8b-a76d-094801d2fd45
        threeDSecureModestringrequired
        Description
        Indicate if the transaction is Frictionless or SCA. Being used by some payment gateways. Possible values: sca, frictionless
        Default
        sca
        threeDSecurePreferencestringrequired
        Description
        The challenge indicator used. Being used by some payment gateways. Possible values: nopref, frictionless, sca, scamandate
        Default
        nopref
        threeDSecureResultstringrequired
        Description
        This field is relevant for 3DS1 and being used by some payment gateways
        Default
        590040
        transStatusstringrequired
        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)
        Default
        Y
        transStatusReasonstringrequired
        Description
        Provides information on why the Transaction Status field has the specified value. Possible values: 01-99
        Default
        01
        verifyStatusstringrequired
        Description
        Cres transStatus value (Possible values: U, N, Y, A, C, D, R, I, null)
        Default
        Y
        versionstringrequired
        Description
        Version. Possible values: 1.0.2, 2.1.0, 2.2.0
        Default
        2.1.0
    - emailobject
      - Email
        emailstringrequired
        Description
        Email address
        Default
        [email protected]
        emailVerificationobject
        Verification
        sentbooleanrequired
        Description
        True if verification email was sent to email address or verification SMS was sent to phone number
        Default
        true
        timeSentnumber
        Description
        Date verification email or SMS was sent in seconds since unix epoch (UTC, Jan 1, 1970)
        Default
        1389567341
        verifiedbooleanrequired
        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)
        Default
        false
    - phoneobject
      - Phone
        phonestringrequired
        Description
        Phone number including all country and local access codes
        Default
        15557654321
        smsVerifiedobject
        Verification
        sentbooleanrequired
        Description
        True if verification email was sent to email address or verification SMS was sent to phone number
        Default
        true
        timeSentnumber
        Description
        Date verification email or SMS was sent in seconds since unix epoch (UTC, Jan 1, 1970)
        Default
        1389567341
        verifiedbooleanrequired
        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)
        Default
        false

400Bad Request (Often missing a required parameter)

401Unauthorized (No valid API key provided)

404Not Found (The requested item doesn't exist)

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

curl

curl --request POST \
     --url https://api.forter-secure.com/v2/accounts/status/{id} \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'api-version: 10.1' \
     --header 'x-forter-siteid: 8b47c6d423ba' \
     --header 'authorization: Basic <base64-encoded-api-key:>' \
     --data '{
     "accountId": "e520-ba9a-367-60b",
     "additionalInformation": {},
     "connectionInformation": {
     "checkoutToolsSessionId": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd",
     "customerIP": "10.0.0.127",
     "forterMobileUID": "6429751237891",
     "forterTokenCookie": "249453te8tbf9355186fet0ken547b95_2786972955236__UDE52-n5_8dg",
     "merchantDeviceIdentifier": "HGJ7512345H3",
     "merchantProvidedSessionId": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd",
     "userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36"
     },
     "eventTime": 1415287568000,
     "merchantAccountStatus": "open",
     "status": "ACTIVE",
     "statusChangeBy": "MERCHANT_ADMIN",
     "statusChangeReason": "user violation of coupon abuse policy",
     "type": "BUSINESS"
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");
myHeaders.append("api-version", "10.1");
myHeaders.append("x-forter-siteid", "8b47c6d423ba");
myHeaders.append("authorization", "Basic <base64-encoded-api-key:>");

var raw = JSON.stringify({
   "accountId": "e520-ba9a-367-60b",
   "additionalInformation": {},
   "connectionInformation": {
      "checkoutToolsSessionId": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd",
      "customerIP": "10.0.0.127",
      "forterMobileUID": "6429751237891",
      "forterTokenCookie": "249453te8tbf9355186fet0ken547b95_2786972955236__UDE52-n5_8dg",
      "merchantDeviceIdentifier": "HGJ7512345H3",
      "merchantProvidedSessionId": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd",
      "userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36"
   },
   "eventTime": 1415287568000,
   "merchantAccountStatus": "open",
   "status": "ACTIVE",
   "statusChangeBy": "MERCHANT_ADMIN",
   "statusChangeReason": "user violation of coupon abuse policy",
   "type": "BUSINESS"
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.forter-secure.com/v2/accounts/status/{id}", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.forter-secure.com/v2/accounts/status/{id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request["api-version"] = "10.1"
request["x-forter-siteid"] = "8b47c6d423ba"
request["authorization"] = "Basic <base64-encoded-api-key:>"
request.body = JSON.dump({
   "accountId": "e520-ba9a-367-60b",
   "additionalInformation": {},
   "connectionInformation": {
      "checkoutToolsSessionId": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd",
      "customerIP": "10.0.0.127",
      "forterMobileUID": "6429751237891",
      "forterTokenCookie": "249453te8tbf9355186fet0ken547b95_2786972955236__UDE52-n5_8dg",
      "merchantDeviceIdentifier": "HGJ7512345H3",
      "merchantProvidedSessionId": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd",
      "userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36"
   },
   "eventTime": 1415287568000,
   "merchantAccountStatus": "open",
   "status": "ACTIVE",
   "statusChangeBy": "MERCHANT_ADMIN",
   "statusChangeReason": "user violation of coupon abuse policy",
   "type": "BUSINESS"
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.forter-secure.com/v2/accounts/status/{id}"

payload = json.dumps({
   "accountId": "e520-ba9a-367-60b",
   "additionalInformation": {},
   "connectionInformation": {
      "checkoutToolsSessionId": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd",
      "customerIP": "10.0.0.127",
      "forterMobileUID": "6429751237891",
      "forterTokenCookie": "249453te8tbf9355186fet0ken547b95_2786972955236__UDE52-n5_8dg",
      "merchantDeviceIdentifier": "HGJ7512345H3",
      "merchantProvidedSessionId": "HTGDVC232fdFDFdfkdjk87382938mcndjc2f4gbbGd",
      "userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36"
   },
   "eventTime": 1415287568000,
   "merchantAccountStatus": "open",
   "status": "ACTIVE",
   "statusChangeBy": "MERCHANT_ADMIN",
   "statusChangeReason": "user violation of coupon abuse policy",
   "type": "BUSINESS"
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json',
   'api-version': '10.1',
   'x-forter-siteid': '8b47c6d423ba',
   'authorization': 'Basic <base64-encoded-api-key:>'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// Example adaptiveAuthAccountsResponse
{
  "accountId": "",
  "correlationId": "",
  "decisionReason": "",
  "forterDecision": "",
  "merchantPolicyId": "",
  "recommendation": "",
  "verificationMethod": {
    "correlationId": "",
    "status": "",
    "statusCode": "",
    "statusMessage": "",
    "type": "",
    "verificationId": "",
    "verificationSpecificData": {
      "ThreeDS": {},
      "email": {},
      "phone": {}
    }
  }
}

400

// Bad Request (Often missing a required parameter)

401

// Unauthorized (No valid API key provided)

404

// Not Found (The requested item doesn't exist)

500

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

アカウントのステータスに関する更新を通知します。このリクエストに対する決定は提供されていませんが、決定モデルが改善されます。