Synchronous and asynchronous messaging

There are two ways in which we inform about processing status changes

Synchronous - which is regular response to request send to our system
Asynchronous - where we send a request to provided callbackUrl on some events

For more about requests and responses check First Request

More about callbackUrl parameter you can find under Gateway Transaction

Synchronous response

Is a regular HTTP response for your request. Structure and parameters
are described under Transaction Response

Asynchronous callback

If callbackUrl is provided within GatewayTransaction we notify your system
about case status changes if some events occur (see TransactionChecks callbacks or CustomerChecks callbacks)

Order of requests

Due to asynchronous nature of our system synchronous request and callback requests are processed independently.
It is possible that asynchronous request which might be sent before synchronous request completes.

Security

In order to secure communication between systems we use two layers:

callbackUrl needs to be an HTTPS URL
SECRET which is added as HTTP header to each request

SECRET can be used by your system to authenticate incoming requests to ensure they come from our system.
To configure SECRET visit Case Manager and Workflows & Users section.

static IP address

All callbacks are sent via a static IPv4 address. For the test environment this IP is 35.157.34.99. See more under environments.

TransactionChecks callbacks

Event	Description
Immediate decision	Once an immediate decision is available, executed in addition to synchronous response
Complete decision	Once a complete decision is available
Operator action	Once an operator performs an action

Callback response


{
"payload": {
"caseId": "b3a13774-6f9d-41d3-80f9-fa6618aea790",
"tenantTransactionId": "Your transaction ID",
"transactionStatus": "proceeded",
"processingStatus": "new",
"investigationStatus": "new",
"decisionType": "complete",
"assignedTo": "john@yourdomain.com",
"feedbackStatus": "yes"
}
}

Field name	Description
payload	Top-level object that contains all properties
caseId	A UUID that is assigned to transaction
tenantTransactionId	ID of the transaction at the tenant.
transactionStatus	Status of processing transaction, one of: - proceeded ... transaction can proceed in caller system, depending on configuration even if a case was opened which does not require blocking a case - blocked ... transaction should be blocked in caller system - unblocked ... signals a previously blocked case to be unblocked - none
processingStatus	Result of processing case, one of: - opening ... temporary initial state during processing - unsuspicious ... indicates no suspicion detected hence no open case - machine-review ... temporary state during ML review while processing - relieved ... indicates a initially suspicious case relieved/auto-closed by system - new ... indicates a new open/suspicious case - operator-review ... indicates when an operator assigns a case to him-/herself. Typically following processStatus=new. - accepted ... indicates a case being closed/accepted by an operator (=final state). "Accepted" in Transaction cases means the case has been worked on and review is finalized. Typically following processingStatus=operator-review (or escalated) - escalated ... indicates a case being escalated into second level. Typically following processingStatus=operator-review. - sar-filing ... indicates hardened suspicion and preparation of SAR filing. Typically following processingStatus=escalated. - sar-filed ... indicates file SAR for a case and closed (=final state). Typically following processingStatus=sar-filing. - reopening ... temporary state reopening a closed case (processingStatus=accepted or sar-filed) - reopened ... indicates previously case (processingStatus=accepted or sar-filed) opened again.
investigationStatus	Result of processing case, one of: - opening ... temporary initial state during processing - unsuspicious ... indicates no suspicion detected hence no open case - machine-review ... temporary state during ML review while processing - relieved ... indicates a initially suspicious case relieved/auto-closed by system - new ... indicates a new open/suspicious case - initial-review ... indicates when a 1st line operator assigns a case to him-/herself. Typically following investigationStatus=new - waiting-for-operator ... indicates a 1st line operator has moved the case to 2nd line. A 2nd line operator can then assign the case to him-/herself. Typically following investigationStatus=initial-review. - operator-review ... indicates when an operator (or 2nd line operator) assigns a case to him-/herself. Typically following investigationStatus=new or investigationStatus=waiting-for-operator - request-for-information ... indicates when an operator has requested information from an end-customer or another team and must return to the case once he/she receives the relevant info. Typically following investigationStatus=initial-review or investigationStatus=operator-review. - accepted ... indicates a case being closed/accepted by an operator (=final state). "Accepted" in Transaction cases means the case has been worked on and review is finalized. Typically following investigationStatus=operator-review (or escalated) - escalated ... indicates a case being escalated into second level. Typically following investigationStatus=operator-review. - sar-filing ... indicates hardened suspicion and preparation of SAR filing. Typically following investigationStatus=escalated. - sar-filed ... indicates file SAR for a case and closed (=final state). Typically following investigationStatus=sar-filing. - reopening ... temporary state reopening a closed case (investigationStatus=accepted or sar-filed) - reopened ... indicates previously case (investigationStatus=accepted or sar-filed) opened again.
decisionType	Completeness state of processing, one of: - complete - incomplete - immediate
assignedTo	Indicates the email address of the current assignee of the customer case. Can be null if no one is assigned
feedbackStatus	Indicates the feedback buttons clicked when closing a transaction case. Possible values are “yes”, “no”, “inconclusive” and null

Use case: using callbacks to react on unblocking of previously blocked transactions

When the synchronous API responds with flag proceed=false you would stop/park a transaction from execution. Yet that somehow needs to be released.
The proceed=true/false is derived from what the Case Manager calls and the Callback reports as "transactionStatus".
A transactionStatus=blocked will lead to a proceed=false. So transactionStatus is the flag you want to listen to in the callback
When then an operator investigates a case he/she would assign a case and then close it because it turns out to be not suspicious in Case Manager you will get a callback with transactionStatus=unb.locked - that is when you release the transaction.
If you have cases in a case group in Case Manager (our system groups similar cases) it will send you callbacks for each transaction as you need to unblock each and every one of them even though it appears and is worked on in one go in the Case Manager.

CustomerChecks callbacks

Customer checks callbacks have differect structure than TransactionChecks callbacks because of some fields are valid only for Customer Check (like customerStatus or customerId) and some are valid only for Aml Check (like transactionStatus or transactionId)

Event	Description
Complete decision	Once processing is completes and case has been created
Operator action	Once an operator performs an action

Callback response

Example of Decline callback:

{
  "payload": {
    "caseId": "b0682204-9538-4b01-9b49-4df45bf260b6",
    "processingStatus": "declined",
    "customerStatus": "blocked",
    "customerId": "generatedOrProvided",
    "riskLevel": "low",
    "assignedTo": "john@yourdomain.com",
    "screeningResultConfirmed": [
      {
        "type": "SPECIAL_INTEREST_ENTITY"
      }
    ]
  }
}

Field name	Description
payload	Top-level object that contains all properties
caseId	A UUID that is assigned to transaction
customerId	A customer id, could generated UUID if was not provided in request
processingStatus	Result of processing case, one of: Initial states: - new ... indicates a new open/suspicious case -unsuspicious...indicates a case is "not opened" so the settings done in case managers configuration section prevent this case from opening. - relieved ... indicates a initially suspicious case relieved/auto-closed by system Workflow states: - operator-review ... indicates when an operator assigns a case to him-/herself. Typically following processStatus=new - accepted ... indicates a case being closed/accepted by an operator (=final state). This means the Customer is acceptable from a business perspective and should be boarded. Typically following processingStatus=operator-review (or escalated) - declined... indicates a case being declined by an operator (=final state). This means the Customer is not acceptable from a business perspective and should not be boarded. Typically following processingStatus=operator-review (or escalated) - escalated ... indicates a case being escalated into second level. Typically following processingStatus=operator-review -manual-risk-changed...indicates the risk level of a customer case was manually changed by an operator in the system
customerStatus	Indicates customer status, one of: - proceeded - blocked
screeningResultConfirmed	Contains screening types which had been confirmed by operator by selecting MATCH under screening hit This value is provided for callbacks of accept or decline operator actions on a case
riskLevel	Contains new risk level set for customerId by using manual risk level change This value is provided only for callback of manual risk level change action
assignedTo	Indicates the email address of the current assignee of the customer case. Can be null if no one is assigned

Example Use Case

The webhook is used to present the gateways callbacks functionality. Webhook simulates the server and presents all the API responses triggered by operator actions or events in the gateway.
Bank transfer with recipient from sanction list is used in the example use case to present how operator and the gateway solution actions generate API responses and use callback feature to inform the server about the case update.

Scenario introduction

Step id	Action	Result
1	Bank transfer details with recipient from a sanction list is sent via the API.	Two API call responses are registered in webhook New case is opened in the Case manager
2	Operator assigns the case to himself	API call response is registered in webhook
3	Operator selects "no match" for each rule break and accepts the changes	API call response is registered in webhook Case status is changed

Scenario detailed description

Open webhook, copy "Your unique URL" and put it in the callbackUrlfield of the request body.

{
"tenantProcessingTimestamp": "2022-02-22T15:21:43.000Z",
"tenantTransactionId": "c45d38a6-2384-49aa-98ab-60134a50a5d7",
"accountHoldingParty": "FUNDS_ORIGINATOR",
"callbackUrl": "<PUT YOUR UNIQUE URL HERE>",
"fundsOriginator": {
"accountNumber": "DE35544587001715587710",
"holder": "Mario Meischberger",
"scheme": "SEPA"
},
"fundsBeneficiary": {
"accountNumber": "DE19247028103332102880",
"holder": "Nicolás Maduro",
"scheme": "SEPA"
},
"settledAmount": 350,
"settledCurrency": "EUR",
"usage": "Vielen Dank",
"paymentMeans": "TRANSFER",
"channel": "ONLINE_BANKING"
}

Try it out here

Open Test Scenario Tool, insert json request body into the test scenario API request.

Click on "New IBAN/Timestamp" to generate unique tenantProcessingTimestamp and accountNumber
Click on "RUN ON TEST" to make an API call.

API response with proceed:false should be generated.

New case is opened in the Case Manager, transaction is blocked.

Two API call responces are generated and can be found in the webhook.

{
"payload": {
"caseId": "a7b6549d-838d-4faa-bd54-2e1deb6e568c",
"tenantTransactionId": "c45d38a6-2384-49aa-98ab-60134a50a5d7",
"transactionStatus": "blocked",
"processingStatus": "new",
"decisionType": "immediate"
}
}

{
"payload": {
"caseId": "a7b6549d-838d-4faa-bd54-2e1deb6e568c",
"tenantTransactionId": "c45d38a6-2384-49aa-98ab-60134a50a5d7",
"transactionStatus": "blocked",
"processingStatus": "new",
"decisionType": "complete"
}
}

Operator assigns the case to himself.
API call responce is generated and can be found in the webhook.

{
"payload": {
"caseId": "a7b6549d-838d-4faa-bd54-2e1deb6e568c",
"tenantTransactionId": "c45d38a6-2384-49aa-98ab-60134a50a5d7",
"transactionStatus": "blocked",
"processingStatus": "operator-review",
"decisionType": "complete"
}
}

Operator selects "NO MATCH" for each rule break and accepts the change.
API call responce is generated and can be found in the webhook.

{
"payload": {
"caseId": "a7b6549d-838d-4faa-bd54-2e1deb6e568c",
"tenantTransactionId": "c45d38a6-2384-49aa-98ab-60134a50a5d7",
"transactionStatus": "unblocked",
"processingStatus": "accepted",
"decisionType": "complete"
}
}

Case status in the Case Manager is changed to Closed.
Processing status in the Case manager is changed to Accepted.
Transaction is unlocked.

Important

The previous version of the Transaction Checks API, AML Checks, has been deprecated. This change has no impact on existing integrations which will continue to be supported.