# 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](https://developer.verestro.com/books/card-management-system/page/your-apis-for-us#bkmrk-jwe-configuration)**
##### 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:**
**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](https://developer.verestro.com/books/card-management-system/page/your-apis-for-us#bkmrk-jwe-configuration)**
##### 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:**
```JSON
{
"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:**
```JSON
{
"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:**
```JSON
{
"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:**
**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:**
**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:**
**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:**
**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:**
**Success response:**
```
204 No Content
```
### Transactions notifier
To get notifications about transactions use [Transaction History Core API](https://developer.verestro.com/books/transaction-history-api/page/technical-documentation-thc-external-api)