# Legacy Transactions Notifier

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 TRUEStatus 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 TRUEDate time of request generation in ISO 8601 date ISO 8601 date, eg. 2023-11-16T13:41:40+00:00
description TRUEDescribes more details for returned status describes in **description section details**
transaction TRUE The transaction properties transaction object described in **the** **transaction object** section
**Description details:**
**Value** **Description**
APPROVEDIndicates a successful transaction. Antaca processed the transaction with no errors.
EXCEEDS\_AMOUNT\_LIMITOccurs when the transaction amount exceeds card limits.
INSUFFICIENT\_FUNDSThere is not enough money on balance.
CARD\_NOT\_FOUNDAntaca cannot find card for which the transaction was invoked.
BALANCE\_NOT\_FOUNDAntaca cannot find balance for which the transaction was invoked.
INVALID\_AMOUNTAmount of the transaction was passed as <= 0.
INSUFFICIENT\_FUNDS\_ON\_DEPOSIT\_BALANCEDeposit balance has not enough funds to process the transaction.
DEPOSIT\_BALANCE\_NOT\_FOUNDOccurs when client has not configured deposit balance in currency used for rejected the transaction.
AML\_EXCEPTIONAML regulations does not allow to process the transaction.
AMBIGUOUS\_REFERENCED\_TRANSACTIONAntaca 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\_FOUNDSystem cannot find any transaction for which the request refer.
CURRENCY\_MISMATCHThe transaction currency is different than balance currency.
CUSTOMER\_NOT\_FOUNDSystem cannot find customer who is involved in the transaction.
BUDGET\_EXCEEDEDThe budget limitation for an card or an customer has been exceeded.
LIMIT\_EXCEEDGeneral limitation for the transaction has been exceeded.
COLLATERAL\_BALANCE\_NOT\_FOUNDSystem 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\_BALANCEAn collateral balance has not enough funds to process transaction request.
UNKNOWN\_TRANSACTION\_TYPESystem cannot determine kind of the transaction and reject it for security reason.
UNKNOWN\_ERRORGeneral error. System cannot match any of concrete description.
**Transaction object:**
**Name** **Required** **Description** **Allowed** **values**
idTRUE Unique identifier of the transaction in UUID format. any value in UUID v4 format, eg. ddb55ff9-11ca-4621-9129-81f939e66011
balanceIdTRUEThe 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
resourceIdTRUEIdentifier of resource used to process transaction. This is always in uuid format.any value in uuid v4 format, eg. 846edf0f-9a96-4f1d-bc38-9c963605b9e8
resourceTRUEName 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
cardIdTRUEThe 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.
externalTransactionIdTRUEThis 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
referenceExternalTransactionIdFALSEThis 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
typeTRUEType 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
categoryTRUECategory of the transaction used for identification of funds movement.CREDIT, DEBIT
amountTRUEAmount of the transaction. This is always integer in minor value.any integer value greater than 0.
currencyFALSECurrency of transaction in ISO 4217 3-letter code.any ISO 4217 3 letter code eg. PLN, USD, EUR
originalAmountFALSEAmount of the original transaction in integer minor value.any integer value greater than 0. Also this field could has null value
originalCurrencyFALSECurrency 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
statusTRUECurrent status of the transaction (after Antaca service process).AUTHORIZED, CLEARED,
descriptionTRUEDetailed description of the transaction.any string value
dateTRUEDate of the transaction in ISO 8601 date.any data specified by iso 8601. Eg. 2023-11-17T11:32:18+00:00
referenceExternalTransactionDateFALSEDate 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
transactionDataTRUEThe transaction data object described in **the** **transaction data section.**Keep in mind that this object is always passed but it can be empty.
**Transaction data object**
**Name** **Required** **Description** **Allowed** **values**
mccFALSEMerchant 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)
merchantIdentifierFALSEThe merchant identifier for the transaction.
merchantNameFALSEName of the merchant.
captureModeFALSECapture mode.magstripe, manual, emv, on behalf (EMV), nfc, ecommerce, adj
lastFourDigitsFALSElast 4 digits of a card.
acquirerCountryFALSECountry of acquirer.ISO 3166-1 alpha-3 code
mdesDigitizedWalletIdFALSEThe Wallet ID (Wallet Reference) used to digitize the card.m4m, google pay, samsung pay, apple pay
cashbackPosCurrencyCodeFALSERepresents the currency code of the cashback amount.ISO 4217 3-letter code
cashbackPosAmountFALSEDisplays the actual cashback amount.integer value in gross
##### Response Only responses with http code 200 & 204 are allowed. ``` 200 OK 204 NoContent ``` In case of any other response code, Antaca will try to send a request once again (up to 5 times). Every time a request will be identical with the same **X-idempotency-key.** Keep in mind that if your service has answered properly, network errors can arise either way. If Antaca resends the request with the same X-Idempotency-Key, the response should be retrieved from the cache. ##### Transaction Types Description Debit transactions list:
**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 InquiryCheck 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.
Credit transactions list:
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