Card Management System

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.

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}/register 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/{userId}/register' \
                                 --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'

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"
                                 }'

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.

Collection	URL	Authentication	Encryption required	Available for admin roles
Customer	POST /customers/me/cards/virtual or for an asynchronous process POST /customers/me/cards/virtual/async	Session token	YES* - JWE *for an asynchronous process NO	N/A
Admin	POST /admin/customers/{customerId}/cards/virtual	Session token	YES* - JWE	Admin, Manager
API	POST /secure/customers/{customerId}/cards/virtual or for an asynchronous process POST /secure/customers/{customerId}/cards/virtual/async	x509 certificate	YES* - JWE *for an asynchronous process NO	N/A

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

Collection	URL	Authentication	Encryption required	Available for admin roles
Customer	POST /customers/me/cards/{cardId}/lock	Session token	NO	N/A
Admin	Administrator blocks the card through the core of the administration panel	N/A	N/A	N/A
API	POST /secure/customers/{userId}/cards/{cardId}/lock	x509 certificate	NO	N/A

Collection	URL	Authentication	Encryption required	Available for admin roles
Customer	POST /customers/me/cards/{cardId}/unlock	Session token	NO	N/A
Admin	Administrator unblocks the card through the core of the administration panel	N/A	N/A	N/A
API	POST /secure/customers/{userId}/cards/{cardId}/unlock	x509 certificate	NO	N/A

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

Parameter	Required	Description	Type
storageCustomerId	TRUE	Customer identifier	integer value
storageCardId	TRUE	Card identifier	integer value
balanceId	TRUE	User balance identifier	uuid v4
amount	TRUE	Transaction value in gross (minor value)	integer value
currency	TRUE	Currency 3-letters code in ISO 4217 https://www.iban.com/currency-codes	ISO 4217 3-letter code
merchantName	TRUE	Merchant name	string value
otp	TRUE	One time password	string value

Parameter	Required	Description	Type
verificationId	TRUE	Verification identifier	uuid v4
userId	TRUE	User identifier	integer value
email	TRUE	User's email address	string value
firstName	TRUE	User first name	string value
lastName	TRUE	User last name	string value
status	TRUE	Verification status. Possible values: REJECTED IN_PROGRESS ACCEPTED	string value
reason	TRUE	Verification status reason ACCEPTED: null IN_PROGRESS: null REJECTED: INVALID_CUSTOMER_DATA BLURRED_DOCUMENT_PHOTO INVALID_DOCUMENT_PHOTO BLURRED_SELFIE INVALID_SELFIE	null/string value

Parameter	Required	Description	Allowed values
balanceId	TRUE	Unique user balance identifier	any string value (recommended uuid v4)
resourceId	TRUE	Unique resource identifier	any string value (recommended uuid v4)
resource	TRUE	Name of a resource.	balance, card
transactionId	TRUE	Transaction identifier obtained from card netwok or generated on client side using the method to generate transaction in Antaca. IMPORTANT: this id may not be unique - it is generated by different systems	any string value (recommended uuid v4)
referenceTransactionId	FALSE	Id of previous transaction to witch current request relates	any string value (recommended uuid v4)
type	TRUE	Type of transaction	cashback, loan, payment, topup, commision, fee, funding, interest, withdrawal, POS, ATM, Cashback at POS
amount	TRUE	Transaction value in gross (minor value)	integer value
currency	TRUE	Currency 3-letters code in ISO 4217	ISO 4217 3-letter code
originalAmount	FALSE	Original transaction value in gross (minor value)	integer value
originalCurrency	FALSE	Original currency 3-letters code in ISO 4217	ISO 4217 3-letter code
status	TRUE	Transaction status	AUTHORIZED, CLEARED, REVERSED
descripion	TRUE	Transaction description	any string value
date	TRUE	Date of transaction in UTC	date in UTC
transactionData	FALSE	Additional transaction data. This object presents detailed data depending on the transaction type	This object is described below

Parameter	required	description	allowed values
mcc	FALSE	Merchant category code	any mcc value, eg. can be found here: https://global.alipay.com/docs/ac/files/mcclist
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

Parameter	Required	Description	Allowed values
status	TRUE	Status of the transaction processing. SUCCESS - indicates that the transaction has been successfully processed in Antaca. DECLINED - indicates that the transaction has been declined. INVALID - indicates that the transaction can't be processed.	SUCCESS, DECLINED, INVALID
date	TRUE	Date time of request generation in ISO 8601 date	ISO 8601 date, eg. 2023-11-16T13:41:40+00:00
description	TRUE	Describes more details for returned status	describes in description section details
transaction	TRUE	The transaction properties	transaction object described in the transaction object section

value	description
APPROVED	Indicates a successful transaction. Antaca processed the transaction with no errors.
EXCEEDS_AMOUNT_LIMIT	Occurs when the transaction amount exceeds card limits.
INSUFFICIENT_FUNDS	There is not enough money on balance.
CARD_NOT_FOUND	Antaca cannot find card for which the transaction was invoked.
BALANCE_NOT_FOUND	Antaca cannot find balance for which the transaction was invoked.
INVALID_AMOUNT	Amount of the transaction was passed as <= 0.
INSUFFICIENT_FUNDS_ON_DEPOSIT_BALANCE	Deposit balance has not enough funds to process the transaction.
DEPOSIT_BALANCE_NOT_FOUND	Occurs when client has not configured deposit balance in currency used for rejected the transaction.
AML_EXCEPTION	Aml regulations does not allow to process the transaction.
AMBIGUOUS_REFERENCED_TRANSACTION	Antaca cannot determine for which a transaction refer current the transaction request. System has found more then one transaction matched by transaction parameters.
REFERENCED_TRANSACTION_NOT_FOUND	System cannot find any transaction for which the request refer.
CURRENCY_MISMATCH	The transaction currency is different than balance currency.
CUSTOMER_NOT_FOUND	System cannot find customer who is involved in the transaction.
BUDGET_EXCEEDED	The budget limitation for an card or an customer has been exceeded.
LIMIT_EXCEED	General limitation for the transaction has been exceeded.
COLLATERAL_BALANCE_NOT_FOUND	System cannot find an collateral balance in proper currency configured for client instance. Those balances could be eg. deposit, credit, technical etc.
INSUFFICIENT_FUNDS_ON_COLLATERAL_BALANCE	An collateral balance has not enough funds to process transaction request.
UNKNOWN_TRANSACTION_TYPE	System cannot determine kind of the transaction and reject it for security reason.
UNKNOWN_ERROR	General error. System cannot match any of concrete description.

Card Management System

Introduction

Create User

White Label Application

Mobile SDKs

Life Cycle API

KYC

Manual KYC Process

Automatic eKYC

External KYC

Create Balance

Automatic

Manual

Create Card

Intro slides

Overview

Introduction to Card Issuing process

Terminology

Configuration & JWE Security

Additional data encryption & integration

JWE configuration

User Lifecycle API & SDK

User registration & KYC

Create User Balance

Card issuing

Digital card

Physical card

Digital-first card

Actions

Create virtual

Lock

Unlock

Remove

Get full data

Reset CVV

Order physical card

Link card

Print virtual

Set PIN

Activate card

Lock outside

More information on Partner Balances and Deposit Requirements

Partner Balance

Partner Credit Balance

Partner Deposit Balance

Balance Summary in Administration Panel

Users

Wallet

Actions

Create user balance

Create Partner Deposit Balance or Partner Credit Balance

Get User Balance

Get Partner Deposit Balance or Partner Credit Balance

Reload Partner Deposit Balance or Partner Credit Balance

Reload user balance

Fee management

Other functionalities

Quick start

Add user.

Create user verification form.

Create user balance.

Create new virtual card.

Your APIs for us

Security

Additional data encryption & integration

Idempotency Key

JWE configuration

Public Key

3DS External OTP Notifier

API 3DS External OTP Notifier

Notification OTP

External verification Notifier

Notification verification In-progress

Notification verification accepted

Notification verification rejected

External Balance

Feautres

Purpose and scope

Terminology

External Balance API

Design Specifications for Graphic Designers  and Customers Required for the MDES Manager Application