This document describes an API, that was deprecated and exists only to support legacy integrations. If you're working on new integration **do not use** this API. Use **[Transaction History Core API](https://developer.verestro.com/books/transaction-history-api/page/technical-documentation-thc-external-api)** instead.
This document describes API for external transaction event notifications. Client who is interested in receiving notification about any transaction that occur in system, must implement below API.These notifications support sending [**Idempotency Key**](https://developer.verestro.com/books/card-management-system/page/your-apis-for-us#bkmrk-jwe-configuration)
#### Security Security for this endpoint is described in **The** **Security** section in the beginning of this page. #### Api For obtaining transaction event notification the Antaca is using single endpoint. ```HTML POST https://server-domain.com/notifications/transaction ``` ##### Header ``` Content-Type: application/json X-Idempotency-Key: 51ec546d-049a-4b8f-a05e-933938656eb2 ``` ##### ##### Request body ```YAML { "status": "SUCCESS", "date": "2023-11-17T11:32:16+00:00", "description": "APPROVED", "transaction": { "id": "b4f534ef-77c2-4f16-ab4d-496806a76fb6", "balanceId": "60036f20-3b2c-470e-b9de-3c6cfbe8a5ff", "resourceId": "b3de5060-2ae2-4f3c-9b94-9c27a90dc6fe", "resource": "card", "cardId": "357970", "externalTransactionId": "d275ecb8-138e-4d0e-b5bf-c4158b4ce516", "referenceExternalTransactionId": null, "type": "POS", "category": "DEBIT", "amount": 10000, "currency": "PLN", "originalAmount": 12300, "originalCurrency": "PLN", "status": "AUTHORIZED", "description": "FrogShop Lublin POL", "date": "2023-11-17T11:32:16+00:00", "referenceExternalTransactionDate": null, "transactionData": { "mcc": "5122", "merchantIdentifier": "12345", "captureMode": "NFC", "lastFourDigits": "0911", "acquirerCountry": "POL" } } } ``` **Parameters:**| **Name** | **Required** | **Description** | **Allowed values** |
| status | TRUE | Status of the transaction processing. **SUCCESS** - indicates that the transaction has been successfully processed in Antaca. **DECLINED** - indicates that the transaction has been declined. **INVALID -** indicates that the transaction can't be processed. | SUCCESS, DECLINED, INVALID |
| date | TRUE | Date time of request generation in ISO 8601 date | ISO 8601 date, eg. 2023-11-16T13:41:40+00:00 |
| description | TRUE | Describes more details for returned status | describes in **description section details** |
| transaction | TRUE | The transaction properties | transaction object described in **the** **transaction object** section |
| **Value** | **Description** |
| APPROVED | Indicates a successful transaction. Antaca processed the transaction with no errors. |
| EXCEEDS\_AMOUNT\_LIMIT | Occurs when the transaction amount exceeds card limits. |
| INSUFFICIENT\_FUNDS | There is not enough money on balance. |
| CARD\_NOT\_FOUND | Antaca cannot find card for which the transaction was invoked. |
| BALANCE\_NOT\_FOUND | Antaca cannot find balance for which the transaction was invoked. |
| INVALID\_AMOUNT | Amount of the transaction was passed as <= 0. |
| INSUFFICIENT\_FUNDS\_ON\_DEPOSIT\_BALANCE | Deposit balance has not enough funds to process the transaction. |
| DEPOSIT\_BALANCE\_NOT\_FOUND | Occurs when client has not configured deposit balance in currency used for rejected the transaction. |
| AML\_EXCEPTION | AML regulations does not allow to process the transaction. |
| AMBIGUOUS\_REFERENCED\_TRANSACTION | Antaca cannot determine for which a transaction refer current the transaction request. System has found more then one transaction matched by transaction parameters. |
| REFERENCED\_TRANSACTION\_NOT\_FOUND | System cannot find any transaction for which the request refer. |
| CURRENCY\_MISMATCH | The transaction currency is different than balance currency. |
| CUSTOMER\_NOT\_FOUND | System cannot find customer who is involved in the transaction. |
| BUDGET\_EXCEEDED | The budget limitation for an card or an customer has been exceeded. |
| LIMIT\_EXCEED | General limitation for the transaction has been exceeded. |
| COLLATERAL\_BALANCE\_NOT\_FOUND | System cannot find an collateral balance in proper currency configured for client instance. Those balances could be eg. deposit, credit, technical etc. |
| INSUFFICIENT\_FUNDS\_ON\_COLLATERAL\_BALANCE | An collateral balance has not enough funds to process transaction request. |
| UNKNOWN\_TRANSACTION\_TYPE | System cannot determine kind of the transaction and reject it for security reason. |
| UNKNOWN\_ERROR | General error. System cannot match any of concrete description. |
| **Name** | **Required** | **Description** | **Allowed** **values** |
| id | TRUE | Unique identifier of the transaction in UUID format. | any value in UUID v4 format, eg. ddb55ff9-11ca-4621-9129-81f939e66011 |
| balanceId | TRUE | The balance identifier in UUID format. This could refere to a customer or any of collateral balance. | any value in uuid v4 format, eg. 6bb3745f-1ddf-4579-855f-913c3f272d19 |
| resourceId | TRUE | Identifier of resource used to process transaction. This is always in uuid format. | any value in uuid v4 format, eg. 846edf0f-9a96-4f1d-bc38-9c963605b9e8 |
| resource | TRUE | Name of resource used to process transaction. This could be eg. card, balance, creditBalance, depositBalance etc. This list could change in future so please do not hardcode this value. | card, balance, creditBalance, debitBalance |
| cardId | TRUE | The card identifier in string format. This value could be used to communicate with the Antaca services. | any string value. Mostly it should be eg. "1234" but it can change in the future and become UUID format. |
| externalTransactionId | TRUE | This is transaction identifier obtained from the transaction processor. This value is not unique and can be duplicated over time. The Antaca is not responsible for this value. | any string value |
| referenceExternalTransactionId | FALSE | This is similar like externalTransactionId except it refers to previously obtained a transaction. This value is not unique and can be duplicated over time. Antaca is not responsible for this value. | any string value |
| type | TRUE | Type of transaction. | This list could evolve over time so please check this documentation from time to time. POS, ATM, Cashback, AFT, Balance Inquiry, Payment, commission, fee, funding, interest, withdrawal, collateralDebit, companyDebit, ibanTechnicalDebit, cashback, creditIbanTransfer, loan, payment, topUp, collateralCredit, companyCredit, ibanTechnicalCredit |
| category | TRUE | Category of the transaction used for identification of funds movement. | CREDIT, DEBIT |
| amount | TRUE | Amount of the transaction. This is always integer in minor value. | any integer value greater than 0. |
| currency | FALSE | Currency of transaction in ISO 4217 3-letter code. | any ISO 4217 3 letter code eg. PLN, USD, EUR |
| originalAmount | FALSE | Amount of the original transaction in integer minor value. | any integer value greater than 0. Also this field could has null value |
| originalCurrency | FALSE | Currency of the original transaction in ISO 4217 3-letter code. | any ISO 4217 3 letter code eg. PLN, USD, EUR. Also this field could has null value |
| status | TRUE | Current status of the transaction (after Antaca service process). | AUTHORIZED, CLEARED, |
| description | TRUE | Detailed description of the transaction. | any string value |
| date | TRUE | Date of the transaction in ISO 8601 date. | any data specified by iso 8601. Eg. 2023-11-17T11:32:18+00:00 |
| referenceExternalTransactionDate | FALSE | Date of the transaction for which this transaction is refer to. Date in ISO 8601 date. | any data specified by ISO 8601. Eg. 2023-11-17T11:32:18+00:00 |
| transactionData | TRUE | The transaction data object described in **the** **transaction data section.** | Keep in mind that this object is always passed but it can be empty. |
| **Name** | **Required** | **Description** | **Allowed** **values** |
| mcc | FALSE | Merchant category code. | any mcc value, eg. can be found here: [https://global.alipay.com/docs/ac/files/mcclist](https://global.alipay.com/docs/ac/files/mcclist) |
| merchantIdentifier | FALSE | The merchant identifier for the transaction. | |
| merchantName | FALSE | Name of the merchant. | |
| captureMode | FALSE | Capture mode. | magstripe, manual, emv, on behalf (EMV), nfc, ecommerce, adj |
| lastFourDigits | FALSE | last 4 digits of a card. | |
| acquirerCountry | FALSE | Country of acquirer. | ISO 3166-1 alpha-3 code |
| mdesDigitizedWalletId | FALSE | The Wallet ID (Wallet Reference) used to digitize the card. | m4m, google pay, samsung pay, apple pay |
| cashbackPosCurrencyCode | FALSE | Represents the currency code of the cashback amount. | ISO 4217 3-letter code |
| cashbackPosAmount | FALSE | Displays the actual cashback amount. | integer value in gross |
| **Type** | **Description** |
| POS | POS transaction (A point-of-sale) applies to the situation when a customer makes a purchase and the payment is processed through the POS system. |
| ATM | ATM Transaction is when the cardholder uses a physical card at an ATM to withdraw cash. |
| Balance Inquiry | Check the available balance of funds. |
| CollateralDebit | internal transaction dedicated only for bin-sponsor (via PA) or internal Verestro APIs (via specific CN) to top up the credit/debit partner balance. Antaca automatically **debits** the **credit partner balance** with: - internal **cashback, loan, payment, top-up** transactions that were credits the user balance. Antaca automatically **debits** the **deposit partner balance** with: - any authorized **debit** transaction from the card network transactions except **FX** transactions |
| Commission | internal transaction for a partner who wants to debit user balance as a commission referenced to the other transaction. |
| CompanyDebit | internal transaction dedicated only for bin-sponsor (via PA) or internal Verestro APIs (via specific CN) to debit company balance used for settlements between the partner and the bin-sponsor. Antaca automatically **debits** company balance with: - **FX** transactions generated by the processor - **interchange** obtained from MC during settlement |
| Fee | internal transaction for a partner who wants to debit user balance as a fee. Antaca automatically **credits** company balance with the funds that were debit the user's balance |
| Funding | internal transaction type used to debit the user's balance. This type indicates that the funds still remain in the Antaca system, usually in conjunction with a payment type a credit transaction on the user's balance. Antaca automatically **credit** the **credit partner balance** with this transaction |
| IbanTechnicalDebit | internal transaction dedicated only for IMS API (via specific CN). IMS API uses this balance to account funds that could not be related to the user's balance |
| Interest | internal transaction for a partner who wants debit the user's balance as part of the interest connected with credit agreement. |
| Withdrawal | internal transaction type used to debit the user's balance. This type indicates that the funds go outside the Antaca system, fe: withdrawal from an account at a bank branch. |
| TopUp | internal transaction type used to top up the user's balance. This type indicates that the funds come from outside the Antaca system, fe: payment to an account at a bank branch. Antaca automatically **debit** the **credit partner balance** with this transaction |
| Payment | internal transaction type used to top up the user's balance. This type indicates that the funds come from the Antaca system, usually in conjunction with a funding type a debit transaction on the user's balance Antaca automatically **debit** the **credit partner balance** with this transaction |
| Loan | internal transaction for a partner who wants to top up the user's balance as part of the credit agreement. Antaca automatically **debit** the **credit partner balance** with this transaction |
| IbanTechnicalCredit | internal transaction dedicated only for IMS API (via specific CN). IMS API uses this balance to account funds that could not be related to the user's balance |
| CreditIbanTransfer | internal transaction dedicated only for IMS API (via specific CN). IMS API uses this balance to credit funds on the user's balance. |
| CompanyCredit | internal transaction dedicated only for bin-sponsor (via PA) or internal Verestro APIs (via specific CN) to top up company balance used for settlements between the partner and the bin-sponsor. Antaca automatically **credits** company balance with: - **FX** transactions generated by the processor - **fee** transactions that were charged from user balance - **interchange** obtained from MC during settlement |
| CollateralCredit | internal transaction dedicated only for bin-sponsor (via PA) or internal Verestro APIs (via specific CN) to top up the credit/debit partner balance. Antaca automatically **credits** the **credit partner balance** with: - internal **funding** transaction that were charged from user balance. Antaca automatically **credits** the **deposit partner balance** with: - the **force credit** from the card network transactions except **FX** transactions |
| Cashback | internal transaction for a partner who wants to top up the user's balance as part of the loyalty program Antaca automatically **debit** the **credit partner balance** with this transaction |