Data Migration

Use the Transaction Processing endpoint to migrate historical data: POST /api/v1/client/transaction-process

This endpoint serves two purposes:

Risk scoring — calculates a fraud score for each transaction
Data storage — saves transaction data in the antifraud system

Each transaction requires a separate API call.

Example: ACCEPT Status

curl -X POST 'https://api.embermind.ch/api/v1/client/transaction-process' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxx-yyy-zzz' \
  -d '{
    "externalId": "txn_12345",
    "status": "ACCEPT",
    "type": "PAYMENT",
    "dateStart": "2024-01-15T10:30:00.000Z",
    "dateEnd": "2024-01-15T10:31:00.000Z",
    "currency": "EUR",
    "amount": "100.50",
    "merchantExternalId": "merchant_001",
    "merchantTitle": "My Merchant",
    "merchantAccountExternalId": "account_001",
    "merchantAccountTitle": "Main Account",
    "email": "[email protected]",
    "phone": "+79998887766",
    "cardToken": "card_token_hash",
    "cardBin": "411111",
    "cardCountry": "DE",
    "cardLastFourDigit": "1234",
    "cardExpireDate": "08/28",
    "cardHolder": "John Doe",
    "ipAddress": "1.2.3.4",
    "ipAddressCountry": "DE",
    "fingerprint": "fp_abc123",
    "cascade": {
      "externalId": "cascade_001",
      "title": "Main Cascade",
      "gateList": [
        {
          "externalId": "gate_001",
          "title": "Gate 1",
          "bankExternalId": "bank_001",
          "bankTitle": "Bank 1",
          "currency": "EUR",
          "serialNumber": 1,
          "status": "ACCEPT"
        }
      ]
    }
  }'

Example: DECLINE Status

When a transaction is declined, you must specify declineBy to indicate whether it was rejected by the bank or the system.

curl -X POST 'https://api.embermind.ch/api/v1/client/transaction-process' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxx-yyy-zzz' \
  -d '{
    "externalId": "txn_12346",
    "status": "DECLINE",
    "type": "PAYMENT",
    "dateStart": "2024-01-15T10:32:00.000Z",
    "dateEnd": "2024-01-15T10:33:00.000Z",
    "currency": "EUR",
    "amount": "250.00",
    "merchantExternalId": "merchant_001",
    "merchantTitle": "My Merchant",
    "merchantAccountExternalId": "account_001",
    "merchantAccountTitle": "Main Account",
    "email": "[email protected]",
    "cardToken": "card_token_hash",
    "cardBin": "411111",
    "cardCountry": "DE",
    "cardLastFourDigit": "1234",
    "ipAddress": "1.2.3.4",
    "cascade": {
      "externalId": "cascade_001",
      "title": "Main Cascade",
      "gateList": [
        {
          "externalId": "gate_001",
          "title": "Gate 1",
          "bankExternalId": "bank_001",
          "bankTitle": "Bank 1",
          "currency": "EUR",
          "serialNumber": 1,
          "status": "DECLINE",
          "declineBy": "BANK",
          "errorReason": "DO_NOT_HONOUR_PROCESSING_ERROR"
        }
      ]
    }
  }'

Response Example

Response (200 OK):

{
  "transactionId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
  "transactionExternalId": "txn_12345",
  "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
        }
      ]
    }
  ]
}

Request Parameters

Core Fields

Parameter	Type	Description
externalId	string	Required. Unique transaction identifier in your system. Must be unique within a single company.
status	string	Required. Transaction status: `NEW`, `PENDING`, `ACCEPT`, or `DECLINE`.
type	string	Required. Transaction type: `PAYMENT` or `WITHDRAW`.
dateStart	string	Transaction start timestamp (ISO 8601).
dateEnd	string	Transaction end timestamp (ISO 8601).
currency	string	Transaction currency (ISO 4217).
amount	string	Transaction amount.
description	string	Transaction description.
paymentMethod	string	Payment method information.

Merchant Information

Parameter	Type	Description
merchantExternalId	string	Merchant identifier in your system. Created automatically if not exists.
merchantTitle	string	Merchant display name.
merchantAccountExternalId	string	Merchant account identifier. Created automatically if not exists.
merchantAccountTitle	string	Merchant account display name.
mccId	string	Merchant Category Code.

Order Information

Parameter	Type	Description
merchantOrderId	string	Merchant order identifier.
processingOrderId	string	Processing order identifier.
externalOrderId	string	External order identifier.
rrn	string	Retrieval Reference Number.

Customer Information

Parameter	Type	Description
customerExternalId	string	Customer identifier in your system.
email	string	Customer email address.
phone	string	Customer phone number.
phoneCountry	string	Customer phone country code.
dateOfBirthday	string	Customer date of birth.
isFtd	boolean	Flag indicating customer's first transaction.
isKycPassed	boolean	KYC verification status.
registrationDate	string	Customer registration date.
lastLoginDate	string	Customer last login date.
withdrawalCount	number	Number of customer withdrawals.
depositCount	number	Number of customer deposits.

Card Information

Parameter	Type	Description
cardToken	string	Tokenized card identifier.
cardBin	string	Card BIN (first 6 digits).
cardCountry	string	Card issuing country code.
cardLastFourDigit	string	Last 4 digits of card number.
cardExpireDate	string	Card expiration date (MM/YY).
cardHolder	string	Cardholder name.

Device & Location Information

Parameter	Type	Description
ipAddress	string	Customer IP address.
ipAddressCountry	string	Country code derived from IP.
fingerprint	string	Browser fingerprint identifier.
browserTimezone	string	Customer timezone (e.g., UTC+4).
browserData	object	Raw browser data from SDK.

Address Information

Parameter	Type	Description
addressFull	string	Full customer address.
address1	string	Address line 1.
address2	string	Address line 2.
city	string	Customer city.
country	string	Customer country.
postalCode	string	Postal code.
region	string	Customer region/state.
lang	string	Customer language code.

Return URLs

Parameter	Type	Description
successReturnUrl	string	URL for redirect after successful payment.
failReturnUrl	string	URL for redirect after failed payment.

Additional Data

Parameter	Type	Description
customData	object	Arbitrary JSON data for your reference.

Cascade Object

Parameter	Type	Description
cascade.externalId	string	Cascade identifier. Created if not exists.
cascade.title	string	Cascade display name.
cascade.gateList	array	Array of gates in the cascade.

Gate Object (inside cascade.gateList)

Parameter	Type	Description
externalId	string	Gate identifier. Created if not exists.
title	string	Gate display name.
bankExternalId	string	Bank identifier. Created if not exists.
bankTitle	string	Bank display name.
currency	string	Gate currency.
serialNumber	number	Gate position in cascade sequence.
status	string	Gate status: `NEW`, `ACCEPT`, or `DECLINE`. If DECLINE, declineBy is required.
declineBy	string	Who rejected: `BANK` or `SYSTEM`. Required when status=DECLINE.
errorReason	string	Decline reason code (see values below).
commissionInfo.amountGateCurrency	string	Commission amount in gate currency.
commissionInfo.amountTransactionCurrency	string	Commission amount in transaction currency.

Error Reason Values

Value	Description
PROCESSING_ERROR	General processing error
AUTHENTICATION_PROCESSING_ERROR	Authentication failed
DO_NOT_HONOUR_PROCESSING_ERROR	Do not honour
EMITTER_DENIAL_PROCESSING_ERROR	Issuer denial
FORM_TIMEOUT_PROCESSING_ERROR	Payment form timeout
INSUFFICIENT_FUNDS_PROCESSING_ERROR	Insufficient funds
LIMIT_PROCESSING_ERROR	Limit exceeded
PROCESSOR_DENIAL_PROCESSING_ERROR	Processor denial
THREEDS_REDIRECT_TIMEOUT_PROCESSING_ERROR	3DS redirect timeout
THREEDS_TIMEOUT_PROCESSING_ERROR	3DS timeout
TECHNICAL_PROCESSING_ERROR	Technical error
VALIDATION_PROCESSING_ERROR	Validation error
CARD_TEMPORARILY_BLOCKED	Card temporarily blocked
PLATFORM_ERROR_CARD_BRAND_UNAVAILABLE	Card brand unavailable
PLATFORM_ERROR_GATE_SKIPPED	Gate skipped

Transaction Status Flow

Transactions progress through statuses in one direction only:

NEW → PENDING → ACCEPT
                   or
             → DECLINE

Status cannot be reverted. Once a transaction reaches ACCEPT or DECLINE, it cannot be changed.

Update Rules

All fields can be updated except dateStart
Data is additive — the API only adds data, never deletes
- Example: If you submit a transaction with 10 gates, then resubmit with 10 different gates, the system stores all 20 gates

Currency Conversion

All transaction amounts are automatically converted and stored in USD
Exchange rates are sourced from openexchangerates.org

Post-Migration: Enable Scoring

After data migration is complete:

Contact your manager to activate the required score generators
Start sending real-time transaction data using the same endpoint