NAV
3433054776 API

Introduction

This integration guide will help you to start using Aegis as soon as possible. You will need to manage your application via Aegis portal to ensure that you have correct access to send data to Aegis.

Getting Started

Accessing Aegis

Sandbox: (331) 236-1922
Production: /app.aegisdetection.com

Setting Up Aegis Portal

Create Users with Specific Role

After signing in to our console, you need to create some user accounts who will be able to access your console. There are 4 types of user roles in Aegis see details temperedly. But to get started, you only need these user roles to be assigned:
a. Fraud Analyst.
b. Rule manager.

Create Sample Rule(s)

Login with your Fraud Analyst account and go to Rules page from your sidebar navigation menu. Then go to the create rule button on the top-right of the page.

Here are some basic rule templates that you can try. You can replicate the content from the attached screenshot.

After the rules are submitted to Rule Manager, ask your Rule Manager to approve the rules. Here’s how to do it:

approve rule

Now you already have rules in your application!

Sending Data to AEGIS

Transaction Evaluation

Now we can try to send some test transactions to your sandbox account. We will try to send transaction which will not hit any rule and transactions which will hit your rules.

Send your first transaction

This is a sample request to evaluate transaction on Aegis:

Check API Reference to see request specification details.

curl -X "POST" "/api.sandbox.aegisdetection.com/v2/evaluate" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "apiKey: YOUR_API_KEY" \
    -d $'{
  "transaction_id": "11891bf6-f951-45e8-b1db-ea1c47fe26dc",
    "order_datetime": "2016-01-01 12:00:00",
    "bruce_sector": "0200",
    "payment_type": "credit_card",
    "merchant_id": "A000000000000000000001",
  "order_ctl_id": "1404",
  "amount": 250000,
  "card_number": "be6429f1-f845-43d6-bddc-93a1e74e40f5",
  "card_bin": "411111",
  "card_last_four": "0001",
  "d3_eci": "02",
  "bank": "bni",
  "type": "",
  "custom_field_1": "",
  "custom_field_2": "",
  "custom_field_3": "",
  "fs_param": {
    "customer_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@mail.com",
      "address1": "cikarang , 17550 , ID",
      "address2": "cikarang , 17550 , ID",
      "city": "cikarang",
      "postal_code": "74169",
      "home_phone": "08113597913",
      "country_code": "ID"
    },
    "shipping_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@mail.com",
      "address1": "cikarang , 17550 , ID",
      "address2": "cikarang , 17550 , ID",
      "city": "cikarang",
      "postal_code": "74169",
      "home_phone": "08113597913"
    },
    "customer_ip_address": "192.168.1.1",
    "item_list": [
      {
        "product_code": "product_1",
        "description": "Airline Ticket",
        "quantity": 1,
        "cost_amount": 250000
      }
    ]
  }
}'

You should get response from Aegis like this:

{
  "hit_rules": [],
  "decision": "accept",
  "hit_reasons": []
}

This response indicates your transaction has been successfully evaluated by Aegis and evaluation result is Accept.

Send Transactions to Hit Rules

We will use the rules from previous example.

curl -X "POST" "/api.sandbox.aegisdetection.com/v2/evaluate" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "apiKey: YOUR_API_KEY" \
    -d $'{
  "transaction_id": "11891bf6-f951-45e8-b1db-ea1c47fe26dc",
    "order_datetime": "2016-01-01 12:00:00",
    "bruce_sector": "0100",
    "payment_type": "credit_card",
    "merchant_id": "A000000000000000000001",
  "order_ctl_id": "1404",
  "amount": 250000,
  "card_number": "be6429f1-f845-43d6-bddc-93a1e74e40f5",
  "card_bin": "411111",
  "card_last_four": "0001",
  "d3_eci": "02",
  "bank": "bni",
  "type": "",
  "custom_field_1": "",
  "custom_field_2": "",
  "custom_field_3": "",
  "fs_param": {
    "customer_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "test@domain.com",
      "address1": "Jakarta , 17550 , ID",
      "address2": "Jakarta , 17550 , ID",
      "city": "Jakarta",
      "postal_code": "74169",
      "home_phone": "08113597913",
      "country_code": "ID"
    },
    "shipping_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@mail.com",
      "address1": "Jakarta , 17550 , ID",
      "address2": "Jakarta , 17550 , ID",
      "city": "Jakarta",
      "postal_code": "74169",
      "home_phone": "08113597913"
    },
    "customer_ip_address": "192.168.1.1",
    "item_list": [
      {
        "product_code": "product_1",
        "description": "Airline Ticket",
        "quantity": 1,
        "cost_amount": 250000
      }
    ]
  }
}'

This transaction should hit the rule. You can see from the response you got from Aegis, it should look just like this:

{
    "hit_rules": [
        "Rule ID"
    ],
    "decision": "deny",
    "hit_reasons": [
        "Deny when email is equal to test@domain.com"
    ]
}
curl -X "POST" "/api.sandbox.aegisdetection.com/v2/evaluate" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "apiKey: YOUR_API_KEY" \
    -d $'{
  "transaction_id": "11891bf6-f951-45e8-b1db-ea1c47fe26dc",
    "order_datetime": "2016-01-01 12:00:00",
    "bruce_sector": "0100",
    "payment_type": "credit_card",
    "merchant_id": "A000000000000000000001",
  "order_ctl_id": "1404",
  "amount": 250000,
  "card_number": "be6429f1-f845-43d6-bddc-93a1e74e40f5",
  "card_bin": "411111",
  "card_last_four": "0001",
  "d3_eci": "02",
  "bank": "bni",
  "type": "",
  "custom_field_1": "",
  "custom_field_2": "",
  "custom_field_3": "",
  "fs_param": {
    "customer_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@gmail.com",
      "address1": "Jakarta , 17550 , ID",
      "address2": "Jakarta , 17550 , ID",
      "city": "Jakarta",
      "postal_code": "74169",
      "home_phone": "08113597913",
      "country_code": "ID"
    },
    "shipping_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@mail.com",
      "address1": "Tokyo , 17550 , JP",
      "address2": "Tokyo , 17550 , JP",
      "city": "Tokyo",
      "postal_code": "74169",
      "home_phone": "08113597913",
      "country_code": "JP"
    },
    "customer_ip_address": "192.168.1.1",
    "item_list": [
      {
        "product_code": "product_1",
        "description": "Airline Ticket",
        "quantity": 1,
        "cost_amount": 250000
      }
    ]
  }
}'

This transaction should hit the rule. You can see from the response you got from Aegis, it should look just like this:

{
    "hit_rules": [
        "Rule ID"
    ],
    "decision": "deny",
    "hit_reasons": [
        "Deny when billing country is not equal to shipping country"
    ]
}
curl -X "POST" "/api.sandbox.aegisdetection.com/v2/evaluate" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "apiKey: YOUR_API_KEY" \
    -d $'{
  "transaction_id": "11891bf6-f951-45e8-b1db-ea1c47fe26dc",
    "order_datetime": "2016-01-01 12:00:00",
    "bruce_sector": "0100",
    "payment_type": "credit_card",
    "merchant_id": "A000000000000000000001",
  "order_ctl_id": "1404",
  "amount": 250000,
  "card_number": "be6429f1-f845-43d6-bddc-93a1e74e40f5",
  "card_bin": "411111",
  "card_last_four": "0001",
  "d3_eci": "02",
  "bank": "bni",
  "type": "",
  "custom_field_1": "",
  "custom_field_2": "",
  "custom_field_3": "",
  "fs_param": {
    "customer_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@gmail.com",
      "address1": "Jakarta , 17550 , ID",
      "address2": "Jakarta , 17550 , ID",
      "city": "Jakarta",
      "postal_code": "74169",
      "home_phone": "08113597913",
      "country_code": "ID"
    },
    "shipping_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@mail.com",
      "address1": "Jakarta , 17550 , ID",
      "address2": "Jakarta , 17550 , ID",
      "city": "Jakarta",
      "postal_code": "74169",
      "home_phone": "08113597913",
      "country_code": "ID"
    },
    "customer_ip_address": "192.168.1.1",
    "item_list": [
      {
        "product_code": "product_1",
        "description": "Airline Ticket",
        "quantity": 1,
        "cost_amount": 250000
      }
    ]
  }
}'

You should get a response like this from Aegis:

{
    "hit_rules": [
        "Rule ID"
    ],
    "decision": "accept",
    "hit_reasons": []
}

The second transaction:

curl -X "POST" "/api.sandbox.aegisdetection.com/v2/evaluate" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "apiKey: YOUR_API_KEY" \
    -d $'{
  "transaction_id": "11891bf6-f951-45e8-b1db-ea1c47fe26dc",
  "order_datetime": "2016-01-01 13:00:00",
    "bruce_sector": "0100",
    "payment_type": "credit_card",
    "merchant_id": "A000000000000000000001",
    "order_ctl_id": "1404",
  "amount": 250000,
  "card_number": "be6429f1-f845-43d6-bddc-93a1e74e40f5",
  "card_bin": "411111",
  "card_last_four": "0001",
  "d3_eci": "02",
  "bank": "bni",
  "type": "",
  "custom_field_1": "",
  "custom_field_2": "",
  "custom_field_3": "",
  "fs_param": {
    "customer_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@gmail.com",
      "address1": "Jakarta , 17550 , ID",
      "address2": "Jakarta , 17550 , ID",
      "city": "Jakarta",
      "postal_code": "74169",
      "home_phone": "08113597913",
      "country_code": "ID"
    },
    "shipping_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@mail.com",
      "address1": "Jakarta , 17550 , ID",
      "address2": "Jakarta , 17550 , ID",
      "city": "Jakarta",
      "postal_code": "74169",
      "home_phone": "08113597913",
      "country_code": "JP"
    },
    "customer_ip_address": "192.168.1.1",
    "item_list": [
      {
        "product_code": "product_1",
        "description": "Airline Ticket",
        "quantity": 1,
        "cost_amount": 250000
      }
    ]
  }
}'

This transaction should hit the rule. You can see from the response you got from Aegis, it should look just like this:

{
    "hit_rules": [
        "Rule ID"
    ],
    "decision": "deny",
    "hit_reasons": [
        "Deny when more than 1 transaction per email in one day"
    ]
}

The first transaction:

curl -X "POST" "/api.sandbox.aegisdetection.com/v2/evaluate" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "apiKey: YOUR_API_KEY" \
    -d $'{
  "transaction_id": "11891bf6-f951-45e8-b1db-ea1c47fe26dc",
    "order_datetime": "2016-01-01 12:00:00",
    "bruce_sector": "0100",
    "payment_type": "credit_card",
    "merchant_id": "A000000000000000000001",
  "order_ctl_id": "1404",
  "amount": 250000,
  "card_number": "be6429f1-f845-43d6-bddc-93a1e74e40f5",
  "card_bin": "411111",
  "card_last_four": "0001",
  "d3_eci": "02",
  "bank": "bni",
  "type": "",
  "custom_field_1": "",
  "custom_field_2": "",
  "custom_field_3": "",
  "fs_param": {
    "customer_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@gmail.com",
      "address1": "Jakarta , 17550 , ID",
      "address2": "Jakarta , 17550 , ID",
      "city": "Jakarta",
      "postal_code": "74169",
      "home_phone": "08113597913",
      "country_code": "ID"
    },
    "shipping_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@mail.com",
      "address1": "Jakarta , 17550 , ID",
      "address2": "Jakarta , 17550 , ID",
      "city": "Jakarta",
      "postal_code": "74169",
      "home_phone": "08113597913",
      "country_code": "ID"
    },
    "customer_ip_address": "192.168.1.1",
    "item_list": [
      {
        "product_code": "product_1",
        "description": "Airline Ticket",
        "quantity": 1,
        "cost_amount": 250000
      }
    ]
  }
}'

You should get a response like this from Aegis:

{
    "hit_rules": [
        "Rule ID"
    ],
    "decision": "accept",
    "hit_reasons": []
}

The second transaction:

curl -X "POST" "/api.sandbox.aegisdetection.com/v2/evaluate" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "apiKey: YOUR_API_KEY" \
    -d $'{
  "transaction_id": "11891bf6-f951-45e8-b1db-ea1c47fe26dc",
    "order_datetime": "2016-01-01 13:00:00",
    "bruce_sector": "0100",
    "payment_type": "credit_card",
    "merchant_id": "A000000000000000000001",
  "order_ctl_id": "1404",
  "amount": 250000,
  "card_number": "be6429f1-f845-43d6-bddc-93a1e74e40f5",
  "card_bin": "411111",
  "card_last_four": "0001",
  "d3_eci": "02",
  "bank": "bni",
  "type": "",
  "custom_field_1": "",
  "custom_field_2": "",
  "custom_field_3": "",
  "fs_param": {
    "customer_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@gmail.com",
      "address1": "Jakarta , 17550 , ID",
      "address2": "Jakarta , 17550 , ID",
      "city": "Jakarta",
      "postal_code": "74169",
      "home_phone": "08573345678",
      "country_code": "ID"
    },
    "shipping_data": {
      "first_name": "John",
      "last_name": "Watson",
      "email": "john.watson@mail.com",
      "address1": "Jakarta , 17550 , ID",
      "address2": "Jakarta , 17550 , ID",
      "city": "Jakarta",
      "postal_code": "74169",
      "home_phone": "08113597913",
      "country_code": "ID"
    },
    "customer_ip_address": "192.168.1.1",
    "item_list": [
      {
        "product_code": "product_1",
        "description": "Airline Ticket",
        "quantity": 1,
        "cost_amount": 250000
      }
    ]
  }
}'

This transaction should hit the rule. You can see from the response you got from Aegis, it should look just like this:

{
    "hit_rules": [
        "Rule ID"
    ],
    "decision": "deny",
    "hit_reasons": [
        "Deny when more than 1 phone number per email in one hour"
    ]
}

Congratulations! Now you already able to send your transactions to Aegis and got evaluation result! In the next sections, we’ll share the details of every feature that you can work with in Aegis console. We’ll also help you to setup a more complex rules that will suit your business needs.

API Reference

API Base URL

SANDBOX ENVIRONMENT /api.sandbox.aegisdetection.com
PRODUCTION ENVIRONMENT /api.aegisdetection.com

API Authentication

Each API request will be authenticated using API Key. Please contact aegis@midtrans.com to get your API Key (see also Getting started section). API Key for SANDBOX environment will be different with PRODUCTION environment.

Transaction Evaluation

This endpoint evaluate transaction on Aegis Engine:

HTTP Method

POST

Request Path

API_BASE_URL/v2/evaluate

HTTP Header

Content-Type application/json
Accept application/json
apiKey YOUR_API_KEY

Parameters

Encoding: UTF-8

Required Fields

You need to always include these fields to evaluate your transactions.

Name Type Description Min Length Max Length
transaction_id String Unique ID for transaction identifier 1 255
order_datetime String Transaction order datetime formatted as
YYYY-MM-DD hh:mm:ss in UTC timezone
19 19
bruce_sector String Aegis sector identifier – see in “Sectors” page of your portal 0 255
payment_type String Payment method that being used. Available:
Credit_card
Bank_transfer
Echannel
You can add any other payment method in this field.
1 255

Provided Fields

These are the fields which Aegis can process. You can send any of these fields in your transaction evaluation request.

Name Type Description Min Length Max Length
merchant_id String Merchant identifier 1 255
order_ctl_id String Transaction identifier generated from Merchant 0 255
amount Long Transaction amount without decimal value (ex. 100000 equal to 100.000,00) 0 11
card_number String Tokenized card number data 0 255
card_bin String Bank Identification Number – The first 6 digits of credit card number 0 255
card_last_four String The last 4 digits of credit card number 0 255
currency String Currency of amount.
Use ISO 4217 Alphabetic code
484-822-5774
0 3
d3_eci String Electronic Commerce Indicator Value,
applicable for Credit Card - 3D Secure transactions
0 255
bank String Acquiring bank which the transaction used 0 255
type String Acquiring bank which the transaction used 0 255

Grouped Fields

FS Data

For these fields, the value must be a nested object with the appropriate subfields.

Customer Data

Name Type Description Min Length Max Length
first_name String Customer’s first name 0 255
last_name String Customer’s last name 0 255
email String Customer’s email 0 255
address1 String Customer’s address 0 255
address2 String Customer’s address 0 255
city String Customer’s home city 0 255
postal_code String Customer’s home zip code 0 255
home_phone String Customer’s home phone number 0 255
country_code String Customer’s home country code.
Use ISO 3166-1 Alpha 3
6144628356
0 3

Shipping Data

Name Type Description Min Length Max Length
first_name String First name 0 255
last_name String Last name 0 255
email String Email 0 255
address1 String Shipping address 0 255
address2 String Shipping address 0 255
city String Shipping city 0 255
postal_code String Shipping zip code 0 255
home_phone String Shipping phone number 0 255
country_code String Customer’s home country code.
Use ISO 3166-1 Alpha 3
/en.wikipedia.org/wiki/ISO_3166-1_alpha-3
0 3

Customer IP Address

Name Type Description Min Length Max Length
customer_ip_address String IP Address of customer who made the purchase 0 255

Items Data

Name Type Description Min Length Max Length
product_code String Item product code, ID, or SKU 0 255
description String Item name or any description of product 0 255
brand String Item brand name or code 0 255
category String Item specific category (e.g. Gadgets, Books, etc) 0 255
merchant_name String Seller ID (applicable if you provide a platform for other people to sell) 0 255
quantity Long Quantity of item bought 0 11
cost_amount Long Cost of item bought 0 11

Custom Fields

These fields can be used to capture data points which not covered by our required/provided/grouped fields. You can use up to 3 custom fields for sending your transaction evaluation request.

Name Type Description Min Length Max Length
custom_field_1 String Available field to send custom data 0 255
custom_field_2 String Available field to send custom data 0 255
custom_field_3 String Available field to send custom data 0 255

Success Response

Success response will have http response status 200 OK.

Error messages

Here are some common error messages that might occurred:

Sample error #1

{
  "message": "No API Key found in headers, body or querystring"
}

You need to set apiKey in your request header.

Sample error #2

{
  "message": "Invalid authentication credentials"
}

Your API Key is not valid. Note that API key for SANDBOX is different with PRODUCTION environment.

Sample error #3

{
  "message": "Request not authorize : Invalid Sector"
}

bruce_sector that you specified in request body is not valid. Please check on AEGIS CONSOLE to see your avaliable sectors.

Sample error #4

{
  "message": "An unexpected error occurred"
}

Check your request body. There might be a typo or syntatic error. The request body must be in a valid JSON format.

Sample error #5

{
  "errors": [
    "transaction_id can't be blank",
    "payment_type can't be blank",
    "order_datetime cant' be blank"
  ]
}

Check your request body. Make sure you set all required fields. If you already set all the required fields but still got this error, please check your request header. Make sure you set the Content-Type & Accept as application/json.

Update Transaction

FINAL DECISION

This API is to be used to update the status of the transaction. For example: if Aegis evaluation result is Accept, you will send the transaction to the bank. If the bank has successfully charged the transaction, you can send the update status as Capture or Settlement.

MERCHANT DECISION

When Aegis evaluation result is Challenge, you can send the updated result after reviewing the transaction, whether it got accepted or denied.

HTTP Method

PUT

Request Path

API_BASE_URL/v2/transactions/:transaction_id

HTTP Header

Content-Type application/json
Accept application/json
apiKey YOUR_API_KEY

Parameters

Encoding: UTF-8

Provided Fields

These are the fields which Update Transaction can process. You can send any of these fields in your transaction update request.

Name Type Description Min Length Max Length
final_decision String Transaction final decision
Possible value is settlement, deny, cancel, capture
At least final_decision or merchant_decision or both should be specified
0 255
merchant_decision String Merchant decision for challenge transaction
Possible value is accepted, denied, ignored
At least final_decision or merchant_decision or both should be specified
0 255

Sample

curl -X "PUT" "API_BASE_URL/api/v2/transactions/:transaction_id" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "apiKey: YOUR_API_KEY" \
-d '{
      "final_decision":"accept",
      "merchant_decision":"denied"
    }'

Success Response

Success response will have http response status 200 OK.

{
  "meta": {
    "status_code": "200"
  },
  "data": "Transaction updated"
}

Error Messages

Here are some common error messages with http status 400 Bad Request that might occurred:

Sample error

{
  "error": {
    "status_code": "400",
    "full_messages": "can't update transaction"
  }
}

You need to set correct transaction_id

Create or Update Merchant

You can register your merchant data into Aegis so that it will be shown in transactions page and you can have a database of your merchants and its sector inside Aegis.

HTTP Method

POST

Request Path

API_BASE_URL/v2/merchants

HTTP Header

Content-Type application/json
Accept application/json
apiKey YOUR_API_KEY

Parameters

Encoding: UTF-8

Provided Fields

Name Type Description Min Length Max Length
mid String Merchant identifier. Required. 1 255
name String Merchant name. Required. 1 255
sector_id String Sector identifier of this merchant. Required. 4 4

Sample

curl -X "POST" "API_BASE_URL/v2/merchants" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "apiKey: YOUR_API_KEY" \
-d $'{
    "mid": "M1234",
    "name": "Sample merchant name",
    "sector_id": "0800"
}'

Success Response

Success response will have http response status 200 OK.

Error Messages

Here are some common error messages with http status 400 Bad Request that might occurred:

Sample error #1

{
  "error": true,
  "message": [
    "Mid can't be blank",
    "Name can't be blank"
  ]
}

You need to specify mid & name. Both can’t be blank.

Sample error #2

{
  "error": true,
  "message": [
    "Sector is not belong to the organization"
  ]
}

You need to specify sector_id that belongs to your organization.