Callbacks

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

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"
}
}

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)

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"
      }
    ]
  }
}

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

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"
}

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.