---
# System prepended metadata

title: Documentação - Cartão Virtual

---

# 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





