Create Transaction

To initiate a new transaction with the Tutelar Server, the following steps must be adhered to for proper setup and execution:

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

Create a transaction

post
Body
deviceFingerPrintstringOptional

Encoded device fingerprint information

Example: ewogICJpcEFkZHJlc3MiOiAiNDkuMjQ5LjYyLjE5OCIsCiAgImJyb3dz
orderIdstring · max: 40Required

Unique order ID to identify the transaction

Example: ORD_10726
customer_ipstringOptional

The customer IP address involved in the transaction

Example: 49.207.180.255
amountnumber · floatRequired

The total amount of the transaction

Example: 299.99
currencyCodestringRequired

The currency code in which the transaction is conducted (e.g.,INR, USD, EUR).

Example: INR
riskCodestringOptional

A code representing the risk level of the transaction

Example: CL00001
productTypestringOptional

The type of product being purchased

Example: Ecommerce
productDescriptionstringOptional

A description of the product being purchased

Example: Table
paymentInstrumentstringRequired

The type of payment instrument used (e.g., credit card, debit card)

Example: card
Responses
106
Duplicate order id received
application/json
post
POST /api/v1/fraud-detector/transaction/create HTTP/1.1
Host: secctrl.tutelar.io
Content-Type: application/json
Accept: */*
Content-Length: 1609

{
  "deviceFingerPrint": "ewogICJpcEFkZHJlc3MiOiAiNDkuMjQ5LjYyLjE5OCIsCiAgImJyb3dz",
  "orderId": "ORD_10726",
  "customer_ip": "49.207.180.255",
  "customer": {
    "name": "",
    "email": "",
    "phone": "",
    "countryCode": "+91"
  },
  "amount": 299.99,
  "currencyCode": "INR",
  "merchant": {
    "id": "TUTxxxxx19",
    "name": "Merchant",
    "email": "[email protected]",
    "business_name": "Merchant Business Name",
    "website_url": "http://merchantbusiness.com",
    "phone": "9876xxxx10"
  },
  "riskCode": "CL00001",
  "productType": "Ecommerce",
  "productDescription": "Table",
  "billing": {
    "address": "B16 and B17 2nd floor SIDCO Industrial Estate Guindy",
    "city": "Chennai",
    "name": "Ippopay",
    "postalCode": "600032",
    "state": "Tamilnadu",
    "country": "India"
  },
  "shipping": {
    "address": "B16 and B17 2nd floor SIDCO Industrial Estate Guindy",
    "city": "Chennai",
    "country": "India",
    "email": "[email protected]",
    "method": "1",
    "name": "Ippopay",
    "period": "1",
    "phone": "9876xxxx10",
    "postalCode": "600032",
    "state": "Tamilnadu"
  },
  "paymentInstrument": "card",
  "paymentData": {
    "bin": "400000xxxxxxxx00",
    "name": "Ippopay",
    "tokenHash": "aa0a953b06984294acda7d933a572df4",
    "ifsc": "IFSC0009591",
    "type": "imps"
  },
  "mcc": {
    "id": "2zYroPJ1074",
    "code": "9311",
    "description": "Tax Payments"
  },
  "industry": {
    "id": "qiGunPvJ1",
    "name": "Financial Services",
    "code": "IND00024"
  },
  "udf1": {
    "value": "text",
    "name": "text"
  },
  "udf2": {
    "value": "text",
    "name": "text"
  },
  "udf3": {
    "value": "text",
    "name": "text"
  },
  "udf4": {
    "value": "text",
    "name": "text"
  },
  "udf5": {
    "value": "text",
    "name": "text"
  },
  "udf6": {
    "value": "text",
    "name": "text"
  },
  "udf7": {
    "value": "text",
    "name": "text"
  },
  "udf8": {
    "value": "text",
    "name": "text"
  },
  "udf9": {
    "value": "text",
    "name": "text"
  },
  "udf10": {
    "value": "text",
    "name": "text"
  }
}
{
  "success": false,
  "message": "Duplicate order id received",
  "code": 106
}

The Customer object is optional. If values are provided, they will be validated

Info:

The maximum length of request parameters 

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,

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., [email protected]). 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."
  }
}

MCC API

https://secctrl.tutelar.io/api/v1/tutler/properties/open/mcc-documents/get/all?

Industry API

https://secctrl.tutelar.io/api/v1/tutler/properties/open/industry-type-list?

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: https://stgsecctrl.tutelar.io/api/v1/fraud-detector-onstream/transaction/create

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, if transactionId and status are present in the request payload:

    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 and status:

If the transaction is made in the post-auth flow, add the following data to the create API post data:

{
 "status": "success"   
 "transactionId": "trans_6789"
}

Use Cases

  • Valid Transaction ID and Status:

  • Invalid Status With Transaction ID:

  • Status Without Transaction ID:

  • Existing Transaction ID:

PreviousIntroductionNextNotify Transaction

Last updated