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

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.

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

Header

Content-Type: application/json
X-Idempotency-Key: 51ec546d-049a-4b8f-a05e-933938656eb2

Request body

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

Description details:

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.

Transaction object:

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.

Transaction data object

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

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 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.

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