Your APIs for us - Notifications

We can send following information to your API endpoints:

3DS OTP code, so you can handle delivery to the user yourself via SMS, Push or other channel.
Notifications about outcome of KYC process.
Notifications about card locks/unlocks.
Simple notification about transactions.

To make this work, you need to expose an API according to relevant section of this documentation.

Security

To set secured server-server connection between our services Verestro requires a similar connection as in the case of client to Verestro communication based on the x509 certificate.
In the first step, Verestro will send to the client a CSR for the dev and production environments.
The next step is for the client to sign the CSR and send the certificate back to Verestro along with the base URL for the methods listed below. Verestro will authorize itself with each request with a certificate, which should be checked on the client side.

Idempotency Key

With some requests additional header X-Idempotency-Key could be send. This header contain unique random id allowing to identify single request.
If client send this header, operation should be triggered only once and for any further request with this key, response should be identical - in most cases, returned from cache.

example headers:

X-Idempotency-Key: 20e87975-dbfb-4c95-b239-169516c0b707

3DS External OTP Notifier

This document describes API for external OTP notifier handling. Clients that are interested into having OTP notifier on their side must have implement this API to allow communication with Antaca to provide one time password about the transaction to client own users.

API 3DS External OTP Notifier

Below you will find a list of endpoints that you should implement on your server side. Please pay special attention to the appropriate security of our connection, the syntax of requests that you can expect from the Verestro side, idempotency and the exact way in which you should respond to each request.

These notifications support sending Idempotency Key

Notification OTP

This method is used to transfer a one-time password generated for transactions without a card present in the 3DS standard.

POST https://server-domain.com/notifications/otp

Headers:

Content-Type: application/json
X-Idempotency-Key: 20e87975-dbfb-4c95-b239-169516c0b707

request body:

{
    "storageCustomerId" => "1337",
    "storageCardId" => "1337",
    "balanceId" => "b334b384-328c-11ed-a261-0242ac120002",
    "amount" => "1000",
    "currency" => "PLN",
    "merchantName" => "merchant test",
    "otp" => "1111"
}

Parameters:

Parameter	Required	Description	Type
storageCustomerId	TRUE	Customer identifier	integer value
storageCardId	TRUE	Card identifier	integer value
balanceId	TRUE	User balance identifier	uuid v4
amount	TRUE	Transaction value in gross (minor value)	integer value
currency	TRUE	Currency 3-letters code in ISO 4217 https://www.iban.com/currency-codes	ISO 4217 3-letter code
merchantName	TRUE	Merchant name	string value
otp	TRUE	One time password	string value

success response:

204 No Content

error responses:

If an error is received, it is not possible to retry the request.

Code 422
{
    "detail": "some specific details provided by server"
}

External Verification Notifier

This document describes API for processed KYC verification notifier handling. Clients that are interested into having information about status KYC verification on their side must have implement this API to allow communication with Antaca.

Notifier provide notifications only with internal KYC status processes

These notifications support sending Idempotency Key

Notification verification In-progress

This method is used to transfer information about changed KYC verification status to 'IN_PROGRESS'.

POST https://server-domain.com/notifications/verificationInProgress

Headers:

Content-Type: application/json
X-Idempotency-Key: 20e87975-dbfb-4c95-b239-169516c0b707

request body:

{
  	"verificationId": "6faaa45a-41f6-4922-95fe-16e316ba7e91", 
    "userId": "1337",
	"email": "leonbakiewicz@gmail.com",  
    "firstName": "Leon",
    "lastName": "Bakiewicz",
    "status": "IN_PROGRESS",
  	"reason": null,
}

response:

204 No Content

Notification verification accepted

This method is used to transfer information about changed KYC verification status to 'ACCEPTED'.

POST https://server-domain.com/notifications/verificationAccepted

Headers:

Content-Type: application/json
X-Idempotency-Key: 20e87975-dbfb-4c95-b239-169516c0b707

request body:

{
  	"verificationId": "6faaa45a-41f6-4922-95fe-16e316ba7e91", 
    "userId": "1337",
	"email": "leonbakiewicz@gmail.com",  
    "firstName": "Leon",
    "lastName": "Bakiewicz",
    "status": "ACCEPTED",
  	"reason": null,
}

response:

204 No Content

Notification verification rejected

This method is used to transfer information about changed KYC verification status to 'REJECTED'.

POST https://server-domain.com/notifications/verificationRejected

Headers:

Content-Type: application/json
X-Idempotency-Key: 20e87975-dbfb-4c95-b239-169516c0b707

request body:

{
  	"verificationId": "6faaa45a-41f6-4922-95fe-16e316ba7e91", 
    "userId": "1337",
	"email": "leonbakiewicz@gmail.com",  
    "firstName": "Leon",
    "lastName": "Bakiewicz",
    "status": "REJECTED",
  	"reason": 'INVALID_CUSTOMER_DATA',
}

response:

204 No Content

Parameters:

Parameter	Required	Description	Type
verificationId	TRUE	Verification identifier	uuid v4
userId	TRUE	User identifier	integer value
email	TRUE	User's email address	string value
firstName	TRUE	User first name	string value
lastName	TRUE	User last name	string value
status	TRUE	Verification status. Possible values: REJECTED IN_PROGRESS ACCEPTED	string value
reason	TRUE	Verification status reason ACCEPTED: null IN_PROGRESS: null REJECTED: INVALID_CUSTOMER_DATA BLURRED_DOCUMENT_PHOTO INVALID_DOCUMENT_PHOTO BLURRED_SELFIE INVALID_SELFIE	null/string value

Sensitive data:

This method is used to share your public key for encryption.

GET https://server-domain.com/public-key

response:

200 OK
{
  "publicKey": "QSBwdWJsaWMga2V5IHNob3VsZCBiZSBoZXJlIGhvd2V2ZXIgaXQgd2FzIHRvbyBsb25nIDoo"
}

External Card Block Notifier

This document describes an external API for communicating card blocks, which requires client-side implementation for clients wishing to receive these notifications.

API External Card Notifier for Locks

This method is used to transfer information about a card's blocking status and the reason for it.

POST https://server-domain.com/notifications/cardLocked

Headers:

Content-Type: application/json

Request body:

{
  "dcCardId": "11",
  "date": "2025-06-17T13:42:54+00:00",
  "reason": "PIN_TRIES_EXCEEDED"
}

Parameters:

Parameter

Required

Description

Type

dcCardId

TRUE

Card identifier

integer value

date

TRUE

Timestamp of lock

datetime

reason

TRUE

Reason of lock

string value,

possible values:

CARD_LOST

CARD_STOLEN

PENDING_QUERY

CARD_CONSOLIDATION

CARD_INACTIVE

PIN_TRIES_EXCEEDED

SUSPECTED_FRAUD

CARD_REPLACED

Success response:

204 No Content

API External Card Notifier for Unlocks

This method is used to transfer information about that card is unlocked.

POST https://server-domain.com/notifications/cardUnlocked

Headers:

Content-Type: application/json

Request body:

{
  "dcCardId": "11",
  "date": "2025-06-17T13:42:54+00:00",
}

Parameters:

Parameter	Required	Description	Type
dcCardId	TRUE	Card identifier	integer value
date	TRUE	Timestamp of unlock	datetime

Success response:

204 No Content

External Transactional Lock Reason Notifier

This document describes an external API for communicating transactional lock reason actions, which requires client-side implementation for clients wishing to receive these notifications.

API External Transactional Lock Reason Added

This method is used to transfer information about that transactional lock reason is added.

POST https://server-domain.com/notifications/transactionalLockReasonAdded

Headers:

Content-Type: application/json
X-Idempotency-Key: 20e87975-dbfb-4c95-b239-169516c0b707

Request body:

{
  "resourceType": "corporation",
  "resourceId": "a3f33118-946d-4b9c-b27f-e009d28355fa",
  "lockReason": "FRAUD_SUSPECTED",
  "timestamp": "2025-06-17T13:42:54+00:00",
}

Parameters:

Parameter	Required	Description	Type
resourceType	TRUE	Type of resource	string value: - corporation - user
resourceId	TRUE	Id of resource	numeric string or uuid
lockReason	TRUE	Reason of lock	string value: - DOCUMENT_EXPIRED - FRAUD_SUSPECTED
timestamp	TRUE	Datetime of add/remove lock reason	datetime

Success response:

204 No Content

API External Transactional Lock Reason Removed

This method is used to transfer information about that transactional lock reason is removed.

POST https://server-domain.com/notifications/transactionalLockReasonRemoved

Headers:

Content-Type: application/json
X-Idempotency-Key: 20e87975-dbfb-4c95-b239-169516c0b707

Request body:

{
  "resourceType": "corporation",
  "resourceId": "a3f33118-946d-4b9c-b27f-e009d28355fa",
  "lockReason": "FRAUD_SUSPECTED",
  "timestamp": "2025-06-17T13:42:54+00:00",
}

Parameters:

Parameter	Required	Description	Type
resourceType	TRUE	Type of resource	string value: - corporation - user
resourceId	TRUE	Id of resource	numeric string or uuid
lockReason	TRUE	Reason of lock	string value: - DOCUMENT_EXPIRED - FRAUD_SUSPECTED
timestamp	TRUE	Datetime of add/remove lock reason	datetime

Success response:

204 No Content

Transactions notifier

To get notifications about transactions use Transaction History Core API