# Bank integration

###### tags: `integration`

## Background

To be able to automate the process for bank operation:

1. Deposit automation
2. Withdrawal automation
3. Account opening automation

### Pros

1. Better UX, they can deposit or withdrawal in 7-24 and payment will be realtime
2. Reduce cost of operation
3. Scalability

### Cons

1. Introduce a risk to the system
2. Sometimes it still requires manual approval (AML), so it is not realtime
3. Finance need extra work for bank reconcilation
4. Hard to implement
4.1 security mechanism (Envolop encryption, oauth, process of exchanging the asymmetric key)
4.2 connectivity (Might requires VPN, IP whitelist)
4.3 async process, need to handle the order of transaction event
4.4 reuse the logic from other bank
4.5 Full testing are needed (Required for some bank)

## Assumption and requirements for existing infrastrure

1. Microservices
2. Payment service must be idempotency
3. Low Latency is not a requirement

## What to acheive

1. No payment will be duplicate
2. No payment will be lost
3. Easy to recover from disaster
4. Should be able to support multiple types of interfaces

### Types of interfaces

#### Incoming transaction

1. File server (FTP) Macquarie,
2. Webhook (common, eg. clearbank)
3. Polling api (common)

#### Outgoing transaction

1. Daily file upload (FTP or manual)
2. REST

## Some important points that need to be careful when implementing bank integration module

1. Webhook response status is important
2. Incoming transaction status is async process (i.e cancel event is called to our system before init event)
3. Be careful of the unique reference id provided by bank, some bank claims that the id is unique but actually it is not. (DBS)
4. Outgoing payment type (CHATS, FPS) will impact the transcation fee, need to figure it out what to use for a specific transaction.
5. Suppored currencies of the beneficiary
6. Better to implement the bank reconcilation system as soon as possible
7. Some bank will provide api rate limit. circuit breaker might need to implement

## Design

### Incoming transaction

participant "Bank system" as e
participant BankService as b
participant RDBMS as d
participant Queue as q
participant "System Volume" as s

== Webhook ==

e -> b ++: POST /api/transaction/incoming status=INIT&id=123456&&currency=USD&amount=1.02
b -> s: Write the request to the system process stream output
b -> b: parse & descrypt request
b -> d: INSERT into incoming_transaction (id, bank_id, reference_id, currency, amount, status) \n (1,1,123456,USD,1.02,INIT)
b -> d: INSERT into bank_events (id, bank_id, type, payload, status)\n (1, 1, INCOMING_TRANSACTION, {...json}, PENDING)
b -> d: COMMIT

b --> e --: response 200 OK

== Polling ==

b -> b ++: Time to work
b -> e ++: GET /api/transaction/queue or FTP polling
e --> b --: transactions
b -> s: Write the response to the system process stream output
b -> d: INSERT into incoming_transaction (id, bank_id, reference_id, currency, amount, status) \n (1,1,123456,USD,1.02,INIT)
b -> d: INSERT into bank_events (id, bank_id, type, payload, status)\n (1, 1, INCOMING_TRANSACTION, {...json}, PENDING)
b -> d: COMMIT
b -> b --: end

== Background to sync the transaction to message queue ==

b -> b ++: Time to work
b -> d ++: SELECT * from bank_events FOR UPDATE SKIP LOCKED where status = PENDING 
d --> b --: events
b -> q : Publish events
b -> d ++: UPDATE bank_events SET status = PUBLISHED where id in (...ids)
note left: Will have chance that failed to update event status
d --> b --: 10 rows updated
b -> b --: end

### Outgoing transaction

TODO: no time