Quick Start

Get up and running with Embermind API in 5 minutes. This guide shows you how to submit your first transaction and receive a risk score.

Prerequisites

Before you begin, make sure you have:

API Key (apiKeyValue) from your account manager
curl or any HTTP client installed

Verify Your API Key

First, let's confirm your API key is working:

curl -X GET 'https://api.embermind.ch/api/v1/client/profile/me' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

Expected Response:

{
  "id": "f0fab777-fd19-4330-2229-8f4431239a1acf",
  "email": "[email protected]",
  "login": "your_login",
  "companyId": "7992110d-617e-40c5-8232-3b9a94e8248ad2f1"
}

If you see your profile info, your API key is valid. If you get an error, check the Authentication guide.

Submit Your First Transaction

Now let's submit a transaction for risk scoring:

curl -X POST 'https://api.embermind.ch/api/v1/client/transaction-process' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "externalId": "test_txn_001",
    "status": "NEW",
    "type": "PAYMENT",
    "dateStart": "2024-01-15T10:30:00.000Z",
    "currency": "EUR",
    "amount": "99.99",
    "merchantExternalId": "merchant_001",
    "merchantAccountExternalId": "account_001",
    "email": "[email protected]",
    "cardToken": "card_hash_abc123",
    "cardBin": "411111",
    "cardLastFourDigit": "1234",
    "ipAddress": "203.0.113.42"
  }'

Expected Response:

{
  "transactionId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
  "transactionExternalId": "test_txn_001",
  "isNeedCheckReturnUrl": false,
  "scoreResultList": []
}

Note: For your first transaction, scoreResultList will be empty. This is expected behavior — score generators analyze transaction history (e.g., "how many cards has this fingerprint used before?"). Since this is the first transaction, there's no history to analyze yet.

Understanding the Response

Field	Description
`transactionId`	Unique ID assigned by Embermind
`transactionExternalId`	Your transaction ID (echoed back)
`isNeedCheckReturnUrl`	Whether Link Detection is enabled for this transaction
`scoreResultList`	Risk scores per gate (empty for first transaction)

When Will Scoring Appear?

Scoring activates when the system has enough data to analyze patterns:

{
  "transactionId": "...",
  "transactionExternalId": "test_txn_005",
  "isNeedCheckReturnUrl": false,
  "scoreResultList": [
    {
      "gateExternalId": "gate_001",
      "scoreValue": 15,
      "badScoreBorder": 41,
      "scoreItemList": [
        {
          "type": "CARD_COUNT_PER_ONE_FINGERPRINT",
          "scoreValue": 5
        },
        {
          "type": "EMAIL_COUNT_PER_CUSTOMER",
          "scoreValue": 10
        }
      ]
    }
  ]
}

Risk Assessment:

scoreValue < badScoreBorder → Transaction is likely safe ✅
scoreValue >= badScoreBorder → Transaction may be fraudulent ⚠️

Update Transaction Status

When the transaction completes, update its status:

curl -X POST 'https://api.embermind.ch/api/v1/client/transaction-process' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "externalId": "test_txn_001",
    "status": "ACCEPT",
    "type": "PAYMENT",
    "dateStart": "2024-01-15T10:30:00.000Z",
    "dateEnd": "2024-01-15T10:31:00.000Z",
    "currency": "EUR",
    "amount": "99.99",
    "merchantExternalId": "merchant_001",
    "merchantAccountExternalId": "account_001"
  }'

Transaction statuses flow: NEW → PENDING → ACCEPT or DECLINE

What's Next?

You've successfully:

✅ Verified your API credentials
✅ Submitted a transaction for risk scoring
✅ Received and interpreted the risk score

Continue learning:

Guide	Description
Authentication	API Key vs Access Token, error handling
Commission Setup	Configure fee calculation
Customer Grouping	Set up customer identification rules
Data Migration	Import historical transactions

Troubleshooting

Error: error.auth.api_key_incorrect

Check that your API key is correct
Ensure the x-api-key header is present

Error: error.validation.*

Verify all required fields are present
Check field formats (dates in ISO 8601, amounts as strings)

Empty scoreResultList

Scoring may be disabled for your company
Contact your manager to enable score generators

Need Help?

For integration support, contact your Embermind account manager.