Card Management System
Verestro CMS is responsible for card issuing and account opening. The system can perform KYC and eKYC of the user before card issuing. You can manage card and user balance through CMS.
- Introduction
- Intro slides
- Overview
- Quick start
- Transactions Flow
- Your APIs for us - Notifications
- Your APIs for us - External Balance
- Technical documentation
- Digital Cards Design
- Physical Cards Design
- Legacy Transactions Notifier
- Frequently Asked Questions
Introduction
To meet the needs and expectations of its customers, Verestro has developed a flexible infrastructure, allowing it to issue cards to fintech, merchants, companies, payment institutions or banks. We can provide digital issuing services for licensed payment and banking institutions or using our partner network, BIN sponsors to companies without payment licenses.
Verestro provides its customers with a range of services based on the applicable laws, directives and guidelines of card issuers such as Mastercard and Visa. Meeting these guidelines based on security standards including PCI DSS, 4 steps must be followed to deliver the card to the user:
Create User
The first step to be fulfilled is to register the user in Verestro infrastructure in order to maintain his data in accordance with PCI DSS guidelines and secure the subsequent communication. Depending on the customer's needs to fulfill this step, there is a possibility of delivering a dedicated mobile application or, in case of already existing system, implementing SDK in own application or server-server connection in cases when the application is not necessary. Regardless of the path chosen, Verestro provides its customers with a dedicated Administration Panel to facilitate the management and monitoring of its customers.
White Label Application
To meet the needs of the most demanding customers, Verestro has developed a mobile application for iOS and android. The application has a modular design which, in the shortest possible time, can be personalized to the required functionalities, branded according to the guidelines and published in production. More about this solution can be found in White Label Application.
Mobile SDKs
Customers with their own infrastructure and well-established products who want to provide their users with new mobile functionalities in a fast and easy way, including secure payment instruments, may use dedicated SDKs. Verestro team actively supports their implementation and leads through necessary certification processes. More on SDK based implementation can be found in User Lifecycle & Card Management SDK.
Life Cycle API
Customers who, similarly to the above case, want to expand their offer with competitive functionalities, where mobile application is not applicable, can use dedicated backend solution in server-server connection. LC API created for this purpose in a safe and easy to implement way allows to meet this requirement. More about LC API can be found in User Lifecycle & Card Management API.
KYC
In order to meet the requirements of card issuers, legal regulations and international directives Verestro supports the KYC (Known Your User) process aimed at verification of the customer to whom the services and payment instruments will be offered. As in the case of user registration, here, too, there is the flexibility of adjusting this solution both from the user's side in the mobile application and the processing of the application itself.
Manual KYC Process
The standard Verestro solution makes it possible to collect the necessary data and photos of documents and persons in the mobile application and send the thus prepared request via a secure channel to the Verestro infrastructure. This process is supported both in the implementation of the White Label Application and/or implementation of SDK in the customer application. All KYC data are available through a dedicated Administration Panel, through which the client at a specific access level verifies the data submitted by users.
Automatic eKYC
As KYC process requires customisations and flexibility, Verestro platform enables integration of external entities supporting this process. With the implementation of which it is possible to achieve full automation and thus reduce user verification time to a minimum. With KYC verification automation, the user can have a working payment device within 3-5 minutes of installing the application on their phone.
External KYC
For institutions that are expanding their offerings to include card issuance and already have a KYC process in place, LC API is a dedicated channel from setting KYC status with the user more about it in User Lifecycle & Card Management API.
Create Balance
The third step that brings the user closer to obtaining the card is the creation of a balance / account for the user, which is a dedicated place that maintains the current balance of available funds in a specific currency. Depending on the customer's needs, the user can have a virtually unlimited number of balances.
Automatic
The most commonly used solution is to automatically create the balance as soon as the user gets a positive KYC verification status. With this approach, the user receives the balance in the currency defined within the project.
Manual
A client can create a balance for a user on demand or enable the user to do so themselves. Regardless of the implementation method, the process of creating balances is available in a dedicated mobile application, the provided SDK, from the server-to-server connection and through a dedicated admin panel. More on balance management can be found in Card Management System.
Create Card
The final step is to create a card linked to the previously created balance. Verestro provides its customers with the ability to generate virtual and physical cards for its users. With the implementation of the application in the minimum configuration specified by Mastercard, Verestro enables joining the Digital First program, where the user has a modern e-banking system along with a stylistically attractive physical representation of a virtual card. Processes related to issuing and managing cards are available in Card Management System.
Intro slides
Arichitecture
SDK / API implementation
Overview
Verestro Card Management System is called ANTACA. The platform provides solutions for creating and managing users' accounts (called "balances"), processing eKYC (user authentication process) and issuing payment cards generated for them.
CMS Antaca provides dedicated services for:
- end-user mobile applications,
- server-to-server connections helpful in integration with existing customer databases,
- administrative panel, necessary from the point of view of financial institutions in the process of issuing cards and managing their clients' funds.
CMS Antaca supports all necessary use cases for various digital and plastic card issuing. It supports integration with multiple issuing processors and can be connected with the one chosen by Verestro partner.
Introduction to Card Issuing process
With the CMS Antaca you can offer your customers three types of cards:
- Virtual card - Digital card without any physical components.
- Physical card – The traditional plastic payment card.
To be able to issue a card for a user, 4 requirements must be met:
- You have to integrated with Verestro platform using JWE token (described below) or other integration methods (API, SDK, White Label).
- User must exist in Verestro database called DataCore. Make sure you register user via User Lifecycle API & SDK.
- User must be strongly verified according to KYC. You can use Verestro KYC (see below) or own KYC process.
- The user must have a User Balance under which the card will be generated.
After those 4 steps you can issue a card for the User.
Below we describe this process step by step:
- Step 1. Configuration & JWE Security,
- Step 2. User Lifecycle API & SDK,
- Step 3. User registration & KYC,
- Step 4. Create User Balance (account),
- Step 5. Card issuing.
Terminology
Name |
Description |
Customer | Institution which is using Verestro products. This institution decides which SDK should be used and how transaction should be processed. Basicly Customer can be called Verestro client. |
User | User which is using Payment Hub Application. It is root of entity tree. User is identified in Wallet Server by some unique identifier which is provided after registration. User can have access to his data and operations based on session. User’s session is created after device pairing is performed. When session expires then user authentication have to be performed. Session is valid 10 minutes, however it is configurable parameter. |
Card | Card belongs to the user. User can have many cards. Card is identified via internal id given after storing card on Wallet Server. Whole PAN is stored on Wallet Server which has PCI DSS certificate. |
Device | Device belongs to user. When user starts using application after installation then device pairing is performed. After pairing device with some unique id, unique device installation id is generated and this installation is assigned to user. It is possible to have one active installation on specific device for specific user. |
Session Token | Token which defines User. It is an authorization way of the User. This entity is created after paring device and this is needed to perform any actions in the application. When session is expired then user authentication needs to be performed. Session is valid 10 minute s, however it is configurable parameter. |
Sender | Verestro Wallet user which triggers transaction to the Receiver (check User description). |
Receiver |
Receiver can be identified in Wallet Server (Internal) or may be an entity that does not exist in Wallet Server (External). ◦ Internal – this type of Receiver has his own unique identifier just like sender. It can also act as a Sender in the transaction process, ◦ External – this type of Receiver does not exist in Wallet Server. Transfers that are made to this type of Receiver require the entering of his card data by Sender. |
Mid | Merchant identifier. This entity is representing Merchant in Acquirer’s system. Customer have to provide the mid information to enable mid configuration in the Verestro system. Required to process 3DS authentication via Verestro System. |
Acquirer | External institution responsible for processing transaction and 3ds requests ordered by the Verestro Payment Hub App. Acquirer connects with banks / card issuers and returns information whether the ordered action on a given card is possible. |
PAN | (Primary Account Number) It is 14-19 (usually 16) digits number which is a unique identifier of the payment card issued to the customer's account. |
Wallet Server | Provides the backend services to support Mobile Payment Application via Verestro Wallet SDK and is responsible for managing users, devices, cards , device tokens, storing transactions history and communication with Acquirers. |
PCI DSS | PCI DSS (Payment Card Industry Data Security Standard) is a security standard used in environments where the data of payment cardholders is processed. The standard covers meticulous data processing control and protection of users against violations. |
IBAN | IBAN (International Bank Account Number) is an international standard for bank account numbering that allows you to transfer funds to foreign accounts and to receive transfers from foreign entities to domestic bank accounts. One of the assumptions of the IBAN standard is to simplify the system of cross-border transfers. |
QR |
A QR code (quick response code) is a two-dimensional barcode. Check here for more details. |
Configuration & JWE Security
To start the implementation, it is necessary to configure the payment processor. If we are using issuing processors already integrated with Verestro the process is simple and after quick information gathering (name of partner, BIN range, currency, remoteURL) a new card program can be setup for our partner.
You can communicate with the CMS Antaca API in three different dedicated channels:
- Mobile Application - Methods strarting with /Customers : designed for the mobile applications that use a session token sent in the header of each request. More about the possibilities of generating these tokens in the section White Label Application Overview.
- Server-to-server - methods starting with /Secure : this communication channel is protected by the x509 certificate. To start an implementation based on this communication channel, it is necessary to generate your own CSR and send it to Verestro. Verestro will sign it and return a valid certification in a response.
- Administrator and Customer Service (rarely used by partners) - methods starting with /admin : designed for the administration panel provided by Verestro.
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. |
|
|
JWE configuration
To setup connection we need from you enc and alg from JWE parameters. Acceptable values are:
- Algorithm used by Verestro to encipher content of message (enc) - A256GCM,
- Algorithm used by Verestro to encipher encryption key (alg) - RSA-OAEP-256,
- Algorithm needed from you to encipher content of message (enc) - A256GCM,
- Allowed algorithms for key encryption (alg) - RSA-OAEP-256 or RSA-OAEP.
Recommended JWE libraries for various programming languages:
Request
To process encrypted message you need to perform a few additional steps on top of standard message processing:
- Add headlines:
- Public-Key through which you can transfer to us your public key encoded b64 (more details below),
- Encrypted-Request headline confirming message encryption in both directions or Encrypt-Response when you need to get the encrypted response only; value true or false,
- Download Verestro Public Key - see in technical API specs on which endpoint,
- Use Verestro Public Key to create JWE and transfer data table in payload,
- Use token (string) received in Verestro response in point 3 below key encryption key in payload.
- for GET methods avoid point 2, 3, 4 above (headlines mentioned in point 1 are still necessary),
- for empty POST methods (without "body") use same rules as for GET message.
Response
After sending to CMS Antaca encrypted request you will receive from us encrypted message:
- Decipher token, which can be found in response below payload key (use your private key to perform this action),
- After decipher action you can see response in unencrypted form.
Additional information:
- Response are encrypted only in case of success - HTTP 20X,
- The only exception from the above mentioned rule is code 204 No content,
- In case of errors (i.e. validation errors) you will receive unencrypted response,
-
ENCRYPTION_REQUIRED,
-
INVALID_PUBLIC_KEY,
-
INVALID_PAYLOAD,
-
CANT_DECRYPT_PAYLOAD.
-
Example request:
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} |
Example response:
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. |
User Lifecycle API & SDK
Once Verestro configured a project for your program and you are ready to authenticate with us using JWE token you will need to register users on our platform.
Please check the following components:
- If you want to integrate directly from mobile appliacations or integrate server-to-server - User Lifecycle and Card Management API &SDK.
User registration & KYC
Once you registered users on our platform and would like to create accounts and issue cards for them you need to perform KYC. There are three alternative scenarios:
- You can use the Verestro KYC API in the verification process of your users.
- Users can register from the level of the mobile application using the SDK method /customers/me/register.
- You can also use a dedicated method in the server-to-server connection to initiate the verification of your users /secure/customers/(customerid)/register.
- If you already have KYC verification process on your side, just update the KYC flag for the user using User Lifecycle & Card Management API.
Once you registered users and performed KYC you can initiate account (called "balance") creation.
Create User Balance
It is main account balance that is connected with user account and card. Main User Balance attributes are currency, balance value and balance state. In order to create User Balance make sure user got through KYC process. KYC process can be either manual or automated. It can be performed by partner or Verestro. It is highly recommended that User Balance is hold by Verestro but we can approve projects where partner holds User Balance.
In order to create any payment card at Verestro CMS you have to create User Balance first. Payment card issued for particular User Balance cannot be moved to another balance later.
There is an important rule - one user can have multiply balances and for every balance user can have multiply payment cards.
To create User Balance use the following methods:
- in case of server-to-server connection /secure/customers/(customerid)/balances,
- in case of integration through mobile application /customers/me/balances.
For more information about account / balance management please check technical APIs.
Card issuing
With the Antaca API you can offer your customers three types of cards:
- Virtual card - Digital card without any physical components.
- Physical card – The traditional plastic payment card.
To be able to issue a card for a user, 3 requirements must be met:
- User must exist in a PCI DSS compliant Data Core system in Verestro. Make sure you register user via User Lifecycle API & SDK.
- User must be strongly verified according to KYC. You can use Verestro KYC or own KYC process.
- The user must have a User Balance under which the card will be generated.
- After those 3 steps you can issue a card for the user.
Digital card
If the API receives the request, it will create a 16-digit PAN (Permanent Account Number), CVC2 (Card Verification Code), and Expiry Date. You can then deliver this information to your customer.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor user as u
participant "mobile app" as m
participant antaca as a
participant datacore as d
participant "payment processor" as t
u->m: 1. generate card
m->a: 2. generate card(userID, SaldoID, configuration ID)
a->t: 3. generate card(cardholder, terminal)
t-->a: 4. card data
a->d: 5. store card
d-->a: 6. status
a-->m: 7. status
@enduml
Physical card
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor user as u
participant "mobile app" as m
participant antaca as a
participant "payment processor" as t
participant "card personalization institution" as ac
u->m: 1. order card
m->a: 2. OrderCard(delivery address, userID, SaldoID, configuration ID)
a->t: 3. OrderCard(cardholder, delivery address, terminal)
t-->a: 4. status
a-->m: 5. status
t->t: 6. GeneratePAN and prepare binary file
t->ac: 7. order card
t->t: 8. Generate orderCardReport
a->t: 9. get orderCardReport
t-->a: 10. orderCardReport
a->a: 11. connect card with user and saldo
a->t: 12. linkCard(trackingNo, reference)
t-->a: 13. status
a->t: 14. getAllLinkedCards
t-->a: 15. full card data
a->a: 16. store card in DC
ac-->u: 17. delivery card
u->m: 18. activate card
m->a: 19. activateCard
a->t: 20. activateCard
t-->a: 21. status
a->t: 22. update PIN (wPIN)
t-->a: 23. status
a->a: 24. update status in DC
@enduml
Actions
Create virtual
This method enables creation of virtual payment card for already created user and balance.
Availability
Collection | URL | Authentication | Encryption required | Available for admin roles |
Customer |
POST /customers or for an asynchronous process |
Session token |
YES* - JWE *for an asynchronous process NO |
N/A |
Admin | POST /admin |
Session token | YES* - JWE | Admin, Manager |
API |
POST /secure or for an asynchronous process |
x509 certificate |
YES* - JWE *for an asynchronous process NO |
N/A |
Lock
This functionality enables temporary or fixed blocking of already issued cards. After card being blocked every authorisation request will be rejected. While using this method you need to inform CMS Antaca about reasons of card blocking. List of reasons is described below in the table.
Code No | Card stop reason | Failure Action code on POS/ATM | irreversible |
1 | Card lost | 2008 | YES |
2 | Card stolen | 2009 | YES |
3 | Pending query | 1000 | NO |
4 | Card consolidation | 1016 | NO |
5 | Card inactive | 1018 | YES |
6 | PIN tries exceeded | 1006 | NO |
7 | Suspected fraud | 1002 | NO |
8 | Card replaced | 1011 | YES |
Availability
Collection | URL | Authentication | Encryption required | Available for admin roles |
Customer |
POST /customers |
Session token |
NO |
N/A |
Admin | Administrator blocks the card through the core of the administration panel | N/A | N/A | N/A |
API | x509 certificate |
NO |
N/A |
Unlock
This functionality enables unblocking previously blocked card. It works in case the card was not blocked with Code No 1, 2, 5 or 8 described in the above table (card lost, card stolen, card inactive or card replaced). CMS Antaca does not need reasons for card unblocking.
Availability
Collection | URL | Authentication | Encryption required | Available for admin roles |
Customer |
POST /customers |
Session token |
NO |
N/A |
Admin | Administrator unblocks the card through the core of the administration panel | N/A | N/A | N/A |
API | x509 certificate |
NO |
N/A |
Remove
This functionality enables card deletion from CMS Antaca. Deleted card cannot be restored.
Availability
Collection | URL | Authentication | Encryption required | Available for admin roles |
Customer |
DELETE /customers |
Session token |
NO |
N/A |
Admin | Administrator delete the card through the core of the administration panel | N/A | N/A | N/A |
API |
Other APIs remove the card via LC or directly in DC |
N/A |
N/A |
N/A |
Get full data
This functionality enables receiving full card data (PAN, Expiry Date, CVC2 or CVV). Access to those data for user should be always connected with additional authorisation by user (fingerprint, application PIN).
Availability
Collection | URL | Authentication | Encryption required | Available for admin roles |
Customer | Session token |
YES |
N/A | |
Admin | Administrator cannot view the full details of the cards | N/A | N/A | N/A |
API | x509 certificate |
YES |
N/A |
Reset CVV
This functionality enables generation of new CVC2 or CVV number for virtual.
Availability
Collection | URL | Authentication | Encryption required | Available for admin roles |
Customer | Session token |
YES |
N/A | |
Admin | POST /admin |
Session token | YES | Admin, Manager, Employee |
API | N/A | N/A | N/A | N/A |
Order physical card
This functionality enables ordering plastic card. Process of card personalisation can take up to 48 hours depending on chosen personalisation center. Additionally card will be transferred to user by courier or post office. Physical card ordered by this functionality will be inactive until activation action.
The DEV/BETA environment does not support physical card order testing.
Availability
Collection | URL | Authentication | Encryption required | Available for admin roles |
Customer |
|
Session token |
YES |
N/A |
Admin | Session token | YES | Admin, Manager, Employee | |
API | x509 certificate | YES | N/A |
Link card
Around 48 hours after card ordering it will be visible in user resources. After Verestro receives confirmation from personalisation center that card was personalised CMS Antaca connects card with user account and balance. From this moment it can be visible for user and can be activated.
Set PIN
This functionality is available for physical and virtual cards. It enables setting up PIN that is used for face-to-face transactions (POS and ATM). In the case of virtual cards - for ATM withdrawals.
IMPORTANT:
|
Availability
Collection | URL | Authentication | Encryption required | Available for admin roles |
Customer |
POST https://prepaidapi.upaid.pl/customers/me/cards/{cardId}/pin |
Session token |
YES |
N/A |
Admin | N/A | N/A | N/A | N/A |
API | N/A | N/A | N/A | N/A |
Activate card
This functionality enables activation of previously ordered physical card. Card transactions will not work until card is activated.
Availability
Collection | URL | Authentication | Encryption required | Available for admin roles |
Customer |
|
Session token |
NO |
N/A |
Admin | Session token | NO | Admin, Manager, Employee | |
API | x509 certificate | NO | N/A |
Lock outside
This functionality enables blocking of card in CMS Antaca on request of external entities (MC or VISA or acquirers). It can be used in case user entered incorrect PIN 3 times or in other fraud related actions. This lock cannot be removed if card was blocked by Code No 1, 2, 5, 8 (see below). The table below contains all possible reasons of card lock.
Code No | Card lock reason | Failure Action Code on POS/ATM | Irreversible |
1 | Card lost | 2008 | YES |
2 | Card stolen | 2009 | YES |
3 | Pending query | 1000 | NO |
4 | Card consolidation | 1016 | NO |
5 | Card inactive | 1018 | YES |
6 | PIN tries exceeded | 1006 | NO |
7 | Suspected fraud | 1002 | NO |
8 | Card replaced | 1011 | YES |
More information on Partner Balances and Deposit Requirements
Partner Balance
The partner balance is used in Verestro deployments together with the partner and BIN sponsor. The partner balance secures the financial liquidity of the BIN sponsor in the settlement process, while giving the partner the opportunity to manage the balances of its users.
Partner Credit Balance
Partner Credit Balance is used to process transactions of Partner especially in cases where User Balance is hold by Verestro. Examples of such projects are many standard projects where Partner is not financial institution or e-Wallet and does not hold User Balances on its side.
The main reason to use Partner Credit Balance is limiting transactions performed by Partner's users to funds hold on Partner Credit Balance. Verestro and its BIN sponsors cannot risk processing transactions without having funds available so this deposit needs to be used to enable transactions in such cases.
Partner through Verestro Administration Panel has access to actual level of Partner Credit Balance and can reload it by sending banking transfer to BIN Sponsor cooperating with Verestro. Partner can receive notification via e-email if Partner Credit Balance goes below pre-defined level.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
participant Partner as p
participant "Issuer Bank" as b
participant "Licensed Issuer" as i
participant Antaca as a
actor "End users" as u
p->b: 1. bank transfer
b->b: 2. accounting of funds
b-->i: 3. accounting of funds
i->a: 4. top up credit balance
p->a: 5. top up user balance
a->a: 6. charge credit balance
alt
a->a: 7. top up user balance
a-->p: 8. success
else insufficient funds
a-->p: 9. fail (insufficient funds)
end
@enduml
Partner Deposit Balance
Partner Deposit Balance is used alternatively to Partner Credit Balance. Partner Credit Balance is used to process transactions of Partner especially in cases where User Balance is not hold by Verestro. Examples of such projects are the ones with other wallet providers that already hold user balance or project where Verestro through its partners acts as BIN Sponsor or Principal Member for Affiliate Partner.
The main reason to use Partner Deposit Balance is limiting transactions performed by Partner's users to funds hold on Partner Deposit Balance. Verestro and its BIN sponsors cannot risk processing transactions without having funds available so this deposit needs to be used to enable transactions in such cases.
Partner through Verestro Administration Panel has access to actual level of Partner Deposit Balance and can reload it by sending banking transfer to BIN Sponsor cooperating with Verestro. Partner can receive notification via e-email if Partner Deposit Balance goes below pre-defined level.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
participant Partner as p
participant "Issuer Bank" as b
participant "Licensed Issuer" as i
participant Antaca as a
participant "Payment cloud" as mc
participant "POS/ATM" as pos
actor "End users" as u
p->b: 1. bank transfer
b->b: 2. accounting of funds
b-->i: 3. accounting of funds
i->a: 4. top up deposit balance
u->pos: 5. make payment
pos->mc: 6. payment authorization
mc->a: 7. payment authorization
a->a: 8. charge deposit balance
alt Sufficient deposit funds
a->a: 9. lock user funds
alt Sufficient user funds
a-->mc: 10. authorization success
mc-->pos: 11. authorization success
pos-->u: 12. success
else Insufficient user funds
a-->mc: 13. authorization fail
mc-->pos: 14. authorization fail
pos-->u: 15. fail
end
else Insufficient deposit funds
a-->mc: 16. authorization fail
mc-->pos: 17. authorization fail
pos-->u: 18. fail
end
@enduml
Balance Summary in Administration Panel
Summary Balances are a control tool used for accounting and liquidity verification reasons. They are presented in Administration Panel in every currency used in the project.
Users
Presents sum of all User Balances in particular currency.
Wallet
Presents sum of all User Balances and all Partner Balances in particular currency.
Actions
Create user balance
This functionality enables creation of user balance in particular currency.
Create Partner Deposit Balance or Partner Credit Balance
Not used in standard projects. This functional enables Partner creation of new Partner Deposit Balance or Partner Credit Balance for particular projects.
Get User Balance
Enables getting user balance and list of cards connected to this balance (account).
Get Partner Deposit Balance or Partner Credit Balance
This functional enables Partner getting information of Partner Deposit Balance or Partner Credit Balance for particular projects.
Reload Partner Deposit Balance or Partner Credit Balance
Not used in standard project. This functional enables Verestro to reload Partner Deposit Balance or Partner Credit Balance for particular projects. It is used by Verestro.
Reload user balance
This functionality enables reloading User Balance.
Fee management
Fee Management System documentation: Fee Management Platform | Verestro Developer Zone.
It is possible to setup various fees charged to users for card issuing and account management activities. Fees can be setup through administration panel by customer or dedicated Verestro customer services. Fees can be managed in two ways:
- Partner can setup own fee management system and charge users completely outside of Verestro system
- Partner can use Verestro fee management module available in Administration Panel
There are various fees that can be configured via Administration Panel:
- fee for account creating
- fee for card creating
fee for token creating- monthly / weekly / daily fee per card
monthly / weekly / daily fee per account- POS transaction fees (fixed and percantage)
- eCom transaction fees
- ATM transaction fees
- Money transfer fee (IBAN Transfer)
- Currency conversion fees
- and others
There is implementation on-going to have conditional fees like - "if users do 1000 eur transaction monthly we do not charge monthly fee".
Please consult Verestro sales or Project Manager in case you need more information.
Other functionalities
You can find additional methods in API descriptions:
- API used for server-to-server connections,
- API used for mobile application-to-server connections,
- API used for Administration Panel access (rarely used by partners).
In case of questions please let us know.
Quick start
Welcome to quick guide on Card issuing. You will find here a 4 step instruction on how to issue a card using Antaca service with our sandbox environment. Set connection to our services following instructions described here. Once you receive your certificate from us, follow the steps below:
Our sandbox environment has a basic configuration allowing maintaining balances on the Verestro side, without protection for the bin-sponsor (masterbalance)
-
Add user.
Send POST request to /lifecycle/v1/wallet with user data (firstName, lastName, phone, email). You’ll receive customerID in return - it will be needed in further steps. Make sure you set value kyc = SUCCESS. It is necessary for further processes.
example curl:curl -X POST 'https://lifecycle.upaidtest.pl/lifecycle/v1/wallet' \ --cert /path/to/cert.pem \ --key /path/to/key.pem:password \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Issuer-Code: sandbox' \ --header 'Application-Id: SBX-APP-ID' \ --header 'Collection: lifecycle' \ --data-raw '{ "firstName": "John", "lastName": "Doe", "phone": "481234567899", "email": "john.doe@verestro.com", "birthDate": "2000-01-01", "wPIN": "1234", "state": "VERIFIED", "kyc": "SUCCESS" }'
-
Create user verification form.
Send POST request to /secure/customers/{customerId}/verification using customerID you’ve received in previous step. It will create KYC verification form.
example curl:curl --location --request POST 'https://sandbox-antaca.secure-verestro.dev/secure/customers/{customerId}/verification' \ --cert yourCertificate.crt:password \ --key yourPrivate.key \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/json' \ --form 'firstName=Leon' \ --form 'lastName=Bakiewicz' \ --form 'imageFace=@/your/path/someFile.jpg' \ --form 'street=Pieklo' \ --form 'pesel=70010155587' \ --form 'number=17a' \ --form 'city=Lublin' \ --form 'birthDate=1970-01-01' \ --form 'postCode=20-128' \ --form 'imageFront=@/your/path/someFile.jpg' \ --form 'imageBack=@/your/path/someFile.jpg' \ --form 'identityCardNo=ASD123456' \ --form 'apartment=2' \ --form 'documentType=passport' \ --form 'country=PL' \ --form 'documentExpirationDate=2025-01-30' \ --form 'nationality=polish' \ --form 'riskLvl=LOW'
-
Create user balance.
Send POST request to /secure/customers/{customerId}/balances. In response you will receive the balanceID with which you will be able to generate a card in the next step
example curl:curl --location --request POST 'https://sandbox-antaca.secure-verestro.dev/secure/customers/{customerId}/balances' \ --cert yourCertificate.crt:password \ --key yourPrivate.key \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --data-raw '{ "currency": "EUR" }'
if you are using IMS service, after the balance was created, the IBAN number will be generated automatically.
-
Create new virtual card.
Using customerID, balanceID and configID, send POST request to /secure/customers/{customerId}/cards/virtual.Single ConfigID contains information about the card type (virtual/physical), currency and bin range. You will receive it at the stage of configuring your project in Verestro. In the case of sandbox, please use 0019167984
example curl:curl --location --request POST 'https://sandbox-antaca.secure-verestro.dev/secure/customers/{customerId}/cards/virtual' \ --cert yourCertificate.crt:password \ --key yourPrivate.key \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Encrypted-Response: true' \ --header 'Public-Key: {enduserPublicKey}' \ --data-raw '{ "balanceId": "0351eb09-3ac0-4234-a4ad-0a6ad52f248b", "configId": "0019167984" }'
Transactions Flow
A transaction in the processing flow can be in different states:
Status | Description |
transaction was successfully authorized. Resources on Cardholder's account are blocked, and the amount is "promised" to the merchant. At this moment none of the resources transfer was performed. |
|
CLEARED |
transaction is settled successfully. Resources on Cardholder's account gets unblocked and transferred to Merchant's account. Block on Cardholder account becomes charge, and "promised" amount becomes income on Merchant's account. |
REVERSED |
transaction was withdrawn, for example as error reported by Merchant. Block is removed and resources on the Cardholder account stay unmoved. None of the transfers is performed. |
Transaction processing status in Antaca system:
Status | Description | Example - Legacy Transaction Notifier |
SUCCESS | indicates that the transaction (AUTHORIZED, CLEARED OR REVERSED) has been successfully processed in Antaca. | {"status":"SUCCESS","date":"2023-01-01T06:01:39+00:00","description":"Description","transaction":{"id":"79c353a-1421-46ca-8d74-c5dca67942fe","balanceId":"79c353a-1421-46ca-8d74-c5dca67942fe","resourceId":"79c353a-1421-46ca-8d74-c5dca67942fe","resource":"card","cardId":"100","externalTransactionId":"478927492","referenceExternalTransactionId":null,"type":"POS","category":"DEBIT","amount":300,"currency":"EUR","originalAmount":1000,"originalCurrency":"POL","status":"AUTHORIZED","description":"Description","date":"2023-01-01T06:01:39+00:00","referenceExternalTransactionDate":null,"transactionData":{"mcc":"5816","merchantIdentifier":"7498274892","captureMode":"ECOM","lastFourDigits":"1000","acquirerCountry":"POL"}}} |
DECLINED |
indicates that the transaction has been declined. None of the funds are transferred from Cardholder's account.
The reason for the transaction rejection (description parameter) is listed in the documentation in the table below: https://developer.verestro.com/books/card-management-system/page/your-apis-for-us#bkmrk-external-transaction An example of a rejected transaction could be insufficient funds in the account (INSUFFICIENT_FUNDS). |
{"status":"DECLINED","date":"2023-01-01T06:01:39+00:00","description":"Description","transaction":{"id":"79c353a-1421-46ca-8d74-c5dca67942fe","balanceId":"79c353a-1421-46ca-8d74-c5dca67942fe","resourceId":"79c353a-1421-46ca-8d74-c5dca67942fe","resource":"card","cardId":"100","externalTransactionId":"74892729","referenceExternalTransactionId":null,"type":"POS","category":"DEBIT","amount":70000,"currency":"EUR","originalAmount":70000,"originalCurrency":"EUR","status":"AUTHORIZED","description":"Description","date":"2023-01-01T06:01:39+00:00","referenceExternalTransactionDate":null,"transactionData":{"mcc":"2312","merchantIdentifier":"000000136 ","captureMode":"ECOM","lastFourDigits":"1000","acquirerCountry":"POL"}}} |
INVALID | indicates that the transaction can't be processed. None of the funds are transferred from Cardholder's account. | {"status":"INVALID","date":"2023-01-01T06:01:39+00:00","description":"Description","transaction":{"id":"79c353a-1421-46ca-8d74-c5dca67942fe","balanceId":"79c353a-1421-46ca-8d74-c5dca67942fe","resourceId":"79c353a-1421-46ca-8d74-c5dca67942fe","resource":"card","cardId":"100","externalTransactionId":"78391719","referenceExternalTransactionId":"783197893","type":"Adjustment","category":"CREDIT","amount":800,"currency":"EUR","originalAmount":null,"originalCurrency":null,"status":"REVERSED","description":"Description","date":"2023-01-01T06:01:39+00:00","referenceExternalTransactionDate":"2023-01-01T06:01:39+00:00","transactionData":[]}} |
Transaction Processing Cases
REVERSAL
Transaction reversal may occur in several cases:
- The merchant did not receive a timely response regarding the authorization status from the payment schema or there were connection problems on the payment schema which generated a timeout on the merchant's side.
- A timeout occurred on the merchant's side and the transaction could not be completed.
Below are examples of payloads from individual services: for (1.) Debit transaction and (2.) Reversal that follows:
Legacy Transaction Notifier | Transaction History Core | External Balance | |
1. Debit transaction | {"status":"SUCCESS","date":"2023-01-01T10:10:57+00:00","description":"APPROVED","transaction":{"id":"24cbc777-de3f-42e2-b772-7d5427dc616e","balanceId":"16b53ddb-877c-4d6c-80c7-2d3750f24b65","resourceId":"59664b2b-8403-4205-a400-92283fa95ffe","resource":"card","cardId":"222","externalTransactionId":"177482","referenceExternalTransactionId":null,"type":"POS","category":"DEBIT","amount":2233,"currency":"EUR","originalAmount":76000,"originalCurrency":"THB","status":"AUTHORIZED","description":"Description","date":"2023-01-01T10:10:54+00:00","referenceExternalTransactionDate":null,"transactionData":{"mcc":"4121","merchantIdentifier":"12345678","captureMode":"ECOM","lastFourDigits":"1234","acquirerCountry":"THA"}}} |
{"id":81111111,"clientTransactionId":"24cbc777-de3f-42e2-b772-7d5427dc616e","amountMinor":2233,"currency":"EUR","type":"PURCHASE","status":"AUTHORIZED","timestamp":"2023-01-01T10:10:54Z","description":"Description","comment":null,"userId":111,"userExternalId":null,"cardId":222,"externalCardId":null,"deviceId":null,"externalDeviceId":null,"paymentTokenId":null,"cardLastFourDigits":"1234","paymentTokenLastFourDigits":null,"cardBin":"555770","userPhone":"48111222333","userEmail":"example@example.com","merchantName":"Description","merchantPostalCode":null,"merchantTransactionId":"177482","transactionCountryCode":"THA","comboCardAccountType":null,"issuerResponseInformation":null,"transactionChannel":"ECOMMERCE","area":"PREPAID","ibanId":null,"deviceInstallationId":null,"employeeGroupId":null,"issuerId":null,"corporationId":null,"mcc":"4121","mccCategory":null,"balanceId":"16b53ddb-877c-4d6c-80c7-2d3750f24b65","originalAmountMinor":76000,"originalCurrency":"THB","exchangeRate":34.053252272342,"balanceMinorValueAfterTransaction":20000,"commissionMinorValue":22,"clearingTimestamp":null,"parentId":null,"ica":null,"contrahent":{"iban":null,"bic":null,"name":"Description"},"attachmentStatus":"EMPTY","incorrectAttachmentStatusReason":null,"labels":[],"categoriesInfo":null,"walletReference":null,"balanceMinorValueBeforeTransaction":null,"interchangeMinorAmount":null,"interchangeCurrency":null} |
endpoint: transactions/debit
{"id":"24cbc777-de3f-42e2-b772-7d5427dc616e","balanceId":"16b53ddb-877c-4d6c-80c7-2d3750f24b65","resourceId":"59664b2b-8403-4205-a400-92283fa95ffe","resource":"card","transactionId":"177482","referenceTransactionId":null,"type":"pos","amount":2233,"currency":"EUR","originalAmount":76000,"originalCurrency":"THB","status":"AUTHORIZED","description":"Description","date":"2023-01-01T10:10:54+00:00","transactionData":{"mcc":"4121","merchantIdentifier":"12345678","merchantName":null,"captureMode":"ECOM","cardId":"222","lastFourDigits":"1234","acquirerCountry":"THA","mdesDigitizedWalletId":null,"cashbackPosCurrencyCode":null,"cashbackPosAmount":"0","lastFourDpan":null,"adjustmentReasonDescription":null,"retrievalReferenceNumber":"443322110088"}} |
2. Reverse transaction |
{"status":"SUCCESS","date":"2023-01-01T11:50:10+00:00","description":"APPROVED","transaction":{"id":"24cbc777-de3f-42e2-b772-7d5427dc616e","balanceId":"16b53ddb-877c-4d6c-80c7-2d3750f24b65","resourceId":"59664b2b-8403-4205-a400-92283fa95ffe","resource":"card","cardId":"222","externalTransactionId":"2678823","referenceExternalTransactionId":"177482","type":"Adjustment","category":"CREDIT","amount":2233,"currency":"EUR","originalAmount":null,"originalCurrency":null,"status":"REVERSED","description":"Description","date":"2023-01-01T13:43:30+00:00","referenceExternalTransactionDate":"2023-01-01T10:10:54+00:00","transactionData":[]}} |
{"id":81111111,"clientTransactionId":"24cbc777-de3f-42e2-b772-7d5427dc616e","amountMinor":0,"currency":"EUR","type":"PURCHASE","status":"REVERSED","timestamp":"2023-01-01T10:10:54Z","description":"Description","comment":null,"userId":111,"userExternalId":null,"cardId":222,"externalCardId":null,"deviceId":null,"externalDeviceId":null,"paymentTokenId":null,"cardLastFourDigits":"1234","paymentTokenLastFourDigits":null,"cardBin":"555770","userPhone":"48111222333","userEmail":"example@example.com","merchantName":"Description","merchantPostalCode":null,"merchantTransactionId":"2678823","transactionCountryCode":"THA","comboCardAccountType":null,"issuerResponseInformation":null,"transactionChannel":"ECOMMERCE","area":"PREPAID","ibanId":null,"deviceInstallationId":null,"employeeGroupId":null,"issuerId":null,"corporationId":null,"mcc":"4121","mccCategory":null,"balanceId":"16b53ddb-877c-4d6c-80c7-2d3750f24b65","originalAmountMinor":76000,"originalCurrency":"THB","exchangeRate":34.053252272342,"balanceMinorValueAfterTransaction":20000,"commissionMinorValue":22,"clearingTimestamp":null,"parentId":null,"ica":null,"contrahent":{"iban":null,"bic":null,"name":"Description"},"attachmentStatus":"EMPTY","incorrectAttachmentStatusReason":null,"labels":[],"categoriesInfo":null,"walletReference":null,"balanceMinorValueBeforeTransaction":null,"interchangeMinorAmount":null,"interchangeCurrency":null} |
endpoint:
transactions/force-credit
{"id":"24cbc777-de3f-42e2-b772-7d5427dc616e","balanceId":"16b53ddb-877c-4d6c-80c7-2d3750f24b65","resourceId":"59664b2b-8403-4205-a400-92283fa95ffe","resource":"card","transactionId":"2678823","referenceTransactionId":"177482","type":"adjustment","amount":2233,"currency":"EUR","originalAmount":null,"originalCurrency":null,"status":"REVERSED","description":"Description","date":"2023-01-01T13:43:30+00:00","transactionData":{"mcc":null,"merchantIdentifier":null,"merchantName":null,"captureMode":null,"cardId":"222","lastFourDigits":null,"acquirerCountry":null,"mdesDigitizedWalletId":null,"cashbackPosCurrencyCode":null,"cashbackPosAmount":null,"lastFourDpan":null,"adjustmentReasonDescription":null,"retrievalReferenceNumber":null}} |
Adjustments
Some transactions add funds instead of debiting accounts. Antaca reports such transactions with type: Adjustment.
Transactions of this type can be:
adjustment transactions related to the debit transaction but reducing or increasing the final debit amount before clearing |
adjustment transactions related (or not) to the another already cleared transaction, fe refund or offline transaction. |
adjustment for transactions with currency conversion - when the acquirer let know to clear transaction to the card network, the previously determined FX added to the transaction amount is deposited into the company balance |
Example of adjustment - External Transaction Notifier:
{"status":"SUCCESS","date":"2023-01-01T06:01:39+00:00","description":"Description","transaction":{"id":"e79c353a-1421-46ca-8d74-c5dca67942fe","balanceId":"e79c353a-1421-46ca-8d74-c5dca67942fe","resourceId":"e79c353a-1421-46ca-8d74-c5dca67942fe","resource":"card","cardId":"22","externalTransactionId":"928562957345","referenceExternalTransactionId":"7489279234","type":"Adjustment","category":"CREDIT","amount":100,"currency":"EUR","originalAmount":25000,"originalCurrency":"PLN","status":"AUTHORIZED","description":"**********************************************************","date":"2023-01-01T06:01:39+00:00","referenceExternalTransactionDate":"2023-01-01T06:01:39+00:00","transactionData":{"mcc":"9311","merchantIdentifier":"7489274","captureMode":"ADJ","lastFourDigits":"1000"}}}
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.
- Notification about outcome of KYC process.
- 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, more about this model here.
In the first step, Verestro will send to the client a CSR for the dev and production environments, more details here.
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 |
|
|
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
JWE configuration
connection we need from you enc and alg from JWE parameters. Acceptable values are:
- Algorithm used by Verestro to encipher content of message (enc) - A256GCM,
- Algorithm used by Verestro to encipher encryption key (alg) - RSA-OAEP-256,
- Algorithm needed from you to encipher content of message (enc) - A256GCM,
- Allowed algorithms for key encryption (alg) - RSA-OAEP-256 or RSA-OAEP.
Recommended JWE libraries for various programming languages:
Request:
To process encrypted message you need to perform a few additional steps on top of standard message processing:
- Verestro add headlines:
- Public-Key through which you can encrypt response to us (if needed),
- Encrypted-Request headline confirming message encryption; value true or false,
- Expose endpoint with your Public Key - you will find a similar endpoint in our technical documentation, GET /secure/public_key
- Use Verestro Public Key to create JWE and transfer data in payload,
Response:
When the response contains sensitive data that requires encryption, use Verestro public key encryption available here GET /secure/public_key
Additional information:
- In case of errors (i.e. validation errors) you will receive unencrypted response,
-
ENCRYPTION_REQUIRED,
-
INVALID_PUBLIC_KEY,
-
INVALID_PAYLOAD,
-
CANT_DECRYPT_PAYLOAD.
-
Example request:
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} |
Example response:
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. |
Public Key
This method is used to share your public key for encryption.
GET https://server-domain.com/public-key
Headers:
Content-Type: application/json
response:
200 OK
{
"publicKey": "QSBwdWJsaWMga2V5IHNob3VsZCBiZSBoZXJlIGhvd2V2ZXIgaXQgd2FzIHRvbyBsb25nIDoo"
}
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
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:
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 |
ISO 4217 3-letter code |
merchantName |
TRUE |
Merchant name |
string value |
otp | TRUE | One time password | string value |
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
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:
{
"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:
{
"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:
{
"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:
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:
|
string value |
reason | TRUE |
Verification status reason ACCEPTED: null IN_PROGRESS: null REJECTED:
|
null/string value |
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"
}
Transactions notifier
To get notifications about transactions use Transaction History Core API
Your APIs for us - External Balance
External Balance
Features
Purpose and scope
Terminology
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.
In the first step, Verestro will send to the client a CSR for the dev and production environments, more details here.
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
External Balance API
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.
Process of linking balances
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
participant "Client server" as cs
participant Antaca as a
participant Lifecycle as lc
cs->lc: 1. create user by POST /wallet (firstName, lastName, phone, email)
lc-->cs: 2. userId
alt With own KYC process
cs->lc: 3. update KYC status by PUT /user (KYC)
else With Verestro KYC process
cs->a: 4. send KYC data by /register (user data with documents and selfie)
a->a: 5. process KYC
a->lc: 6. update KYC status
end
alt With automatic balance creation
lc-->a: 7. event about the new user with KYC
a->a: 8. create a balance in the default currency
a->cs: 10. link balance (userId, balanceId, currency)
cs-->a: 11. 204 (OK)
else Every time with create a balance
cs->a: 9. create balance by POST /balance (userId, currency)
a->cs: 10. link balance (userId, balanceId, currency)
cs-->a: 11. 204 (OK)
a-->cs: 12. 201 balance created
end
@enduml
- send a GET requests to retrieve information about specific balance. Using user ID and/or balance ID, Antaca can obtain information about balance currency and money amount.
- send a GET requests to retrieve information about all user’s balances. Using only user ID Antaca can retrieve list of users balances.
- delete link between balances
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
example:
curl POST "https://server-domain.com/transactions/debit"
--header "X-Idempotency-Key: 21aa0c2a-5554-4071-bd48-b9c64a0b6270"
Transaction object
{
"id": "b4f534ef-77c2-4f16-ab4d-496806a76fb6",
"balanceId": "b334b384-328c-11ed-a261-0242ac120002",
"resourceId": "9d673932-3291-11ed-a261-0242ac120002",
"resource": "card",
"transactionId": "ab3d89e4-3291-11ed-a261-0242ac120002",
"referenceTransactionId": "b759931c-3291-11ed-a261-0242ac120002",
"type": "POS",
"amount": 10000,
"currency": "PLN",
"originalAmount": 10000,
"originalCurrency": "PLN",
"status": "AUTHORIZED",
"description": "transaction description",
"date": "2020-08-17T18:43:42+00:00",
"transactionData": {
"mcc": "5942",
"merchantIdentifier": "003060300000005",
"merchantName": "Book store",
"captureMode": "NFC",
"lastFourDigits": "4560",
"acquirerCountry": "PL",
"mdesDigitizedWalletId": "Google Pay",
"cashbackPosCurrencyCode": "PLN",
"cashbackPosAmount": 10000,
"paymentTokenLastFourDigits": "7890",
"adjustmentReasonDescription": "REFUND",
"retrievalReferenceNumber": "749248185012"
}
}
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 network 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 |
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, commission, fee, funding, interest, withdrawal, pos, atm, cashback_at_pos, adjustment |
amount |
TRUE |
Transaction value in gross (minor value) For example: 12.34 EUR will be sent as 1234 |
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) For example: 12.34 EUR will be sent as 1234 |
integer value |
originalCurrency |
FALSE | Original currency 3-letters code in ISO 4217 | ISO 4217 3-letter code |
status |
TRUE | Transaction status | AUTHORIZED, CLEARED, REVERSED |
description |
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 |
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 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 |
paymentTokenLastFourDigits | FALSE | Last 4 digits of Device Primary Account Number (tokenized PAN) | |
adjustmentReasonDescription | FALSE |
Reason for adjustment |
eg. REFUND, MONEY_SEND, CHARGEBACK |
retrievalReferenceNumber | FALSE | 12-digit number generated to record each transaction | |
cardId | FALSE | 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. |
Integration with External Balance
API External balance
For the process to function correctly, the Client must implement all endpoints detailed in this chapter.
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. If you decide to implement external balance to be able to keep the balance on your side and authorize transactions, remember that the implementation of all the methods below is required to ensure the API works.
Link balance
This method is used to link customer balance between client and server. Requested balanceId will be used for communication between client and Verestro side.
If you create balance entity at your end you should create it after receiving this call. Do not create balance entity on your side as result of POST /secure/balances nor POST /secure/customers/{id}/balances, because link balance will be called before response to these methods.
POST https://server-domain.com/users/:id/balances
path parameters:
id - user identifier
Headers:
Content-Type: application/json
Accept: application/json
request body:
{
"balanceId":"2e520dc2-329d-11ed-a261-0242ac120002",
"currency": "PLN"
}
parameters:
balanceId - unique identifier of balance in format: uuid v4. This ID will be used in communication between client and server.
currency - required, should be 3 letters code in ISO 4217 https://www.iban.com/currency-codes
response:
204 NoContent
error codes:
404 - should be returned if no user has been matched by requested path parameter.
Code 404
{
"title": "USER_NOT_FOUND",
"detail": "some specific details provided by server"
}
Get single user balance
Method used to obtain single user balance information.
GET https://server-domain.com/users/:id/balances/:balanceId
path parameters:
id - user identifier
balanceId - unique balance identifier
headers:
Accept: application/json
response:
200 OK
{
"currency": "PLN",
"amount": 250
}
response parameters:
currency - three letter iso 4217 code
amount - actual balance amount in minor (penny), integer value. For example: 12.34 EUR will be sent as 1234
error codes:
404 - should be returned if no balance found by requested balanceId.
Code 404
{
"title": "BALANCE_NOT_FOUND",
"detail": "some specific details provided by server"
}
403 - if requested balance does not belong to user.
Code 403
{
"title": "FORBIDDEN",
"detail": "some specific details provided by server"
}
Get balance collection
This method should return collection of customer balances.
GET https://server-domain.com/users/:id/balances
path parameters:
id - user identifier
headers:
Accept: application/json
response:
200 OK
[
{
"id": "a072bd0e-328c-11ed-a261-0242ac120001",
"currency": "PLN",
"amount": 250
},
{
"id": "b334a5e2-328c-11ed-a261-0242ac120002",
"currency": "USD",
"amount": 460
}
]
If user has not created any balance yet, there should be returned empty collection.
200 OK
[]
response parameters:
id - unique identifier of user balance
currency - three letter iso 4217 code
amount - actual balance amount in minor (penny), numeric value
Delete balance
This method is used to unattached balance from user. From legal point of view, balance should be deleted only if there is no money on it.
DELETE https://server-domain.com/users/:id/balances/:balanceId
path parameters:
id - user identifier
balanceId - unique balance identifier
response:
204 No Content
error responses:
404 - if requested balance has not been found.
Code 404
{
"title": "BALANCE_NOT_FOUND",
"detail": "some specific details provided by server"
}
403 - if requested balance does not belong to user.
Code 403
{
"title": "FORBIDDEN",
"detail": "some specific details provided by server"
}
Debit transaction
This kind of transaction is used to authorize transaction. In debit transactions Antaca asks 'if user has money?'.
POST https://server-domain.com/transactions/debit
headers:
Content-Type: application/json
X-Idempotency-Key: uuidV4
request body:
Description of the contents of the transaction object can be found above.
success response:
204 No Content
error responses:
422
{
"title": "INSUFFICIENT_FUNDS",
"detail": "some specific details provided by server"
}
422
{
"title": "LIMITS_EXCEEDED",
"detail": "some specific details provided by server"
}
422
{
"title": "FRAUDS_DETECTED",
"detail": "some specific details provided by server"
}
404
{
"title": "BALANCE_NOT_FOUND",
"detail": "some specific details provided by server"
}
Force debit transaction
This kind of transaction is used to inform server side that transaction has occurred.
For this request, actual transaction already happen so server can not reject this request. This behavior can occur for offline transactions fe: in plane, subway, for refunds and referring to previously authorized transactions.
POST https://server-domain.com/transactions/force-debit
headers:
Content-Type: application/json
X-Idempotency-Key: uuidV4
request body:
Description of the contents of the transaction object can be found above.
response:
204 No Content
error response:
As mention in description section, we do not accept transaction rejection.
Credit transaction
Method is used to credit user balance. In credit transactions Antaca asks 'can user get money?'.
POST https://server-domain.com/transactions/credit
headers:
Content-Type: application/json
X-Idempotency-Key: uuidV4
request body:
Description of the contents of the transaction object can be found above.
success response:
204 No Content
error responses:
404
{
"title": "BALANCE_NOT_FOUND",
"detail": "cannot find requested balance"
}
422
{
"title": "FRAUDS_DETECTED",
"detail": "some specific details provided by server"
}
Force credit
Method is used to credit user balance. This kind of transaction is used to inform server side that transaction has occurred. For this request, actual transaction already happen so server can not reject this request.
POST https://server-domain.com/transactions/force-credit
headers:
Content-Type: application/json
X-Idempotency-Key: uuidV4
request body:
Description of the contents of the transaction object can be found above.
success response:
204 No Content
error response:
As mention in description section, we do not accept transaction rejection.
Reversal
Method is used to revert any changes for previous transaction. Request body will be identical to transaction witch client try to revert. If server cannot find referenced transaction then no action is required.
POST https://server-domain.com/transactions/reversal
headers:
Content-Type: application/json
X-Idempotency-Key: uuidV4
request body:
Description of the contents of the transaction object can be found above.
success response:
204 No Content
error responses:
IMPORTANT: for this method, we do not accept any error. Only satisfying behavior is to revert referenced transaction and no action if cannot find transaction.
Update transaction status
From time to time, client will inform about clearings triggered by acquirer side. If client mark transaction as cleared it means that transaction will not be corrected by any other transaction request and requested amount is final.
PUT https://server-domain.com/transactions/:id
path parameters:
id - transaction identifier
request body:
Description of the contents of the transaction object can be found above.
success response:
204 No Content
error responses:
404
{
"title": "TRANSACTION_NOT_FOUND",
"detail": "cannot find requested transaction"
}
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. |
Commission |
internal transaction for a partner who wants to debit user balance as a commission referenced to the other transaction. |
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 |
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 |
CreditIbanTransfer |
internal transaction dedicated only for IMS API (via specific CN). IMS API uses this balance to credit funds on the user's balance. |
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 |
Technical documentation
Server-server connection
@swagger="https://s3.verestro.dev/quicko-prepaid/devzone/api-docs-secure.json?AWSAccessKeyId=quicko-prepaid&Signature=0hLv91hrIjIu%2Fdg8N%2BPEVvfpcm4%3D&Expires=2020026755"
Digital Cards Design
Design Specifications for Graphic Designers and Customers Required for the MDES Manager Application
- Sizes required for the MDES Manager: 1536 px x 969 px
- File format: PNG
If you are submitting files to be verified by Verestro, you will need the SVG format. - The corners of the cards should not be rounded. The corners will be rounded in the application.
Remember that in the Apple Pay and Google Pay applications, the card number is placed in the bottom left corner of the cards. The card numbers should be visible.
What do we need for MDES manager?
1. Preparation of the card for MDES Menager (according to the guidelines above).
2. Client's logo for MDES Menger (size: 1372px x 293px).
3. Client icon (favicon) for mdes manager (size: 100px x 100px).
What do we need for 3ds?
1. Preparation of the client's logo for 3DS (size: 129px x 60 px).
The UX department will help provide logos and icons in appropriate sizes, please provide the icon and logo that will appear on a white background.
Download the Mastercard logo in SVG format for your project:
Physical Cards Design
Required Design Specifications for Graphic Designers and Customers Required
You should prepare two files:
- Preview (png).
- For printing (pdf, ai).
For printing:
- Sizes required : 242 px x 153 px
- Bleeds: 5 mm
- Placed logos should be sent as vector graphic (paths, curves).
- Colour images should have at least 300 dpi print resolution.
- Indicate the fonts used and save them on the data carrier or convert any text to curves.
- On the printing card we put only:
- Your logo (vector).
- Authorized signature.
- All texts.
- Custom service.
For a more detailed description of how to prepare the card and its appearance options, see the Mastercard Design Specifications for Graphic Designers and Customers.
Download the Mastercard logo in SVG format for your project:
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:
Antaca automatically debits the deposit partner balance with:
|
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:
|
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 |
interchangeCredit |
transaction automatically generated by Antaca as a result of settlement previously authorized transactions. This type of transaction top up only the company 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:
|
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:
Antaca automatically credits the deposit partner balance with:
|
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 |
Frequently Asked Questions
Certificates
in progress
User
Blocking user
Q: Does blocking the user results in blocking user's cards as well?
A: No.
Cards
Creating card
Q: Cards are created with status VERIFIED. Should users perform card activation to virtual cards?
A: Virtual cards do not need to be activated. This only applies to physical cards.
Q: What is the default status for a newly ordered virtual and physical cards?
A: Virtual cards are active right after being created. Physical cards need to be activated by the end user. To check if a card is active, search for activationDate parameter in method GET /admin/cards - if it's not null, card is active.
Physical cards
Q: Client is asking about physical cards and where they can track when this card is issued or what is the current status?
A: We do not provide it via API, but they can do it through an agreement with a courier company that will deliver cards from the personalization company to users.
PIN
Q: User's card will be auto locked after 3 failed PIN attempt by the issuer. Do we send a callback response to client when this happens?
A: No.
Q: Is OTP required when sending a request to /admin/cards/{cardId}/pin to change card PIN?
A: OTP is not required in this situation.
Q: How to set PIN for a card?
A: PIN can be set before generating the card using the wPIN variable in the POST /wallet method at the very beginning when creating a user in LC - we need information whether we should enable this option if it will be used.
Q: When user needs PIN for virtual cards?
A: PIN for virtual cards is used only for ATM withdrawals. PIN for physical cards is used only for contact payments and in ATMs.
Q: How to change PIN?
A: PIN can be set/changed at any time using the /secure/customers/{customerId}/cards/{cardId}/pin method. This is the recommended method for set/change PIN for implementations such as Remessa, because with this method they provide this option directly to the user live.
Top-up
Q: Is it possible to topup temporarily blocked card or to get card details?
A: Internal transactions can still be made. Details cannot be viewed.
Deleting card
Q: Do we have any server-side mechanism preventing us from deleting lastly added card?
A: No.
Q: What happens to cards asigned to deleted balance?
A: After deleting balance, all cards asigned to balance are deleted as well.
Q: How to delete a card?
A: in Admin Panel (enabled for Admin and Manager role) or using /secure endpoint: DELETE /secure/cards/{cardId}
External cards
Q: Is CVV required to add an external card?
A: It depends on card issuer. Some of them don't verify CVV or Expiration date.
Balance
Q: How can we delete an user's balance?
A: Firstly balance must be equal to 0 and all transactions must be cleared. Then following method should be used: /admin/customers/{customerId}/balances/{balanceId} .
Does deleting a balance automatically results in deleting IBAN from IBAN list?
A: Yes, IMS will delete IBAN after receiving event from Antaca.
Q: After receiving an event about creating a balance for the user and making a request to get user data using the /secure/customers/{customerId} method, we receive the CUSTOMER_NOT_FOUND error.
A: Make sure customer KYC has been accepted.
Q: What happens if a deleted account receives an IBAN transfer?
A: IMS keeps that funds on the IBAN technical balance for refund, Quicko takes care of this.
Transactions
General
Q: Is Google Play treated as a foreign merchant (Poland's POV)?
A: Yes, it's registered in Ireland.
Q: Do we have a possibility to show our client the reason of transaction failure? Currently we can only see status declined or reversed in Admin Panel.
A: No, most of the times we don't know the reason of failure ourselfs - we get declined or reversed status from Tutuka.
Q: Must Force debit/credit transaction method be implemented for physical cards? The possibility of performing off-line transactions is stored on the card chip.
A: Force debit transaction must be implemented in each card issuing project. Force transactions are more than just off-line transactions, f.e. vending machines purchases, self-checkout stores and more.
Q: What data does merchant see when someone pays using our cards?
A: It depends on transaction payment method used. When using:
a) a physical card - the user for whom the card was created (name and surname),
b) a token from xPay when purchasing - data entered during tokenization by the end user,
c) e-com payments - data entered by the user.
Q: What information do we gather when user is paying with tokenized card?
A: We save the information that payment was initialized using token, which external wallet is connected to the mentioned token and last 4 digits of DPAN (Device Primary Account Number).
Clearing
Q: Will you be able to process clearing if the card is irreversibly blocked? Let's say customer blocked the card (with the irreversible reason code) and received a financial transaction (clearing) after that.
A: No new transaction will be authorised. Transactions made before the moment of blocking will be cleared.
Master balance
Q: Does REFUND transaction add money to masterbalance right away?
A: No, Quicko does that during transaction settlements.
Q: Should every credit transaction result in decreasing Masterbalance or companybalance?
A: TBD
Q: How to check if Masterbalance decrease resulted in end user balance topup?
A: The best confirmation of the Masterbalance decrease is a successful top-up of the user’s balance - if client executes the /secure/transactions/credit method, there are 2 options:
- a) they receive 200 + uuid of the registered transaction - that means Masterbalance has been decreased also,
- b) they receive 409 + info “INSUFFICIENT_FUNDS” - which is equivalent to information that there were insufficient funds on Masterbalance to top up user balance.
Q: What method should we use to debit user balance and increase MB balance (for example for crypto selling).
A: POST secure/transactions/debit and transactionType = FUNDING
Q: What if there are not enough funds to cover a /force-debit transaction on Masterbalance?
A: In case of forced transaction, when the transaction amount is greater than the amount on MasterBalance, then the balance will be less than 0 (negative balance).
Quicko will collect the missing funds from the Partner (if Quicko is BIN-sponsor)
Notifier
Q: Differences between THC & Antaca Notifier:
A:
a) transaction notifier from THC API - you will receive information about every movement on the user's balance. In general, THC is a simple, recommended source of transaction history for the enduser point of view.
b) transaction notifier from Antaca - informs about the same as above and additionally about the movements of funds on technical balances (masterbalance/company/ibantechnical) and about transaction events that did not generate a transaction (rejection insufficient funds/limits/etc).
Currently transaction notifier from Antaca is deprecated.
KYC
Q: What's the maximum size of a file send during KYC?
A: Maximum size is 2048 kilobytes per file. Following formats are allowed: jpg, jpeg i png.
Q: Are field usaResident, taxResident, sourceOfFunds required when sending a POST request to /customers/me/register?
A: Yes, they are requierd since 28th of July 2023.
3DS
Q: Client would like to receive codes from 3DS (not via SMS) to their own endpoint. Which endpoint and authentication method should they use?
A: They should use endpoint /notifications/otp and authorize with a certificate.
Q: How 3DS shoud be implemented to be PSD2 compliant? Normally issuers implement either in-app authentication for 2FA or a static password.
A: TBD
External Balance
Q: Differences between id/transactionId/referenceTransactionID
A: ID - value generated for the transaction by our system (Antaca) as UUID.
transactionId - value generated by an external service for the transaction (ID from the processor). For information purposes only, because it may be a non-unique value for different transactions.
referenceTransactionId - Transaction ID of the original transaction f.e. -> of the transaction to be adjusted. The value generated by an external service for the transaction (ID from the processor).
Q: Example of Refund for External Balance:
A: Request: /force-credit or /credit
{"id":"eedb7f17-0ed3-4694-8ca9-227bc38f1420","balanceId":"ba81185e-195e-414d-b4b5-5bce5eeb572e","resourceId":"9754c120-3c7a-4469-ae9c-85d7b94adae3","resource":"card","transactionId":"BE2127E2-G9FC-7281-90BC211BCE5A1732","referenceTransactionId":"65248914100035741256491","type":"adjustment","amount":1000,"currency":"EUR","originalAmount":1000,"originalCurrency":"EUR","status":"AUTHORIZED","description":"Description","date":"2023-01-01T06:30:00+00:00","transactionData":{"mcc":"5311","merchantIdentifier":"837828 ","captureMode":"ADJ","cardId":"111","lastFourDigits":"1234","adjustmentReasonDescription":"REFUND","retrievalReferenceNumber":"928372000000-65248914100035741256491-00006533"}}