# Create Transaction **Whitelist Server IP Address**: \ Before initiating the transaction process, ensure that your server’s IP address is whitelisted in the Tutelar Panel. This step is crucial as it authorizes your server to communicate with the Tutelar Server. **Generate API Keys**: \ Generate the necessary API keys from the Tutelar Panel. These keys will be used to authenticate your API requests to the Tutelar Server, ensuring secure and verified communication. **Submit Transaction via Create Transaction API**: \ Utilize the Create Transaction API to submit a new transaction to the Tutelar Server. Ensure that all relevant transaction details are included in your request. The Tutelar Server will validate the submitted transaction data. **Receive Transaction Validation Response**: \ After validation, you will receive a response from the Tutelar Server containing the following critical pieces of information: * **Risk Score**: A numerical value indicating the risk level of the transaction. * **Risk Status**: A status indicator (e.g., high, medium, low) that reflects the assessed risk. * **Reference Number**: A unique identifier for the transaction, useful for tracking and reference purposes. * **Customer Information**: Details about the customer involved in the transaction. **Decision Making Based on Risk Assessment**: \ Use the risk score, risk status, reference number, and customer information to decide whether to allow or deny the customer's payment. This decision is vital for fraud prevention and ensuring the security of transactions. **Update Transaction Status**: \ Upon successful or failed payment, it is imperative to call the Transaction Status API to update the status of the previously completed transaction. This step ensures that the transaction records are accurate and up-to-date. By following these steps, you can effectively manage and assess transaction risks, making informed decisions to approve or deny payments, thereby maintaining a secure and reliable payment process ## POST /api/v1/fraud-detector/transaction/create > Create a transaction ```json {"openapi":"3.0.0","info":{"title":"Fraud Detector API","version":"1.0.0"},"servers":[{"url":"https://secctrl.tutelar.io"}],"paths":{"/api/v1/fraud-detector/transaction/create":{"post":{"summary":"Create a transaction","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId","customer","amount","merchant","paymentInstrument","currencyCode","paymentData"],"properties":{"deviceFingerPrint":{"type":"string","description":"Encoded device fingerprint information"},"orderId":{"type":"string","maxLength":40,"description":"Unique order ID to identify the transaction"},"customer_ip":{"type":"string","description":"The customer IP address involved in the transaction"},"customer":{"type":"object","description":"Contains detailed information about the customer involved in the transaction, including their name, email address, phone number, and the country code associated with their phone number.","required":["name","email","phone"],"properties":{"name":{"type":"string","maxLength":40},"email":{"type":"string"},"phone":{"type":"string"},"countryCode":{"type":"string"}}},"amount":{"type":"number","format":"float","description":"The total amount of the transaction"},"currencyCode":{"type":"string","description":"The currency code in which the transaction is conducted (e.g.,INR, USD, EUR)."},"merchant":{"type":"object","description":"Contains detailed information about the merchant processing the transaction, including a unique identifier, name, email address, website URL, business name, phone number and risk level.","required":["id","business_name"],"properties":{"id":{"type":"string","maxLength":20},"name":{"type":"string","maxLength":120},"email":{"type":"string","maxLength":40},"business_name":{"type":"string","maxLength":120},"website_url":{"type":"string","maxLength":200},"phone":{"type":"string"},"riskLevel":{"type":"string","enum":["low","medium","high"]}}},"riskCode":{"type":"string","description":"A code representing the risk level of the transaction"},"productType":{"type":"string","description":"The type of product being purchased"},"productDescription":{"type":"string","description":"A description of the product being purchased"},"billing":{"type":"object","description":"The billing details for the transaction","properties":{"address":{"type":"string"},"city":{"type":"string"},"name":{"type":"string"},"postalCode":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"}}},"shipping":{"type":"object","description":"The shipping details for the transaction","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"method":{"type":"string"},"name":{"type":"string"},"period":{"type":"string"},"phone":{"type":"string"},"postalCode":{"type":"string"},"state":{"type":"string"}}},"paymentChannel":{"type":"string","description":"Indicates the channel through which the payment is processed, such as a payment gateway (pg), quick_collect, or other supported payment channels.","enum":["pg","quick_collect","e_collect","banking","others"]},"paymentOption":{"type":"string","description":"Represents the specific payment option selected by the customer, such as payment link, EMI, or other supported payment options.","enum":["payment_link","pay_out","emi"]},"paymentInstrument":{"type":"string","description":"The type of payment instrument used (card, netbanking, upi etc)","enum":["card","upi","wallet","ft","nb"]},"paymentData":{"type":"object","description":"Contains specific details related to the payment method used for the transaction, including the name on the payment instrument, a secure token hash for the payment data, and the Bank Identification Number (BIN) of the payment instrument.","required":["tokenHash"],"properties":{"modeType":{"type":"string","enum":["credit","debit","prepaid","collect_request","redirect","qr","intent","neft","rtgs","imps","ift","nbfc_emi","paytm","phone_pe","upi"]},"bin":{"type":"string"},"cardBank":{"type":"string"},"cardType":{"type":"string"},"cardCountry":{"type":"string"},"cardBrand":{"type":"string"},"cardSubBrand":{"type":"string"},"name":{"type":"string"},"tokenHash":{"type":"string"},"ifsc":{"type":"string"},"type":{"type":"string"}}},"mcc":{"type":"object","description":"The Merchant Category Code, which classifies the type of business.","properties":{"id":{"type":"string"},"code":{"type":"string"},"description":{"type":"string"}}},"industry":{"type":"object","description":"The industry in which the merchant operates.","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"}}},"device":{"type":"object","description":"Used when the encoded deviceFingerPrint field is absent. Use Case:- Server-to-server API calls","properties":{"deviceId":{"type":"string"},"deviceType":{"type":"string"},"os":{"type":"string"},"sessionId":{"type":"string"},"browserName":{"type":"string"},"browserHash":{"type":"string"},"cookieHash":{"type":"string"}}},"udf1":{"type":"object","description":"UDF (User Defined Fields) allow for custom data storage: udf1-udf8 are customizable fields. **name**: Label of the field. **value**: Content of the field, tailored to user needs.\n","properties":{"value":{"type":"string"},"name":{"type":"string"}}},"udf2":{"type":"object","properties":{"value":{"type":"string"},"name":{"type":"string"}}},"udf3":{"type":"object","properties":{"value":{"type":"string"},"name":{"type":"string"}}},"udf4":{"type":"object","properties":{"value":{"type":"string"},"name":{"type":"string"}}},"udf5":{"type":"object","properties":{"value":{"type":"string"},"name":{"type":"string"}}},"udf6":{"type":"object","properties":{"value":{"type":"string"},"name":{"type":"string"}}},"udf7":{"type":"object","properties":{"value":{"type":"string"},"name":{"type":"string"}}},"udf8":{"type":"object","properties":{"value":{"type":"string"},"name":{"type":"string"}}},"udf9":{"type":"object","properties":{"value":{"type":"string"},"name":{"type":"string"}}},"udf10":{"type":"object","properties":{"value":{"type":"string"},"name":{"type":"string"}}}}}}}},"responses":{"106":{"description":"Duplicate order id received","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"code":{"type":"integer"}}}}}},"200":{"description":"Successful transaction creation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"orderId":{"type":"string"},"referenceNo":{"type":"string"},"requestedDateTime":{"type":"string"},"responseDateTime":{"type":"string"},"processedTime":{"type":"integer"},"merchant_details":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"business_name":{"type":"string"},"website_url":{"type":"string"},"phone":{"type":"string"},"riskLevel":{"type":"string"},"reseller":{"type":"object","properties":{"id":{"type":"string"},"reseller_id":{"type":"string"},"name":{"type":"string"},"business_name":{"type":"string"},"email":{"type":"string"}}}}},"customer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"product_description":{"type":"string"},"product_type":{"type":"string"}}},"transaction_details":{"type":"object","properties":{"amount":{"type":"number"},"status":{"type":"string"}}},"risk_details":{"type":"object","properties":{"status":{"type":"string"},"score":{"type":"integer"},"type":{"type":"string"},"engine_code":{"type":"string"},"engine_name":{"type":"string"}}},"rules_triggered":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string"},"group_code":{"type":"string"},"score":{"type":"integer"},"description":{"type":"string"},"group_rules":{"type":"array","items":{"type":"object","properties":{"rule_code":{"type":"string"},"rule_inputs":{"type":"string"}}}}}}},"payment_instrument":{"type":"object","properties":{"payment_instrument_type":{"type":"string"},"card_holder_name":{"type":"string"},"card_using_bank":{"type":"string"},"card_type":{"type":"string"},"card_country":{"type":"string"},"card_bin_number":{"type":"string"},"card_brand":{"type":"string"},"card_sub_brand":{"type":"string"},"card_country_code":{"type":"string"},"dr_presence":{"type":"boolean"}}},"ip_address":{"type":"object","properties":{"address":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"city":{"type":"string"},"country_code":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"dr_presence":{"type":"boolean"}}},"phone_number":{"type":"object","properties":{"number":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"dr_presence":{"type":"boolean"}}},"email_address":{"type":"object","properties":{"address":{"type":"string"},"free":{"type":"string"},"disposable":{"type":"string"},"domain":{"type":"string"},"dr_presence":{"type":"boolean"}}},"device_details":{"type":"object","properties":{"id":{"type":"string"},"device_type":{"type":"string"},"device_accuracy":{"type":"string"},"device_profile_score":{"type":"string"},"operating_system":{"type":"string"},"source_ip":{"type":"string"},"source_ip_country":{"type":"string"},"flash_data":{"type":"boolean"},"packet_vpn":{"type":"string"},"packet_tor":{"type":"string"},"session_id":{"type":"string"},"pdf_viewer_enabled":{"type":"boolean"},"battery_info":{"type":"string"},"timestamp":{"type":"integer"},"timezone":{"type":"string"},"browser_name":{"type":"string"},"browser_version":{"type":"string"},"private_window":{"type":"boolean"},"browser_hash":{"type":"string"},"browser_vendor":{"type":"string"},"user_agent":{"type":"string"},"cookie_enabled":{"type":"boolean"},"cookie_wiped_out":{"type":"boolean"},"cookie_hash":{"type":"string"},"flash_enabled":{"type":"boolean"},"java_enabled":{"type":"boolean"},"ad_blocked":{"type":"boolean"},"color_depth":{"type":"integer"},"canvas_hash":{"type":"string"},"supports_web_rtc":{"type":"boolean"},"region_language":{"type":"string"},"screen_type":{"type":"string"},"screen_height":{"type":"integer"},"screen_width":{"type":"integer"},"font_count":{"type":"integer"},"font_list":{"type":"array","items":{"type":"string"}},"font_hash":{"type":"string"},"webgl_hash":{"type":"string"},"plugin_list":{"type":"array","items":{"type":"string"}},"plugin_count":{"type":"integer"},"webrtc_activated":{"type":"boolean"},"dr_presence":{"type":"boolean"}}}}}}}}}},"401":{"description":"Invalid authentication credentials","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"Merchant status issues","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"code":{"type":"integer"},"message":{"type":"string"}}}}}},"500":{"description":"Product is unsubscribed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"code":{"type":"integer"},"message":{"type":"string"}}}}}}}}}}} ``` {% hint style="danger" %} The Customer object is optional. If values are provided, they will be validated {% endhint %} {% hint style="info" %} Info: The maximum length of request parameters ```yaml orderId: 40 characters, customer.name: 120 characters, merchant.id: 20 characters, merchant.name: 120 characters, merchant.email: 40 characters, merchant.business_name: 120 characters, merchant.website_url: 200 characters, ``` {% endhint %} {% hint style="info" %} Info:\ **Request Parameter Validation Rules** ``` { "merchant": { "id": "Alphanumeric characters (A-Z, a-z, 0-9) and special characters (@ $ _ -) with spaces allowed.", "email": "Valid email format (e.g., example@domain.com). The domain extension must be 2 or 3 characters long (e.g: .com, .in, .org, .net).", "name": "Alphanumeric characters, spaces, and special characters (. - & ' + ! @) allowed.", "business_name": "Alphanumeric characters, spaces, and special characters (. - & ' + ! @) allowed.", "website_url": "Valid URL format supporting http, https, and www (e.g., https://example.com or www.example.com).", "phone": "Only numeric values allowed (0-9), no spaces or special characters." } } ``` {% endhint %} {% hint style="info" %} MCC API ``` https://secctrl.tutelar.io/api/v1/tutler/properties/open/mcc ``` Industry API ``` https://secctrl.tutelar.io/api/v1/tutler/properties/open/industry-type-list ``` {% endhint %} ### **Pre Auth and Post Auth** The Transaction Create API has been enhanced to support both pre-authorization (pre-auth) and post-authorization (post-auth) transaction flows.\ \ **API Description** The Create API handles the creation of transactions in the pre-auth flow. For the post-auth flow, it also updates transaction details if `transactionId` and `status` are present in the request payload (`postData`). **API Endpoint**: #### Process Flow **Pre-Auth Flow**: The API performs the standard transaction creation logic. #### Post-Auth Flow: * The API performs the standard transaction creation logic. * Additionally, 1. It updates the transaction status, velocity, and risk results. 2. It calculates SLA durations and schedules jobs to update SLA transactions if required. #### Post Data The request payload should be a JSON object containing the necessary transaction details.\ For post-auth flows, it should include `transactionId`, `status`, and optionally `statusReason`. If the transaction is made in the post-auth flow, add the following data to the create API post data: ```json { "status": "success", "transactionId": "trans_6789", "statusReason": "Payment Completed Successfully", } ``` #### Use Cases * Valid Transaction ID and Status: - [ ] **Scenario**: Providing both a valid transactionId and status. - [ ] **Expected Result:** The API creates the transaction & updates the transaction details. * Invalid Status With Transaction ID: - [ ] **Scenario:** Providing an invalid status. - [ ] **Expected Result:** The API processes the request as a standard pre-auth transaction creation, ignoring the status and transactionId. * Status Without Transaction ID: - [ ] **Scenario:** Providing a status without a transactionId. - [ ] **Expected Result:** The API processes the request as a standard pre-auth transaction creation, ignoring the status. * Existing Transaction ID: - [ ] **Scenario:** Providing an existing transactionId. - [ ] **Expected Result:** The API creates the transaction & doesn’t update the transaction details. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tutelar.io/tutelar-api-document/fraud-detection-monitoring/create-transaction.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.