CARD operation import - with transaction monitoring

Just so you know, further examples and descriptions apply only to CARD-CASH operation imports with transaction monitoring.

This section provides information how to submit operation (transaction) details to our database and is focused to those operations which require to perform transaction monitoring. It includes examples of API requests with mandatory and optional fields, a comprehensive list of all available fields, common responses and error descriptions. CARD-CASH operation is a simple cash withdrawal from ATM. So in this case note that: DEBTOR - is an entity CREDITOR - is an ATM. HTTP Method: POST Path: {{baseUrl}}/amlyze-ws-rest/operation ContentType: application/json Authorization: Bearer Token

API requests examples

Show Mandatory fields example | CARD-CASH operation import - with transaction monitoring

{
  "communicationNumber": "Com_458",
  "requester": "ATM",

  "operationExtId": "ExtId_458",
  "operationType": "CARD_CASH",
  "cardOperationSubType": "CARD_CASH_WITHDRAWAL",
  "riskManagementCategory": "OP_DEFAULT",
  "sourceOfRiskLevel": "EVALUATE",
  "operationDateTime": "2024-01-22T15:09:33+02:00",
  "financialFlowDirection": "OUTGOING",
  "currency": "EUR",
  "amount": 2000,
  "description": "ATM TBCBANK CEN: Cash Withdrawal",
  "listOperationParty": [
      {
          "partyRole": "DEBTOR",
          "accountNumber": "LT933520036948858623",
          "bic": "BICXX22",
          "entityType": "INDIVIDUAL",
          "firstName": "Geli",
          "lastName": "Deliono"
      },
      {
          "partyRole": "CREDITOR",
          "accountNumber": "ATM TBCBANK CEN ",
          "entityType": "UNKNOWN",
          "title": "ATM"
      }
  ]
}

Show Mandatory fields example | CARD-CASH operation import - with transaction monitoring and screening

{
  "communicationNumber": "Com_458",
  "requester": "ATM",

  "operationExtId": "ExtId_458",
  "operationType": "CARD_CASH",
  "cardOperationSubType": "CARD_CASH_WITHDRAWAL",
  "riskManagementCategory": "OP_DEFAULT",
  "sourceOfRiskLevel": "EVALUATE",

  "initializeScreeningProcesses": [
       "SANCTIONS",
       "PEP",
       "ADVERSE_MEDIA",
       "INTERNAL_LIST"
  ],

  "operationDateTime": "2024-01-22T15:09:33+02:00",
  "financialFlowDirection": "OUTGOING",
  "currency": "EUR",
  "amount": 2000,
  "description": "ATM TBCBANK CEN: Cash Withdrawal",
  "listOperationParty": [
      {
          "partyRole": "DEBTOR",
          "accountNumber": "LT933520036948858623",
          "bic": "BICXX22",
          "entityType": "INDIVIDUAL",
          "firstName": "Geli",
          "lastName": "Deliono"
      },
      {
          "partyRole": "CREDITOR",
          "accountNumber": "ATM TBCBANK CEN ",
          "entityType": "UNKNOWN",
          "title": "ATM"
      }
  ]
}

Show All fields example | CARD-CASH operation import - with transaction monitoring

{
  "communicationNumber": "Com_0027",
  "requester": "AMLYZE",
  "businessUnit": "Unit B",
  
  "operationExtId": "ExtId_0027",
  "operationType": "CARD_CASH",
  "cardOperationSubType": "CARD_CASH_WITHDRAWAL",
  "riskManagementCategory": "OP_DEFAULT",
  "sourceOfRiskLevel": "EVALUATE",

  "initializeScreeningProcesses": [
      "SANCTIONS",
      "ADVERSE_MEDIA",
      "PEP",
      "INTERNAL_LIST"
  ],

  "riskLevel": "HIGH",
  "operationDateTime": "2024-01-22T15:09:33+02:00",
  "sourceCountry": "LT",
  "destinationCountry": "LT",
  "currency": "EUR",
  "amount": 5000,
  "euroExchangeRate": 1,
  "amountInEuro": 5000,
  "financialFlowDirection": "OUTGOING",
  "description": "BANKOMAT TBC: Manual Cash Disbursements",
  "ipAddress": "222.222.222.222",
  "ipAddressCountry": "LT",
  "terminalExtId": "TerminalExtId_0101",
  "terminalCode": "TerminalCode_0101",
  "merchantExtId": "MerchantExtId_0101",
  "merchantCode": "MerchantCode_0101",
  "merchantDescription": "Decription of a merchant",
  "merchantName": "XYZ Bank Group - Merchant 1",
  "merchantCountryCode": "UA",
  "salesPointExtId": "SalesPointExtId_0101",
  "salesPointCode": "SalesPointCode_0101",
  "listOperationParty": [
      {
          "partyRole": "DEBTOR",
          "accountNumber": "LT933520036948858623",
          "bic": "BICXX22",
          "currency": "EUR",
          "bankTitle": "TBC",
          "entityType": "INDIVIDUAL",
          "firstName": "Geli",
          "lastName": "Deliono",
          "address": "Baltų pr. 16, LT-44001, Kauno m. sav.",
          "country": "LT",
          "cardNumber": "5167945220452179",
          "cardValidTill": "2025-12-01",
          "cardHolderName": "Geli Jr. Deliono"
      },
      {
          "partyRole": "CREDITOR",
          "accountNumber": "BANKOMAT TBC",
          "bic": "BIC23",
          "currency": "EUR",
          "bankTitle": "TBC",
          "entityType": "UNKNOWN",
          "title": "MINDAUGO G.1: TBC ATM – Manual Cash Disbursements"
      }
  ]
}

Fields

communicationNumber

string(256)

required

Unique number of communication.Example: ComNr_01_TEST

requester

string(100)

required

Name of the system requesting web service.Example: Amlyze

businessUnit

string(255) from classifier list

❗Mandatory field for clients utilizing a multi-organizational solution. Omit this parameter unless instructed about it.It serves to specify the unique identifier for the business unit. Business units are logical groupings of users and data. Each business unit can have its own set of users, permissions, and data access rules.Example: BUSINESS_UNIT_NAME

Show Path to extract classifier values

HTTP Method: GETPath: {{baseUrl}}/classifier/businessUnit

operationExtId

string(255)

required

External identifier of operation.Example: Op_01_SEPA_TEST

operationType

string

required

Notifies about which kind of operation type was performed.Value: CARD_CASH

cardOperationSubType

string(255)

required

Card operation subtype code.Example: CARD_CASH_WITHDRAWAL

riskManagementCategory

string(255) from classifier list

required

Code of risk management category of the object. Value must be from a classifier list personalized to your company.Example: OP_TRANSFER

Show Path to extract classifier values

HTTP Method: GETPath: {{baseUrl}}/classifier/riskManagementCategory

sourceOfRiskLevel

string

required

The value “EVALUATE” is used for normal business processes - risk assessment will be performed.Value: EVALUATE

initializeScreeningProcesses

list[]

Defines which lists to check during screening process. Strings of the list are noted in the dropdown below.

Show list[]

   "initializeScreeningProcesses": [
       "SANCTIONS",
       "PEP",
       "ADVERSE_MEDIA",
       "INTERNAL_LIST"
   ]

Example: PEP, ADVERSE_MEDIA

operationDateTime

date

required

The operation date and time show when the operation proceeded.Example: 2024-08-16T13:00:00Z

sourceCountry

string(ISO 3166-1 alpha-2) from classifier list

Country rom where the operation was initiated.

Show Path to extract classifier values

HTTP Method: GETPath: {{baseUrl}}/classifier/country

Example: LT

destinationCountry

string(ISO 3166-1 alpha-2) from classifier list

Country of operation’s destination.

Show Path to extract classifier values

HTTP Method: GETPath: {{baseUrl}}/classifier/country

Example: LT

currency

string(255) from classifier list

required

International currency code.

Show Path to extract classifier values

HTTP Method: GETPath: {{baseUrl}}/classifier/currency

Value: EUR

amount

BigDecimal

required

Amount of money sent in an operation.Example: 1499

euroExchangeRate

BigDecimal

❗Mandatory if currency is not EUR. Not Used when currency is EUR.Euro exchange rate for other than Eur currency.Example: 0.93

amountInEuro

BigDecimal

❗Mandatory if currency is not EUR. Not Used when currency is EUR.Amount of money in euro currency.Example: 1499

financialFlowDirection

string from enum

required

Refers to the movement of money between entities or accounts.Enum class values: INCOMING, OUTGOINGExample: INCOMING

description

string(550)

required

The purpose of payment is saved under description.Example: Invoice '02'

ipAddress

string(255)

The IP address of the operation.Example: xxx.zzz.yyyy.www

ipAddressCountry

string(ISO 3166-1 alpha-2) from classifier list

Country of an IP address of the operation.

Show Path to extract classifier values

HTTP Method: GETPath: {{baseUrl}}/classifier/country

Example: LT

terminalExtId

string(100)

External identifier of the terminal.Example: t_extid_145

terminalCode

string(100)

External code of terminal.Example: 57455

merchantExtId

string(100)

External identifier of the seller-mediator.Example: External_0112

merchantCode

string(50)

External identifier of the seller-mediator.Example: 5541

merchantDescription

string(32768)

Seller-mediator description.Example: Ecommerce merchants

merchantName

string(32768)

Name of the seller-mediator.Example: Costco

merchantCountryCode

string(ISO 3166-1 alpha-2) from classifier list

Seller-mediator country code.

Show Path to extract classifier values

HTTP Method: GETPath: {{baseUrl}}/classifier/country

Example: ES

salesPointExtId

string(100)

External identifier of the sales point.Example: S_extid_0145

salesPointCode

string(50)

External code of the sales point.Example: 54574

listOperationParty

list[]

required

List of entities that belong to one operation. Fields of the list are described in the dropdown below.

Show listOperationParty list[] fields

partyRole

string from enum

required

The role of the party in ongoing operation. At least one operation party account must already exist in Amlyze.Only one operation can be imported per API request which means only one CREDITOR and one DEBTOR could be provided.Enum class values: DEBTOR, CREDITOR, ULTIMATE_DEBTOR, ULTIMATE_CREDITORIf financialFlowDirection is INCOMING your customer is CREDITOR. If financialFlowDirection is OUTGOING your customer is DEBTOR.Example: CREDITOR

accountNumber

string(255)

required

❗Not mandatory if partyRole is ULTIMATE_DEBTOR or ULTIMATE_CREDITOR.Unique account identification number used in performing operations.Example: LT038625979279192518

bic

string(100)

required

❗Mandatory only for your customer. Not mandatory for counterparties.Bank identifier code for account number.Example: BICXX22

currency

string(255) from classifier list

required

International currency code.

Show Path to extract classifier values

HTTP Method: GETPath: {{baseUrl}}/classifier/currency

Value: EUR

bankTitle

string(255)

Title of bank at which the operation is happening.Example: TBC bank

entityType

string from enum

required

Describes client status.Enum class values: INDIVIDUAL, ORGANIZATION, UNKNOWNUNKNOWN is valid only for counterparties.Example: INDIVIDUAL

firstName

string(100)

Individual entity’s first name, used only together with lastName and never alone.Example: Eduardo

lastName

string(100)

Individual entity’s last name, used only together with firstName and never alone.Example: Rodriguez

title

string(255)

required

❗Not mandatory if entity is INDIVIDUAL and both firstName and lastName are provided.Identifies a party (INDIVIDUAL, ORGANIZATION or UNKNOWN) without requiring firstName or lastName.Example: Moller

identifier

string(255)

❗Mandatory only when “partyRole” = “ULTIMATE_” and no more elements are provided for that party.Unique identification number (e.g., personal ID, company VAT code) to distinguish the payer and the transaction. Can be used for customer, counterparty and ultimateparty.Example: 50007153359

address

string(4000)

Party’s nformation including street address, city, and possibly other relevant details.Example: Verkių g. 7-8, Vilnius

Country

string(ISO 3166-1 alpha-2) from classifier list

Two-letter country code specifying the participant’s country.

Show Path to extract classifier values

HTTP Method: GETPath: {{baseUrl}}/classifier/country

Example: DE

cardNumber

string(255)

Card number written on the card.Example: 4720582145647937

cardValidTill

string(255)

Card date of expiration written on the card.Example: 2025-06-07

cardHolderName

string(255)

Name written on the card.Example: Eduardo Rodrigues

List of possible responses

This part lists common responses after the submission of the request.

200 OK
  "resultType": "REQUEST_ACCEPTED"


400 Bad Request
    "resultType": "REQUEST_REJECTED",
    "errorCode": "O001",
    "errorDescription": "CommunicationNumber already used in amlyze"


404 Not Found
    "timestamp": "2024-05-26T16:49:50.237+00:00",
    "status": 404,
    "error": "Not Found",
    "path": "/amlyze-ws-rest/opeation" --> mistake inside the endpoint


500 Internal Server Error
  "resultType": "REQUEST_REJECTED"
  "status": 500,
  "error": "Internal Server Error"

List of possible errors

This section lists the possible errors that can occur when making a bad operation request to the API. A bad request is a request that somehow does not follow the API specifications.

Error Description
DestinationCountry is mandatory, check country classifier codes for allowed values.
Amount is mandatory and must be greater than 0.
Despite currency = EUR, AmountInEur differs from Amount.
AmountInEur is mandatory and must be greater than 0.
EuroExchangeRate is mandatory and must be greater than 0.
For non-INTERNAL operation, financialFlowDirection value cannot be ‘NULL’.
Description is mandatory.
Invalid MerchantCountryCode.
RiskManagementCategory is mandatory.
RiskManagementCategory does not exist in Amlyze.
RiskManagementCategory does not support Operation.
Account registered to your institution; Account found in Amlyze, but customer not found in Amlyze.
entityType mismatch in operationParty[” + i + ”]: Amlyze customer has different entity type to operation one.
For INCOMING operation, your customer party role must be CREDITOR.
For OUTGOING operation, your customer party role must be DEBTOR.
operationType ” + operationType.getCode() + ” is not defined in Amlyze. Check Operation type classifier for available values.
Problem with operation party (index: ” + i + ”).
Invalid FinancialFlowDirection: Your institution DEBTOR found for INCOMING operation.
Invalid FinancialFlowDirection: Your institution CREDITOR found for OUTGOING operation.
OperationParties must contain CREDITOR.
OperationParties must contain DEBTOR.
Invalid operation party count. Range: min 1, max 4.
Invalid count of operation parties for ” + operationType.getCode() + ” operationType.
For ‘PIS’ operation, only creditor can be provided.
No operation party account related to your institution BIC, or Customer.
Invalid count of your institution operation parties for ” + operationType.getCode() + ” operationType.
Tenant header ’” + securityOwnerService.getHeaderTenantCode() + ”’ is mandatory.
Business unit is mandatory.
Tenant ’” + tenantCode + ”’ business unit ’”+ businessUnitCode +”’ does not exist.
CommunicationNumber is mandatory.
Requester is mandatory.
SourceOfRiskLevel is mandatory, allowed values: IMPORT / EVALUATE.
OperationExtId is mandatory.
OperationType is mandatory.
Problem with OperationType (INVALID): INVALID is not defined in Amlyze. Check Operation type classifier for available values.
Currency is mandatory, check Currency classifier codes for allowed values.
SourceCountry is mandatory, check country classifier codes for allowed values.
Problem with OperationType (SEPA): Problem with OperationParties. No operation party account related to your institution BIC or Customer.
Problem with OperationType (SEPA): Invalid count of your institution operation parties for SEPA operationType.

API Documentation

​API requests examples

​Fields

​List of possible responses

​List of possible errors

API requests examples

Fields

List of possible responses

List of possible errors