---
###### tags: `Banks`
---
# Tatra Banka API Pilot 2
| Version |Date |Author | Comment |
| ------------- |---------- |------------- | ---------|
|0.1 |27.06.2019 |Alexey Krichun | Initial proposition
|0.2 |01.07.2019 |Alexey Krichun | Update after review
|0.2.1| 02.07.2019| Daniel Meltzer| add iOS part|
|0.3| 03.07.2019| Alexey Krichun, Daniel Meltzer| Changed BalanceData field types|
|0.4| 15.07.2019| Alexey Krichun| Update PayKeyErrorFactory, authRequiredError, autorizePayment|
|0.5| 18.07.2019| Oleksii Serha| Update setup api call, authRequiredError(), wrongPinError()|
|0.6| 19.07.2019| Andrey Savitskiy| Update errors api call, authRequired:, wrongPinError:|
|0.7| 24.07.2019| Oleksii Serha| added new error - missingContactPermissionError()|
|0.8| 13.08.2019| Andrey Savitskiy| Replace authorizePayment: completion block|
|0.9| 14.08.2019| Evgen Sagidulin| Added `redirectionUri` parameter to TATRASetupData model|
|0.10| 03.09.2019| Andrey Savitskiy| Updated `bankTempOOSError` method in error factory|
|0.11| 04.09.2019| Andrey Savitskiy, Oleksii Serha| Updated `TBSetupData` for Android and IOS|
This is a general callback interface, will be used across the documentation.
#### Android
```java
interface CompletionCallback<DATA> {
void onSuccess();
void onSuccess(DATA data);
void onError(Error error);
}
```
#### iOS will be using blocks
## 1. Flow Lifecycle
### 1.1 Flow Started
This method is invoked each time a flow starts, after tapping the PayKey button.
#### Android
```java
void onFlowStart(Context context);
```
#### iOS
```objectivec=
- (void)onFlowStart;
```
### 1.2 Flow Ended
This method is invoked each time a flow ends, after user aborts the flow by tapping exit button or close of keyboard.
#### Android
```java
void onFlowStop(Context context);
```
#### iOS
```objectivec=
- (void)onFlowStop;
```
## 2. Flow Action Interface Methods
### 2.1 Setup
This call will provide the setup data for the available flows.
#### Android
```java=
void setup(CompletionCallback<TBSetupData> completion);
class TBSetupData {
Boolean isActivated;
String descriptionValidationRegex;
String phoneValidationRegex;
int descriptionValidationLength;
BigDecimal minTransactionAmount;
BigDecimal maxTransactionAmount;
Uri redirectionUri;
}
```
#### iOS
```objectivec=
- (void)fetchSetupData:(nonnull TATRAFetchSetupDataCompletionBlock)completion;
typedef void (^TATRAFetchSetupDataCompletionBlock)(__kindof PKError *_Nullable error, TATRASetupData * _Nonnull setupData);
```
```objectivec=
@interface TATRASetupData : PKSetupData
@property (nonatomic, copy) NSString* descriptionValidationRegex;
@property (nonatomic, copy) NSNumber* descriptionValidationLength;
@property (nonatomic, copy) NSString* phoneValidationRegex;
@property (nonatomic, assign) BOOL isActivated;
@property (nonatomic, copy) NSString* redirectionUri;
+ (instancetype)setupDataWithDescriptionValidationRegex:(NSString*)descriptionRegex
descriptionLength:(NSNumber*)length
phoneValidationRegex:(NSString*)phoneRegex
isActivate:(BOOL)isActivate
amountValues:(PKAmountValues*)amountValues
redirectionUri:(NSString*)redirectionUri;
@end
```
```objectivec=
@interface PKSetupData : NSObject <NSCoding>
@property (nonatomic, readonly) PKAmountValues* makePaymentValues;
+ (instancetype)setupDataWithAmountValues:(PKAmountValues*)amountValues;
@end
```
```objectivec=
@interface PKAmountValues : NSObject<NSCoding>
@property (nonatomic, readonly) NSNumber* minValue;
@property (nonatomic, readonly) NSNumber* maxValue;
+(instancetype)amountWithMinValue:(NSNumber *)minValue
maxValue:(NSNumber *)maxValue;
@end
```
### 2.2 Errors
Each api call can return an error. Each error type will show a different screen or a behavior in the flow.
### 2.2.1 Fatal Error
This error is irrecoverable. The user will be able to exit the flow.
### 2.2.2 Error Factory
A factory with the required errors will be provided as part of the SDK.
Additional errors can be created programatically using the `Error` class.
#### Android
```java=
class PayKeyErrorFactory {
static Error generalError(String title, String message);
static Error authRequiredError(String title, boolean showConditions);
static Error executePaymentError(String title, String message);
static Error amountLimitError(String title, String message);
static Error sameRecipientError(String title, String message);
static Error serviceUnavaiableError(String title, String message);
static Error networkError(String title, String message);
static Error wrongPinError(String title, boolean applicationBlocked);
static Error bankTempOOSError(String paymentId);
static Error missingContactPermissionError(String title, String subtitle, Uri uri);
}
```
#### iOS
```objectivec
@interface TATRAErrorFactory : NSObject
+(PKError*)generalError:(NSString*)title message:(NSString*)message;
+(PKError*)executePaymentError:(NSString*)title message:(NSString*)message;
+(PKError*)amountLimitError:(NSString*)title message:(NSString*)message;
+(PKError*)sameRecipientError:(NSString*)title message:(NSString*)message;
+(PKError*)serviceUnavaiableError:(NSString*)title message:(NSString*)message;
+(PKError*)networkError:(NSString*)title message:(NSString*)message;
+(PKError*)authRequired:(NSNumber*)showConditions title:(NSString*)title;
+(PKError*)wrongPinError:(NSNumber*)applicationBlocked title:(NSString*)title;
+(PKError*)bankTempOOSError:(NSString *)paymentId;
@end
```
## 3. Contacts
### 3.1 Top Contacts
This api call will retrieve the list of top contacts to be presented
#### Android
```java
void getTopContacts(CompletionCallback<List<TTContact>> completion);
class TTContact {
String fullName;
String phone;
Uri image;
}
```
#### iOS
```objectivec=
- (void)fetchTopContacts:(nonnull TATRAContactsCompletionBlock)completion;
typedef void (^TATRAContactsCompletionBlock)(__kindof PKError *_Nullable error, NSArray<TATRAContact*> * _Nonnull contacts);
```
TATRAContact
```objectivec=
@interface TATRAContact : PKContact
@property (nonatomic, strong, nullable) UIImage* icon;
@property (nonatomic, strong) NSString* fullName;
@end
```
PKContact
```objectivec=
@interface PKContact : NSObject <PKContact, NSCoding>
@end
@protocol PKContact <NSObject>
@property (nonatomic, strong) NSArray<PKPhoneNumber*>* phones;
@end
```
### 3.2 Additional Contacts
This api call will return a list of all contacts to be presented in a contact list
#### Android
```java
void getContacts(CompletionCallback<List<TTContact>> completion)
```
#### iOS
```objectivec=
- (void)fetchContacts:(nonnull TATRAContactsCompletionBlock)completion;
typedef void (^TATRAContactsCompletionBlock)(__kindof PKError *_Nullable error, NSArray<TATRAContact*> * _Nonnull contacts);
```
## 4. Payment
### 4.1 Execute Payment
This api call will provide the gathered details collected during the user journey.
The returned string will hold the text to be presented on the authentication screen.
#### Android
```java
void executePayment(TransactionRequest details, CompletionCallback<String> completion)
class TransactionRequest {
BigDecimal amount;
String messageForRecipient;
TTContact recepient;
}
```
#### iOS
```objectivec=
- (void)executePayment:(TATRARequest* _Nonnull)request completion:(nonnull TATRAPaymentCompletionBlock)completion;
typedef void (^TATRAPaymentCompletionBlock)(__kindof PKError *_Nullable error, NSString* _Nullable confirmationString);
@interface TATRARequest : NSObject
@property (nonatomic, strong) TATRAContact* contact;
@property (nonatomic, strong) NSNumber* amount;
@property (nonatomic, copy) NSString* reference;
@end
```
### 4.2 Payment Authorization
This api call will provide the auth data entered by the user for authentication.
The returned string will be pated to the input field to share with a receiver.
#### Android
```java
void authorizePayment(AuthData data, CompletionCallback<String> completion);
class AuthData {
String pincode;
}
```
#### iOS
```objectivec=
- (void)authorizePayment:(NSString* _Nonnull)pincode completion:(nonnull TATRAPaymentCompletionBlock)completion;
typedef void (^TATRAPaymentCompletionBlock)(__kindof PKError *_Nullable error, NSString* _Nullable confirmationString);
```
### 4.3 Resubmit Payment
If the `authorizePayment` request returns the `bankTempOOSError`, a confirmation screen will be shown and if users selects to retry the payment, the following API call will be called:
#### Android
```java
void resubmitPayment(String paymentId, CompletionCallback<String> completion)
```
#### iOS
```objectivec=
- (void)resubmitPayment:(NSString* _Nonnull)paymentId completion:(nonnull TATRAPaymentCompletionBlock)completion;
```
## 5. Account Balance
This API call will return the current balance data.
#### Android
```java
void getBalance(CompletionCallback<BalanceData> completion)
class BalanceData {
BigDecimal balance;
Date dueDate;
}
```
#### iOS
```objectivec=
-(void)fetchBalance:(TATRABalanceCompletionBlock _Nonnull)completion;
typedef void (^TATRABalanceCompletionBlock)(__kindof PKError *_Nullable error, TATRABalanceData* _Nullable balanceData);
@interface TATRABalanceData : NSObject
@property (strong,nonatomic)NSNumber* balance;
@property (strong,nonatomic)NSDate* dueDate;
@end
```
## 6. Get IBAN
This API call will return the IBAN.
#### Android
```java
void getIban(CompletionCallback<String> completion)
```
#### iOS
```objectivec=
- (void)getIban:(nonnull TATRAIBANCompletionBlock)completion;
typedef void (^TATRAIBANCompletionBlock)(__kindof PKError *_Nullable error, NSString* _Nullable iban);
```
## 7. Authorization
If the authorization is required on `getBalance()` or `getIban()` calls, these calls should return an 'Auth Required' error (created by `ErrorFactory.authRequiredError()`/`[TATRAErrorFactory authRequired]` . The user will enter the PIN code and the following API call will be called:
#### Android
```java
void authorize(AuthData data, CompletionCallback<Void> completion)
```
#### iOS
```objectivec=
- (void)authorize:(NSString* _Nonnull)pincode completion:(nonnull TATRAGeneralCompletionBlock)completion;
```
Sign in with Wallet
Connect another wallet