---
# System prepended metadata

title: Tatra Banka API Pilot 2
tags: [Banks]

---

---
###### 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;
```