# Documentação - Cartão Virtual

_De modo a melhorar a ativação de conta, reduzir custos logísticos e incentivar compras online, temos agora uma experiência digital através de uma API de geração de Cartão Virtual, que funciona no mesmo formato dos cartões físicos, nos processos de liquidação e compra. Contendo todas as etapas de: emissão, visualização, cancelamento, bloqueio e desbloqueio, e essa feature na chamada API também é atrelada ao two-factor authentication (2FA), etapas para garantir a segurança da operação._

# Épica

### [BCARDS-22] Cartão Virtual

### Histórias

- **[BCARDS-41] Criar/Ativar Cartão Virtual**
- **[BCARDS-56] Visualizar Cartão Virtual**
- **[BCARDS-58] Bloquear Cartão Virtual**
- **[BCARDS-59] Desbloquear Cartão Virtual**
- **[BCARDS-57] Cancelar Cartão Virtual**

# [BCARDS-41] Criar Cartão Virtual

Nesta task foi criado o endpoint de criação do cartão virtual.
Esse endpoint deve receber o identificador(ID) do Marktplace e o Identificador(ID) do Holder.

O Marketplace faz a chamada _POST_ no endpoint **/marketplaces/{marketplaceId}/holders/{holderId}/cards/requests/virtual** para geração do Cartão Virtual.

_e o "Body" recebe os seguintes requerimentos:_

{
"account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"address_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"card_type": "string",
"embossing_policy_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6"
"phone_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"printed_card_name": "string"
}

Será esperado um status de resposta da API, para solicitação de cartão criado com sucesso será:

- 201 CREATED ⇾ Cartão Criado

_Exemplo de resposta do "Body":_

{
"external_key": "bab06abb9ebf44ec924dade0c04c0de8",
"account_id": "cf245b18890a4ea4b23b27390a02bebc",
"holder_id": "83593676f28b470da41160269a54060c",
"marketplace_id": "f71a8951368a4cc085cf7875ff44e61c",
"printed_card_name": "EXAMPLE CARD",
"status": "PENDING",
"created_at": "2021-06-28T10:51:33.7675467",
"updated_at": "2021-06-28T10:51:33.8447605",
"uri": "/marketplaces/f71a8951-368a-4cc0-85cf-7875ff44e61c
/holders/83593676-f28b-470d-a411-60269a54060c/cards/bab06abb-9ebf-44ec-924d-ade0c04c0de8",
"embossing_policy_id": "7710a903853b41bba678a347a1adcc6e",
"card_type": "VIRTUAL"
}

E o status de resposta da API com falha será:
- 404 NOT_FOUND ⇾ O `marketplaceId` ou `holderId`, ou política de embossamento não foram encontrados

____

_Informações importantes sobre criação do cartão:_

- O Cartão Virtual não tem senha
- Deve ser retornado um número aleatório de cartão atrelado à conta do cliente
- Esse cartão deve apresentar as seguintes informações:
- Número do Cartão
- Nome do Holder
- Data de Validade
- CVV (o código de segurança).
- Para data de validade do cartão utilize: MM/yyyy, sendo yyyy = ano corrente + 5, por exemplo: se o ano corrente é 2020, a data de validade deverá ser 01/2025.
- O valor do CVV pode ser qualquer valor numérico com três dígitos obrigatoriamente.
- Exceto pelo fato do cartão virtual não ter senha e sua a validação se dar pelo CVV, ele se comporta exatamente como um cartão físico, podendo ser utilizado em praticamente todos os fluxos de compra.
- O Cartão não funcionará em POS físicos, ou seja, não serão aprovadas compras digitadas em ambientes físicos, somente em E-commerces, aplicativos e serviços recorrentes.
- O cartão virtual, após gerado, não terá expiração após uma compra, e sim uma data de validade.
- A Zoop não armazenará os dados do Cartão, porém salva a quantidade de cartões gerados por estabelecimentos comerciais (Holders) e por Marketplace, bem como o valor transacionado.
- O Cartão Virtual é criado pelo sistema da Dock e retornado na nossa API para informar o Marketplace.
- Todos os cartões virtuais são bloqueados quando criados. É necessário desbloqueá-lo para começar a usar. O cartão ficara em espera em uma categoria de "análise", seguindo para pendente e assim encaminhado para o usuário fazer a ativação. 

## [BCARDS-41] Ativar Cartão Virtual
Nesta task foi criado o endpoint de ativação do cartão virtual.
Esse endpoint deve receber o identificador(ID) do Marktplace, o Identificador(ID) do Holder e o ExternalKey(identificador do cartão).

O Marketplace faz a chamada _POST_ no endpoint **/marketplaces/{marketplaceId}/holders/{holderId}/cards/{externalKey}/activate/virtual** para ativação do cartão virtual.

_e o "Body" recebe o seguinte requerimento:_

{
"password": "string"
}

Será esperado um status de resposta da API, para solicitação de cartão ativado com sucesso será:

- 200 OK ⇾ Cartão Ativado com Sucesso

E retornando uma resposta.
_Exemplo de resposta do “Body”:_

{
"account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"card_type": "string",
"created_at": "2021-06-28T15:53:21.218Z",
"embossing_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"expiration_date": "2021-06-28",
"external_key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"holder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"marketplace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pan": "string",
"reason": "string",
"status": "string",
"updated_at": "2021-06-28T15:53:21.218Z",
"uri": "string"
}

E o status de resposta da API com falha será:

- 404 NOT_FOUND ⇾ O `marketplaceId`, `holderId` ou `externalKey` não representam um cartão virtual.
- 412 PRECONDITION_FAILED ⇾ Uma condição prévia falhou, como uma conta bancária inválida ou o cartão não estava no status "PENDING" ao chamar o endpoint.

# [BCARDS-56] Visualizar Cartão Virtual

Nesta task foi criado o endpoint de visualização do cartão virtual.
Esse endpoint deve receber o identificador(ID) do Marktplace, o Identificador(ID) do Holder e o ExternalKey(identificador do cartão).

O Marketplace faz a chamada _GET_ no endpoint **/marketplaces/{marketplaceId}/holders/{holderId}/cards/{externalKey}/virtual** para visualização dos detalhes do cartão virtual.

Será esperado um status de resposta da API, para solicitação de visualizar cartão com sucesso será:

- 200 OK ⇾ Cartão encontrado com sucesso.

O Corpo da resposta contém os dados do cartão.

_Exemplo de resposta do “Body”:_

{
"account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"card_number": "string",
"card_type": "string",
"created_at": "2021-06-28T19:33:56.024Z",
"cvv": "string",
"embossing_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"expiration_date": "string",
"external_key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"holder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"marketplace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pan": "string",
"plastic_name": "string",
"reason": "string",
"status": "string",
"updated_at": "2021-06-28T19:33:56.024Z",
"uri": "string"
}

E o status de resposta da API com falha será:

- 404 NOT_FOUND ⇾ O `marketplaceId`, `holderId` ou o `externalKey` não representam um cartão virtual.
- 412 PRECONDITION_FAILED ⇾ Uma condição prévia falhou, como uma conta bancária inválida.

# [BCARDS-58] Bloquear Cartão Virtual

Nesta task foi criado o endpoint de bloqueio do cartão virtual. Esse endpoint deve receber o identificador(ID) do Marktplace, o Identificador(ID) do Holder e o ExternalKey(identificador do cartão).

O Marketplace faz a chamada _POST_ no endpoint
**/marketplaces/{marketplaceId}/holders/{holderId}/cards/{externalKey}/block/virtual** para fazer o bloqueio do cartão virtual.

_e o "Body" recebe o seguinte requerimento:_

{
"observation": "string"
}

Será esperado um status de resposta da API, para cartão bloqueado com sucesso será:

- 202 Accepted ⇾ Uma solicitação de bloqueio foi recebida para o cartão virtual fornecido.

_Exemplo de resposta do “Body”:_

{
"external_key": "70f5710822ba4642985a2b0bd9b30820",
"account_id": "cf245b18890a4ea4b23b27390a02bebc",
"holder_id": "83593676f28b470da41160269a54060c",
"marketplace_id": "f71a8951368a4cc085cf7875ff44e61c",
"pan": "4475********4867",
"expiration_date": "2026-12-31",
"status": "BLOCKED",
"created_at": "2021-06-28T11:06:10.924589",
"updated_at": "2021-06-28T11:07:09.2961585",
"uri":"/marketplaces f71a8951-368a-4cc0-85cf-7875ff44e61c/holders/83593676-f28b-470d-a411-60269a54060c cards70f57108-22ba-4642-985a-2b0bd9b30820",
"embossing_policy_id":"7710a903853b41bba678a347a1adcc6e",
"card_type": "VIRTUAL"
}

E o status de resposta da API com falha será:

- 404 NOT_FOUND ⇾ O `marketplaceId`, `holderId` ou o `externalKey` não representam um cartão virtual.
- 412 PRECONDITION_FAILED ⇾ Uma pré-condição falhou, como o cartão estando em um estado que não pode ser bloqueado.

_Informações importantes sobre bloqueio de cartão:_

- Enquanto o cartão está bloqueado, não é possível realizar operações com ele.
- Para realizar o bloqueio, basta o Marketplace chamar a API de bloqueio **/block/virtual** identificando o cartão, holder e justificar o motivo do bloqueio com no máximo 100 caracteres.

# [BCARDS-59] Desbloquear Cartão Virtual

Nesta task foi criado o endpoint de desbloqueio do cartão virtual.
Esse endpoint deve receber o identificador(ID) do Marktplace, o Identificador(ID) do Holder e o ExternalKey(identificador do cartão).

O Marketplace faz a chamada _POST_ no endpoint **/marketplaces/{marketplaceId}/holders/{holderId}/cards/{externalKey}/unblock/virtual** para desbloqueio do cartão virtual.

Será esperado um status de resposta da API, para solicitação de desbloqueio de cartão com sucesso será:

- 202 ACCEPTED ⇾ Uma solicitação de desbloqueio foi recebida para o cartão virtual fornecido

E retornando uma resposta.
_Exemplo de resposta do “Body”:_

{
"external_key": "70f5710822ba4642985a2b0bd9b30820",
"account_id": "cf245b18890a4ea4b23b27390a02bebc",
"holder_id": "83593676f28b470da41160269a54060c",
"marketplace_id": "f71a8951368a4cc085cf7875ff44e61c",
"pan": "4475********4867",
"expiration_date": "2026-12-31",
"status": "ACTIVE",
"created_at": "2021-06-28T11:06:10.924589",
"updated_at": "2021-06-28T11:07:42.2776369",
"uri": "/marketplaces/f71a8951-368a-4cc0-85cf-7875ff44e61c/holders/83593676-f28b-470d-a411-60269a54060c/cards/70f57108-22ba-4642-985a-2b0bd9b30820",
"embossing_policy_id": "7710a903853b41bba678a347a1adcc6e",
"card_type": "VIRTUAL"
}

E o status de resposta da API com falha será:

- 404 NOT_FOUND ⇾ O `marketplaceId`, `holderId` ou o `externalKey` não representam um cartão virtual.
- 412 PRECONDITION_FAILED ⇾ Uma pré-condição falhou, como o cartão estando em um estado que não pode ser desbloqueado.

_Informações importantes sobre desbloqueio de cartão:_

- Para o desbloqueio de qualquer cartão é chamando a API de desbloqueio da Dock: **https://caradhras.dock.tech/v1/cards/create-cartoes-desbloquear**
- Após o processo de desbloqueio o cartão pode ser usado novamente para realização de operações

# [BCARDS-57] Cancelar Cartão Virtual

Nesta task foi criado o endpoint de cancelamento do cartão virtual.
Esse endpoint deve receber o identificador(ID) do Marktplace e o Identificador(ID) do Holder.

o Marketplace faz a chamada _POST_ no endpoint **/marketplaces/{marketplaceId}/holders/{holderId}/cards/{externalKey}/cancel/virtual** para cancelamento do cartão virtual

_e o "Body" recebe o seguinte requerimento:_

{
"observation": "string"
}

Será esperado um status de resposta da API, para solicitação de cancelamento do cartão com sucesso será:

- 200 OK ⇾ Cartão cancelado com sucesso

_Exemplo de resposta do “Body”:_

{
"account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"card_type": "string",
"created_at": "2021-06-28T18:23:05.534Z",
"embossing_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"expiration_date": "2021-06-28",
"external_key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"holder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"marketplace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pan": "string",
"reason": "string",
"status": "string",
"updated_at": "2021-06-28T18:23:05.534Z",
"uri": "string"
}

E o status de resposta da API com falha será:

- 404 NOT_FOUND ⇾ O `marketplaceId`, `holderId` ou o `externalKey` não representam um cartão virtual.
- 412 PRECONDITION_FAILED ⇾ Uma pré-condição falhou, como o cartão estando em um estado que não pode ser cancelado.

_Informações importantes sobre cancelamento de cartão:_

- Cancelar o cartão virtual não cancela o cartão físico, vice e versa.

___

# Status do Cartão Virtual

| Status | Descrição |
| -------- | -------- |
|`PENDING` |Quando está em trânsito para o domicilio do holder ou pendente de ativação
`ACTIVE` |Quando está pronto para ativação e pode ser utilizado livremente pelo holder
`BLOCKED` |Quando o cartão não pode ser temporariamente utilizado mas é reversível
`CANCELED` |Quando o cartão não pode ser mais utilizado e está cancelado definitivamente
`DENIED` |Quando a solicitação do cartão é negada no processo de onboarding da Dock
`WAITING_CORRECTIONS` |Quando a Dock detecta erros semânticos nos dados cadastrais do holder
`WAITING_ANALYSIS` |Quando a análise dos dados para onboard ainda não está concluída
`ERROR` | Quando há um erro sistêmico no pedido desse cartão, seja Dock ou Zoop

# Glossário

* 2FA : Two-factor authentication - Garante que serão necessários dois fatores únicos para liberação da transação
* POS : Point Of Sales - Ponto de Vendas, local onde ocorre uma transação de venda.
* API : Application Programming Interface - É um conjunto de normas que possibilita a comunicação entre plataformas através de uma série de padrões e protocolos