---
# System prepended metadata

title: 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.

**<span style="color:red"> We need to evaluate if there is any KYC/Compliance issue on this flow.</span>**
:::

### 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** <span style="color:red">**rejects**</span> 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** <span style="color:red">**rejects**</span> 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 <span style="color:green">**approves**</span> the transaction.
>    - Else, **Partner**A <span style="color:red">**rejects**</span> 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!**
:::
