# Your APIs for us 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. - Notification about outcome of KYC process. - Transaction request, so you can keep users balance on your end and accept or reject transactions their transactions (we call this "External Balance"). - Simple notification about transactions. To make this work, you need to expose an API according to relevant section of this documentation.
To use external balance you must have Banking License or Payment Institution License. Additionally if you don't directly own BIN range, total sum of transactions of your users will be limited by deposit called "Master Balance".
### 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, more about this model [here](https://developer.verestro.com/books/connecting-to-our-services/page/connecting-to-server-to-server-apis). In the first step, Verestro will send to the client a CSR for the dev and production environments, more details [here](https://developer.verestro.com/books/connecting-to-our-services/page/exposing-apis-for-us). 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. ### Additional data encryption & integration Some requests and responses contain sensitive data, to additionally secure the connection we require JSON Web Encryption (JWE).normal | encrypted | |||
---|---|---|---|---|
Example of request with sensitive data |
|
| ||
Example ofresponse with sensitive data |
|
|
Correct request | Sent request (incorrect) | Received by CMS Antaca (after decipher action with private key) |
---|---|---|
``` {"card_no" : 1337} ``` | {"payload" : "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0.rdUrW12XCZQgLFDJ-2zAHWYYnaAanctceE1-Y6yJUplX0B2dLu-bvYOEJ83KxxUs-ZjA41R4PmAVilx1cTF4pv-7CZR0\_ki85XRATBYF2-MvZdcC81fHy2QPU\_ZsAEWAW00a1wKJmuEsgPB2m1aLZ7oK4fC1hciep4PyAtuWQRYHjhNb-UDT41\_gDKTbnSGTwheL7S0mAJ\_HsKfnZFHYUrM77UcxQGZKnH7Mzqvndf9THiMo0-3MWliYFDAm1bqN2\_KTIoBNCprYjFnyIXPCjib73bjWX\_P2ip5Ul84cngbQmFVzc7o91JrpJvYou1INS7zL4XKLFcADN4nZ\_9ePWsm5\_kX5SOMyUyEhOC9gusrLNAJ0MHaIFHni8WqnMAWM3\_MC4OQDYetKax5bnHK6x42\_5eFaf6ZmzmioKny5aGm-4Vo8TEu691FmPxglhyenWlMhvBvf6ZeVsy58Ofr0mi3TXjwYbAyas7m6sncxZu1FhEJ4da6gtNjmjuKdikOOntu8V71QQ07nczNqfGlUv0RcUc9uKJq5je4b9BEbK9WuQcroxmALqC4HTt1xhICHrVUA0d\_t3fglhS2n7wNaKKCFq70ZWIrpdTaBd35kdVQOEjZgCavSjbZOzgOzcEqS6P2Blm7bZ7ZZBmnfk8y8M4m0xWoQNTmLC6nqz9bSbME.UEryKNClDxQZpyWu.6Lw\_5CcZ9HiVxHfi\_XTAFw.pYbQ6tdmQYe1kiPonm1GhA"} | ``` {"card_no" : 1337} ``` |
Correct response | Sent response by CMS Antaca | Received by you |
---|---|---|
``` {"card_no" : 1338} ``` | {"payload" : "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0.iPmvEKtMAMrrEiR89vlwsL77ZfqxXrcMiy-bx3z6\_7HAo\_\_aQzBpMVDtLyj3kTHYWxen8bhPuVyebXyaIHL20sekFzcIFFzvaGoyQYU6zOK8tPv81tgixQe8SDnEr5v9VWBfiHxtPvqlpQIig2is5ynBkyqjdpQWEagR3MpqpATGl7f-omG82Jq0OwZByWI8I6P89hczwgK37F-MUnQDxcRUM3RagbHKNeIcfmPdJpNeqFZHe45y4wUkTWN0uzW72qydkN\_4uM9fy0nrUpgsJNbtJGAVIUVmDz4pIZkiI1zyGbfZX-PT7Wh9UNM06gEUf4i2goZY-m4wPB0n2zXvxzcEdfTH27iPp-aKiJjfJpYb\_ZnHyklk\_\_gZlAy9r7W0594dY-eBJ\_iUa5aeDsFS2TIfsfjMJsL8NRWY2noiTw5lsneD8dwvr6N\_rYcWoFXDyWXHoRitSSd2iYrB80gbeSOBW0wfKtPxNIZrR0uDhkE8FouS5Pk7QBw412kd43GtrEpAijqn3ne7MNUpCtuNfJ8e\_NdGDLTR7CSHhC0jfFlchpIvklF42o216NO-OnyJsjdv1w4\_w1ugs61fTHDl8lgBalOjOxauKwIvJJOyFdWmpjlXuzJhrray7ov25uh2ibvFv3Gfd2iuGUnLIZzYBOTT8ftGWTCGXTDvVOvzGbs.c3qMNb2Bne-7g0Wz.PInghFM6Q8Gn0p4Tlebig32s-ZrpLqTMqQDlpXLLYx0iq-StrKco\_HrjdN4MxondP4CicCgseIjcV8JR29jKYX-nqKdchEYq\_vVIzFHcNI\_Mx7y1el192QbMyx6b0Gbj5L79wpuB7qCUqTBNhJZ2c07PuyPsewcNwglvnc-OrA-2vL6lJnBi5ZGH8gBH1cZCgmbrMpZGNFPG3oFpOn9JPzmnvQxe9tvSFFj5989A8d\_XMHP-ZQ.dJZxnBRxJeMKswDsCA3cXA"} | Check yourself by using Private Key included in the response. |
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.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](https://www.iban.com/currency-codes) | ISO 4217 3-letter code |
merchantName | TRUE | Merchant name | string value |
otp | TRUE | One time password | string value |
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'.Parameter | Required | Description | Type |
---|---|---|---|
verificationId | TRUE | Verification identifier | uuid v4 |
userId | TRUE | User identifier | integer value |
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 |
**Remember to avoid billing problems** Deleting a balance is only possible when its status is 0. This also applies to situations in which a user with at least one balance is deleted.
##### Transaction processing**Remember to avoid communication errors** Verestro servers attach an X-Idempotency-Key to each request in the header. This header contains a unique ID for each request to ensure idempotence. Each request with a unique identifier in this header should be processed only once on the client side and the response to it should be identical - in most cases, returned from cache
Parameter | 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 | Unique user balance identifier | any string value (recommended uuid v4) |
resourceId | TRUE | Unique resource identifier | any string value (recommended uuid v4) |
resource | TRUE | Name of a resource. | balance, card |
transactionId | TRUE | Transaction identifier obtained from card netwok or generated on client side using the method to generate transaction in Antaca. **IMPORTANT: this id may not be unique - it is generated by different systems** | any string value (recommended uuid v4) |
referenceTransactionId | FALSE | Id of previous transaction to witch current request relates | any string value (recommended uuid v4) |
type | TRUE | Type of transaction | cashback, loan, payment, topup, commision, fee, funding, interest, withdrawal, POS, ATM, Cashback at POS |
amount | TRUE | Transaction value in gross (minor value) | integer value |
currency | TRUE | Currency 3-letters code in ISO 4217 | ISO 4217 3-letter code |
originalAmount | FALSE | Original transaction value in gross (minor value) | integer value |
originalCurrency | FALSE | Original currency 3-letters code in ISO 4217 | ISO 4217 3-letter code |
status | TRUE | Transaction status | AUTHORIZED, CLEARED, REVERSED |
descripion | TRUE | Transaction description | any string value |
date | TRUE | Date of transaction in UTC | date in UTC |
transactionData | FALSE | Additional transaction data. This object presents detailed data depending on the transaction type | This object is described below |
Parameter | 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 merchant | |
captureMode | FALSE | Capture mode | magstripe, manual, emv, on behalf (EMV), nfc, ecommerce, adj |
lastFourDigits | FALSE | Last 4 digits of card | |
acquirerCountry | FALSE | Country of acquirer | |
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 |
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": "PL" } } } ``` **Parameters:****Parameter** | **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. |
**Parameter** | **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 exept 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 proceess). | 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 wich this transaction is refere 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. |
**Parameter** | **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. | |
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 |