Transfero Cards - CaaS Integration

--- title: 'Transfero Cards - CaaS Integration' --- Transfero Cards - CaaS Integration === ## Purpose Implement the Cards feature as a new service in the CaaS. ## Motivation As a outside-Brazil company, I would like to offer credit cards to my customers in Brazil in order to enforce my brand and introduce it on their day-by-day. Once I already have an integration with Transfero CaaS to process deposits and withdrawals, it sounds good that I can use the same infrastructure to offer cards for my customers without effort of a new integration. ## Entities In this documentation, we are considering the following entities: >- **User**: The final consumer which holds a card. >- **Merchant**: The establishment which sells a product/service to an User. >- **Mastercard**: The global card manufacturer. >- **SWAP**: Card integrator associated to Mastercard. >- **Transfero** > - **QGX Integration**: Application which centralize all business logic specific for cards flow. > - **CaaS**: Transfero platform. >- **Partner**: Target customer from Transfero. These entities are chained as the following diagram: <figure> <img src="https://i.imgur.com/OvFMN5N.png" alt="Albuquerque, New Mexico"> <figcaption style="text-align:center">Figure 1: Entities chain</figcaption> </figure> ## Cards Flow ### 1. Issue a Card When a **User** (or **Partner**) wants to issue a card, the flow is: >1. **Partner** requests a new card to **Transfero** through the API; >2. ***Transfero*** requests this card to **SWAP**; >3. ***SWAP*** emits the card and send to **User** address; >4. **User** receives the card and ask for **Partner** to activate his card; >5. **Partner** requests **Transfero** to activate this card; >5. **Transfero** requests **SWAP** to activate this card; >6. **SWAP** activates the card; >7. The **User** is able to use the card everywhere. :::info :pencil: **Note** In this flow the Transfero will only pass the requests/responses forward and store all required data. ** We need to evaluate if there is any KYC/Compliance issue on this flow.** ::: ### 2. Pay using a card :exclamation::exclamation: Once a **User** holds an activated card, he can pay anything triggering the following flow: >1. **User**1 pass his card in the **Merchant**'s card machine to pay a product. >2. The **Merchant**'s card machine calls **Mastercard**, which calls **SWAP** to approve the *transaction*. >3. **SWAP** identifies that the *transaction* comes from a **Transfero**'s card; >4. **SWAP** checks if **Transfero** has enough balance to process this transaction: > - If yes, **SWAP** calls **Transfero** to approve the *transaction*. > - Else, **SWAP** **rejects** the transaction. >5. **Transfero** identifies that the *transaction* comes from a **Partner**A's card; >6. **Transfero** checks if **Partner**A has enough balance to process this transaction: > - If yes, **Transfero** calls **Partner**A to approve the *transaction*. > - Else, **Transfero** **rejects** the transaction. >7. **Partner**A identifies that the *transaction* comes from a **User**1's card; >8. **Partner**A checks if **User**1 has enough balance to process this transaction: > - If yes, **Partner**A **approves** the transaction. > - Else, **Partner**A **rejects** the transaction. >9. The approval (approved or rejected) is sent back through the entire chain until the **Merchant**'s card machine. :::info :exclamation: **Warning** All approval chain must take an average of ***1 second***. If it takes more time than expected, the transaction is rejected automacally by the first stages. ::: ## Proposal The proposal is under **Transfero** scope, which includes two components: **QGX Integration** and **CaaS**. ### Responsibilites Before proposing the changes, let us define the responsibilities of each component: * **QGX Integration** >* Integration with **SWAP** API. >* Implement all logic specific for cards: > * Store all cards informations. > * Cards list for partner. > * Active/Blocked cards. > * Info regarding card holder. >* Store all transcations partitioned by card. >* **Cards Backoffice** for the Support and Operations teams. * **CaaS** >* KYP. >* Partner Balance. >* Fee charging. >* Transaction register at Partner level. >* Partner authorization. >* "Front door" of the solution. ### Proposed Changes We are proposing the following changes: 1. Create a new service in **CaaS** Core: >* **Name** > * `transferocaas-card-service` > >* **Responsibilities**: > * Bypass all card requests from **CaaS** API to **QGX Integration** > * Check and lock partner balance in the [approval flow](#2-Pay-using-a-card-). > * Call partner API in the [approval flow](#2-Pay-using-a-card-). > * Send debit transaction creation request to *transactions queue*. > * Create fee transaction request and send *transactions queue*. > >* **Dependencies**: > * Cosmos DB (openbanking collection): > * Read *Account* document and run *Balance* procedures. > * Service Bus Queue: > *adapter-send-transaction-openbanking; > >* **Services/Apps** > - **QGX Integration** API. > - **Partner** API (in [approval flow](#2-Pay-using-a-card-)); 2. Update **CaaS** model: > * **Entity** - Enum PaymentGroupType >* **Change** - Add new value: `Card` 3. Add the following endpoints in the CaaS API: > **GET** /api/v1/account/{accountId}/card > **GET** /api/v1/account/{accountId}/card/virtual/{cardId} > **GET** /api/v1/account/{accountId}/card/physical/{cardId} > **POST** /api/v2/account/{accountId}/card/physical > **POST** /api/v2/account/{accountId}/card/virtual > **POST** /api/v2/account/{accountId}/card/activate > **POST** /api/v2/account/{accountId}/card/link (?) > **PUT** /api/v1/account/{accountId}/card/{cardId}/block > **PUT** /api/v1/account/{accountId}/card/{cardId}/unblock ### Proposed Flow - CaaS * Consider the following scenario: >1. The **partner** *Wirex* is an active user of **CaaS**. >2. They have following accounts: > - **401** - BRL Account > - **402** - BRZ Account > - **403** - USDT Account >3. They have used the **CaaS** to perform the following actions: > - Process BRL deposits > - Trade between FIAT/Crypto currencies > - Process FIAT and Cryptos withdrawal * For enabling this **Partner** to process cards, we will need: >1. Register this **Partner** in the **QGX Integration**. (*we need more info about the requirements here.*) >2. Create a new Account in the **CaaS** containing: > * **Currency**: BRL > * **PaymentGroupType** (Payout): Card > * Fees > * **Example**: *"404 - BRL | Card Account"* >3. Grant roles to **Partner** be able to access the Cards endpoint in the CaaS API. * After this setup, the Partner will be able to issue and activate cards for their **user**s. * When the **CaaS** receives an approval request for card *transactions* ([approval flow](#2-Pay-using-a-card-)), it will trigger the following flow: >1. Check if the Card account have enough balance; >1. Lock transaction amount from balance; >2. Send approval request for **Partner** registered URL: > * If **partner** returns approved status: > 1. Retrieve the status back; > 2. Send transaction request to queue; > 3. Calculate fee and send fee transaction request to queue. > * If **partner** returns rejected status: > * 1. Retrieve the status back; > * 2. Unlock locked balance. :::info :pencil: **Note** The partner must feed the **Card Account** to process the cards transactions. He can use the **Transfer endpoint** to transfer funds between his main BRL account and the card specific one. ::: ## Project Timeline ```mermaid gantt title A Gantt Diagram section Section A task :a1, 2014-01-01, 30d Another task :after a1 , 20d section Another Task in sec :2014-01-12 , 12d anther task : 24d ``` > Read more about mermaid here: http://mermaid-js.github.io/mermaid/ ## Appendix :::info **Links here!** :::