# QI Tech — Banking-as-a-Service › Gestão de cartões pré-pago
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
17 página(s).
Índice:
- Requisição de Autorização (Opcional) (/documentation/cards/autorizacao/)
- Simulação de autorização (/documentation/cards/autorizacao/simular_autorizacao)
- Gerar cartão físico (/documentation/cards/create/gerar_cartao_fisico)
- Criar cartão virtual (/documentation/cards/create/gerar_cartao_virtual)
- Introdução (/documentation/cards/introducao)
- Buscar autorização pela Chave da Autorização (/documentation/cards/search/buscar_autorizacao)
- Buscar Authorizações (/documentation/cards/search/buscar_autorizacoes)
- Buscar cartão por chave (/documentation/cards/search/buscar_cartao_by_key)
- Buscar dados PCI (/documentation/cards/search/buscar_dados_pci)
- Buscar entrega por chave de cartão (/documentation/cards/search/buscar_entrega_by_key)
- Buscar Senha PCI (/documentation/cards/search/buscar_senha)
- Listar cartões (/documentation/cards/search/listar_cartoes)
- Ativar cartão físico (/documentation/cards/status/ativar_cartao)
- Atualizar status (/documentation/cards/status/update_status_cartao)
- Configuração do contactless (/documentation/cards/update/contactless_cartao)
- Alterar senha cartão físico (/documentation/cards/update/password_cartao)
- Atualizar endereço de entrega (/documentation/cards/update/update_delivery_address)
---
# Requisição de Autorização (Opcional)
URL: /documentation/cards/autorizacao/
---
Uma vez que o programa está configurado, o portador do cartão foi adicionado e tem um cartão ativo, este cartão pode ser usado para fazer compras em vários pontos de venda ao redor do mundo. Sempre que uma transação for iniciada em algum ponto de captura, uma `Authorization` será criada para autorizar este movimento. Será feita uma Requisição de Autorização `Authorization Request` ao sistema do cliente para que este decida pela aprovação ou não desta autorização com base nas informações contidas neste pedido.
A entidade `Authorization` contém a situação atual dos valores autorizados e capturados e pode assumir os seguintes valores de estado:
| Estado | Descrição |
|---|---|
| pending | Requisição de autorização foi aprovada e nenhum evento de captura ou cancelamento foi processado |
| unauthorized | Requisição de autorização não foi aprovada |
| completed | Pelo menos um valor capturado com sucesso para a autorização em questão (seja um valor igual, a menor ou a maior que o valor total aprovado nas requisições de autorização) |
| reversed | Autorização foi estornada por completo ou expirou sem captura |
Detalhamento dos campos de uma Autorização pode ser encontrado em [Buscar Autorização](/documentation/cards/search/buscar_autorizacao/)
A Requisição de Autorização `Authorization Request` quando enviada para o cliente conterá os [Cabeçalhos de Autenticação](/documentation/primeiros_passos/teste_de_autenticacao/webhook_v2/index.html) e possuirá a seguinte composição:
### Requisição de Autorização
ENDPOINT (client_url)/authorization_request
METODO POST
Request Body
```json
{
"authorization_key": "c91ce179-517c-48f9-9c28-18368457b67f",
"authorization_request_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"card": {
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"type": "virtual",
"card_name": "ecommerce sample",
"printed_name": "Aurora Catarina",
"status": "active",
"brand": "visa",
"bin": "123456",
"last_four_digits": "5695"
},
"terminal_id": "123456",
"terminal_country_code": "BRA",
"terminal_type": "2",
"terminal_pin_entry_capability": true,
"terminal_magnetic_stripe_capability": true,
"terminal_contactless_capability": false,
"terminal_chip_capability": true,
"merchant_acquirer_code": "250",
"merchant_code": "123456",
"merchant_name": "VASP LINHAS AEREAS",
"merchant_street": "RUA CMDTE X, 127",
"merchant_city": "SAO PAULO, SP",
"merchant_region": "BRA",
"merchant_postal_code": "04570-140",
"merchant_mcc": "3036",
"authorization_code": "473890",
"nsu": "123456",
"acquirer_reference_number": "12312423",
"merchant_currency_code": "BRL",
"merchant_amount": 10.59,
"billing_currency_code": "BRL",
"billing_amount": 10.59,
"processing_datetime": "2023-01-10T13:45:52.000Z",
"number_of_installments": 1,
"authorization_type": "authorization",
"pan_entry_mode": "chip",
"pin_sent": true,
"autorization": {Objeto Autorização}
}
```
#### Authorization Request
| Campo | Tipo | Descrição |
|---|---| ---|
| `authorization_request_key` | string | Identificador único da Requisição de Autorização |
| `authorization_key` | string | Identificador único da entidade Autorização relacionada com esta requisição |
| `card` | object |**[Objeto Card](#objeto-card)** |
| `terminal_id` | string | O identificador do terminal enviado pela adquirente na mensageria de autenticação |
| `terminal_country_code` | string | O código do país do terminal, enviado na mensagem de autorização conforme ISO 3166-1 alpha-3 |
| `terminal_type` | string | O tipo de terminal conforme recebido na mensageria de autorização |
| `terminal_pin_entry_capability` | boolean | Existe a possibilidade de inserir a senha do cartão no terminal? |
| `terminal_magnetic_stripe_capability` | boolean | O terminal é capaz de ler tarja magnética? |
| `terminal_contactless_capability` | boolean | O terminal é capaz de iniciar transações contactless? |
| `terminal_chip_capability` | boolean | O terminal é capaz de iniciar transações utilizando o chip EMV? |
| `merchant_acquirer_code` | string | O identificador da adquirente conforme mensageria de autorização |
| `merchant_code` | string | O identificador do lojista na adquirente conforme mensageria de autorização |
| `merchant_name` | string | O nome do lojista de acordo com a mensageria de autorização |
| `merchant_street` | string | A rua do endereço do lojista |
| `merchant_city` | string | A cidade do endereço do lojista |
| `merchant_region` | string | A região do endereço do lojista |
| `merchant_postal_code` | string | O código postal (CEP) do endereço do lojista |
| `merchant_mcc` | string | Merchant Category Code - identificação do tipo de estabelecimento - [Lista Atualizada pode ser encontrada aqui](https://usa.visa.com/content/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf) |
| `authorization_code` | string | Código de Autorização de 6 dígitos |
| `nsu` | string | Número sequencial único que define uma autorização |
| `acquirer_reference_number` | string | Identificador único da autorização na adquirente |
| `merchant_currency_code` | string | A moeda utilizada na transação - ISO 4217-alpha |
| `merchant_amount` | decimal | Valor da transação na moeda em que a transação foi realizada |
| `billing_currency_code` | string | A moeda de cobrança do portador do cartão - ISO 4217-alpha |
| `billing_amount` | decimal | Valor da transação na moeda de cobrança do portador do cartão |
| `processing_datetime` | timestamp utc | Horário em que a requisição de autorização foi processada |
| `number_of_installments` | int | Número de parcelas sendo autorizadas nesta requisição |
| `authorization_request_type` | enum | Enumerador de **[Tipos de Requisição de Autorização](#tipos-de-autorizacao)** |
| `pan_entry_mode` | enum | **[Modos de entrada do PAN](#modos-de-entrada-do-pan)** - Chip, Digitada, Tarja, Fallback, Contactless |
| `pin_sent` | boolean | Foi inserida uma senha no terminal? |
| `authorization` | object | Objeto Autorização detalhado em [GET Autorização](/documentation/cards/search/buscar_autorizacao/), presente apenas quando o tipo de autorização for incremental. |
#### Objeto Card
| Campo | Tipo | Descrição |
|---| ---| ---|
| `card_key` | string | Chave de identificação do cartão|
| `account_key` | string | Identificador da conta do titular |
| `type` | string | Tipo de cartão |
| `card_name` | string | Identificador alphanumérico do cartão|
| `printed_name` | string | Nome impresso no cartão |
| `status` | string | Status atual do cartão |
| `brand` | string | Bandeira do cartão |
| `bin` | string | BIN do cartão |
| `last_four_digits` | string | Últimos 4 dígitos do cartão |
#### Tipos de Requisição de Autorização
| Enumerador | Descrição |
|---|---|
| **authorization** | Requisição de autorização comum |
| **incremental_authorization** | Requisição de autorização incremental para uma Autorização preexistente |
| **partial_reversal_authorization** | Autorização para realizar o estorno parcial de uma transação prévia, aparece apenas em eventos, não é autorizada explicitamente pelo cliente |
| **reversal_authorization** | Autorização para realizar o estorno de uma transação prévia, aparece apenas em eventos, não é autorizada explicitamente pelo cliente |
#### Modos de Entrada do PAN
Enumerador | ISO 8583 | Descrição
---------- | -------- | -----------
unknown | 00 | PAN entry mode desconhecido.
typed | 01 | PAN inserido manualmente (digitado).
bar_code | 03 | PAN inserido por meio de leitora de código de barras
ocr | 04 | PAN inserido por meio de OCR (Optical Character Recognition)
chip | 05 | PAN inserido por cartão com circuito integrado (Chip)
track_1 | 06 | PAN inserido pela Track 1 do cartão de tarja
contactless | 07 | PAN inserido por meio de Contactless EMV
fallback_typed | 79 | Foi tentado utilizar o leitor de cartão ou de tarja do dispositivo e o cartão mas não foi possível processar a transação com aquela informação (Possivelmente um problema no dispositivo ou no cartão), foi então digitada o PAN. Em alguns casos a adquirente não está homologada para utilizar o CHIP ou a tarja e envia este código.
fallback_magnetic_stripe | 80 | Foi tentado utilizar o leitor de cartão do dispositivo e o cartão mas não foi possível processar a transação com aquela informação (Possivelmente um problema no dispositivo ou no cartão), foi então utilizada a tarja magnética do cartão.
ecommerce | 81 | Transação de e-commerce / não presencial
magnetic_stripe | 90 | Transação de tarja (Cartão não possui chip ou dispositivo não possui leitor/não foi homologado)
### Resposta de aprovação ou negação de uma requisição de autorização
A resposta à Rquisição de Autorização deverá ser sempre com HTTP Status 201 e o parecer deve ser informado no campo *approve*. Caso o parecer seja negativo, um enumerador de razão de negação deverá ser escolhido e é possível enviar uma descrição em texto para detalhar essa negação.
ENDPOINT (client_url)/authorization_request
MÉTODO POST
HTTP STATUS 201
Response Body
```json
"authorization_request_response": "unauthorized",
"denial_reason": "fraud_suspicion",
"denial_reason_details": "Customer tried to perform a transaction 10 times the average transactions"
```
#### Detalhe
| Campo | Tipo | Descrição |
|---|---| ---|
| `authorization_request_response` *(required)* | enumerator | `authorized` caso a autorização seja aprovada ou `unauthorized` caso a autorização seja negada |
| `denial_reason` | enum | **[Enumerador Razão de Negação](#enumerador-razao-de-negacao)** |
| `denial_reason_details` | string | Deny reason details | |
#### Enumerador Razão de Negação
| Enumerador | Descrição |
|-----------------------|---------------------------------------------------------------------------|
| **fraud_suspicion** | Movimentação com comportamento suspeito |
| **blocked_customer** | Portador com restrições |
#### Resposta negativa
Qualquer HTTP status que não seja 2XX será interpretado como incapacidade do cliente de processar a autorização. Será então aplicada a regra de decisão configurada no programa do cliente para os casos de indisponibilidade.
Importante: Autorizações que sejam negadas pelos critérios básicos de validação de cartões serão respondidas automaticamente pela QI sem o envio de uma requisição de autorização. O cliente receberá apenas um webhook de autorização negada.
## Autorização Incremental
Uma `Authorization` poderá receber mais de uma `Authorization Request`, situação que chamamos de autorização incremental. Cada `Authorization Request` pode ou não ser autorizado e a entidade `Authorization` irá sempre representar o resultado do que for capturado com sucesso dentre as N autorizações.
Uma autorização incremental poderá ser identificada pelo campo `authorization_type` com valor *incremental_authorization*. Sempre que a requisição for deste tipo, o objeto `Authorization` relacionado será enviado junto ao payload da `Authorization Request`.
---
# Simulação de autorização
URL: /documentation/cards/autorizacao/simular_autorizacao
### Request
ENDPOINT /mock/card/authorization
MÉTODO POST
Request Body
```json
{
"card_key": "ff3c4484-7a52-457e-b989-d9dcb87dfcd6",
"merchant_name": "Supermarket XYZ",
"merchant_city": "São Paulo",
"merchant_region": "BR",
"merchant_postal_code": "01001000",
"merchant_mcc": "5411",
"amount": 150.75,
"authorization_type": "purchase"
}
```
### Response
```json
{
"is_approved": true,
"response_code": "00",
"limit_amount": null
}
```
### Objeto Request Body
Nessa tabela, está disponível o descritivo de todas as variáveis utilizadas pelas requisições acima detalhadas.
| Campo | Tipo | Descrição | Máx. Caract. | Exemplo |
|-----------------------|--------|----------------------------------------------------|--------------|----------------------|
| **card_key** | string | Chave única do cartão (obrigatório) | 36 | "ff3c4484-7a52-457e-b989-d9dcb87dfcd6" |
| **authorization_type**| string | Tipo de autorização (obrigatório) | **[Enumeradores](#authorization-type-enumeradores)** |
| **merchant_name** | string | Nome do estabelecimento | 40 | "Supermarket XYZ" |
| **merchant_city** | string | Cidade do estabelecimento | 40 | "São Paulo" |
| **merchant_region** | string | País do estabelecimento | 2 | "BR" |
| **merchant_postal_code** | string | Código postal do estabelecimento | 8 | "01001000" |
| **merchant_mcc** | string | Código da categoria do estabelecimento (MCC) | **[Enumeradores](#merchant-mcc-enumeradores)** |
| **amount** | number | Valor da transação | - | 150.75 |
### Enumeradores merchant_mcc
| Enumerador | Descrição |
|------------|--------------------------------------------|
| 5812 | Eating Places, Restaurants |
| 5499 | Miscellaneous Food Stores |
| 5814 | Fast Food Restaurants |
| 5411 | Grocery Stores, Supermarkets |
| 4121 | Taxicabs and Limousines |
| 4111 | Local and Suburban Transit |
| 4215 | Courier Services, Air or Ground |
| 5912 | Drug Stores and Pharmacies |
| 5815 | Digital Goods: Applications (Excludes Games)|
| 8999 | Professional Services (Not Elsewhere Classified)|
| 5462 | Bakeries |
| 5541 | Service Stations (with or without Ancillary Services)|
| 7523 | Parking Lots, Parking Meters and Garages |
| 5300 | Wholesale Clubs |
| 4899 | Cable, Satellite and Other Pay Television and Radio Services|
| 5311 | Department Stores |
| 5813 | Bars, Cocktail Lounges, Discotheques, Nightclubs and Taverns (Drinking Places)|
| 7372 | Computer Programming, Data Processing and Integrated Systems Design Services|
| 5099 | Durable Goods (Not Elsewhere Classified) |
| 5943 | Stationery Stores, Office and School Supply Stores|
| 7299 | Miscellaneous Personal Services (Not Elsewhere Classified)|
| 5199 | Nondurable Goods (Not Elsewhere Classified)|
| 7230 | Beauty and Barber Shops |
| 5999 | Miscellaneous and Specialty Retail Stores |
| 5651 | Family Clothing Stores |
### Enumeradores authorization_type
| Enumerador | Descrição |
|-------------|----------------------------|
| purchase | Purchase |
| reversal | Reversal |
| withdrawal | Withdrawal |
---
# Gerar cartão físico
URL: /documentation/cards/create/gerar_cartao_fisico
## Request
ENDPOINT /prepaid/card
MÉTODO POST
Request Body
```json
{
"account_key": "5294ed8d-08fc-4397-b15f-6d9aa07b0041",
"program_key": "7d405c31-ec9a-46c1-8ac8-54bab209bf41",
"type": "plastic",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"contactless_enabled": true,
"delivery_address": {
"address": "Rua Cel. Domingos Diniz",
"number": 124,
"neighborhood": "Centro",
"zip_code": "35797000",
"city": "Presidente Juscelino",
"state": "MG",
"complement": "Quadra 08 Lote 259",
"reference": "Supermercado Presidente",
"address_type": "residential"
}
}
```
:::info
O endereço utilizado para o envio do cartão físico, será o mesmo informado na abertura da conta de pagamento na QI Tec.
:::
### Body params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|---------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| `account_key` * | string | Chave de identificação da conta de pagamento na QI Tech. | uuid |
| `program_key` * | string | Chave de identificação do programa para emitir um cartão. | uuid |
| `type` * | string | Tipo do cartão a ser emitido (PLASTIC). | **[Enumeradores](#enumeradores-card_type)** |
| `card_name` * | string | Alias do cartão, como esse cartão será identificado. | 15 |
| `printed_name` * | string | Nome que será impresso no cartão (não será permitido o uso de números e caracteres especiais). | 26 |
| `contactless_enabled` * | boolean | Habilitar ou desabilitar o uso de contactless do cartão | - |
| `delivery_address` | Object | Endereco de entrega do cartão | **[Objeto Address](#address)** |
### Enumeradores card_type
| Enumerador | Tradução |
|------------|----------------|
| plastic | Cartão físico |
| virtual | Cartão virtual |
### Address
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|---------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| address* | string | Endereço de entrega | 100 |
| neighborhood*| string | Bairro do endereço de entrega | 100 |
| zip_code* | string | CEP do endereço de entrega | 8 |
| city* | string | Cidade do endereço de entrega | 100 |
| state* | string | Estado do endereço de entrega | 2 |
| number | number | Número do endereço de entrega | |
| complement | string | Complemento do endereço de entrega | 100 |
| reference | string | Ponto de referência do endereço de entrega | 100 |
| address_type* | string | Tipo de entrega | **[Enumeradores](#enumeradores-address_type)** |
:::caution Atenção!
O campo `number` é opcional. Endereços sem numeração podem ser enviados sem este campo.
:::
### Enumeradores address_type
| Enumerador | Tradução |
|------------|----------------------|
| residential| Endereço residencial |
| commercial | Endereço comercial |
| other | Outro endereço |
## Response
STATUS 201
Response Body
```json
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"created_at": "2023-06-20T19:28:16Z",
"status":"created"
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "The type of person is invalid for this program, please try another.",
"translation": "Invalid Person",
"code": "CARD000007"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000005| 404 | It was not possible to fetch the Program for the program_key \{program_key\}.|
| CARD000006| 404 | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000007| 400 | The type of person is invalid for this program, please try another.|
| CARD000008| 400 | The Card Holder with the status \{status\} is invalid for the operation.|
| CARD000009| 400 | We're sorry, but the card could not be generated. Please try again later.|
| CARD000010| 404 | It was not possible to fetch the Person for the person_key \{owner_person_key\}.|
| CARD000033| 403 | Create plastic card is not allowed for program_key \{program_key\}.|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card",
"event_datetime": "2023-07-24T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"program_key": "bf74df61-557a-45cb-914f-41e127a6e18c",
"status": "created",
"type": "plastic"
}
}
```
---
# Criar cartão virtual
URL: /documentation/cards/create/gerar_cartao_virtual
## Request
ENDPOINT /prepaid/card
MÉTODO POST
Request Body
```json
{
"account_key": "5294ed8d-08fc-4397-b15f-6d9aa07b0041",
"program_key":"7d405c31-ec9a-46c1-8ac8-54bab209bf41",
"type": "virtual",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"cvv_rotation_interval_hours": 72
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------|--------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| `account_key` * | string | Chave de identificação da conta de pagamento na QI Tech. | uuid |
| `program_key` * | string | Chave de identificação do programa para emitir um cartão. | uuid |
| `type` * | string | Tipo do cartão a ser emitido (VIRTUAL). | **[Enumeradores](#enumeradores-card_type)** |
| `card_name` * | string | Alias do cartão, como esse cartão será identificado. | uuid |
| `printed_name` * | string | Nome que será impresso no cartão (não será permitido o uso de números e caracteres especiais). | uuid |
| `cvv_rotation_interval_hours` * | int | Intervalo em horas para atualizar o número CVV. | Number |
### Enumeradores card_type
| Enumerador | Tradução |
|------------|----------------|
| plastic | Cartão físico |
| virtual | Cartão virtual |
## Response
STATUS 201
Response Body
```json
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"created_at": "2023-02-20T19:28:16Z",
"status":"created"
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "The type of person is invalid for this program, please try another.",
"translation": "Invalid Person",
"code": "CARD000007"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000005| 404 | It was not possible to fetch the Program for the program_key \{program_key\}.|
| CARD000006| 404 | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000007| 400 | The type of person is invalid for this program, please try another.|
| CARD000008| 400 | The Card Holder with the status \{status\} is invalid for the operation.|
| CARD000009| 400 | We're sorry, but the card could not be generated. Please try again later.|
| CARD000010| 404 | It was not possible to fetch the Person for the person_key \{owner_person_key\}.|
| CARD000032| 403 | Create virtual card is not allowed for program_key \{program_key\}.|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card",
"event_datetime": "2023-07-24T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"program_key": "bf74df61-557a-45cb-914f-41e127a6e18c",
"status": "created",
"type": "virtual"
}
}
```
---
# Introdução
URL: /documentation/cards/introducao
As APIs para emissão de cartão pré pago, permitem que os clientes dos parceiros da QI Tech, solicitem e emitam Cartões Pré Pagos, sejam eles físicos ou virtuais.
Na QI Tech, oferecemos aos nossos parceiros a oportunidade de se tornarem subemissores. Por meio das nossas APIs, os parceiros podem disponibilizar aos seus próprios clientes a possibilidade de emitir tanto cartões pré pagos físicos como virtuais, permitindo assim uma solução completa para serviços bancários.
Para entender melhor nosso sistema faremos uma breve introdução de como funciona o ecossistema de cartões pré pagos, mas lembramos que assim como as demais APIs a liberação do serviço deve ser feita junto ao nosso time e as **[chamadas são autenticadas](/documentation/primeiros_passos/teste_de_autenticacao)**.
### Cartão Pré Pago
O cartão pré pago é um cartão que esta vinculado a uma conta de pagamento dentro da QI Tech.
Todas as transações executadas através deste cartão, debitarão o saldo existente na conta de pagamentos.
Caso a conta não tenha saldo a transação será negada.
### Conta de Pagamento
A QI Tech é uma instituição financeira autorizada a operar com contas de pagamento pré pago pelo Banco Central do Brasil. Um Cartão pré pago esta sempre vinculado à uma conta de pagamento pré pago.
Sendo assim, para criação de um cartão pré pago, seja ele físico ou virtual, é sempre necessário realizar a abertura de uma conta de pagamento. Confira **[aqui](/documentation/contas/abertura_de_conta/abertura_de_conta_pf)** nossa API de abertura de contas.
### Programa
Para que um parceiro possa realizar a emissão de um cartão pré pago, é necessário que ele tenha um programa associado e configurado em sua integração com a QI.
O programa é nada mais que as configurações e regras necessárias para a emissão do cartão em conformidade com a bandeira VISA.
Aqui estão algumas informações importantes sobre o programa:
* **Tipo do programa** - Refere-se à modalidade de utilização do cartão. No caso desta documentação, trata-se da modalidade Pré Pago.
* **Bandeira** - Utilizamos a bandeira VISA para os cartões emitidos pelo programa.
* **Layout do cartão** - Refere-se ao desenho que será impresso no cartão físico e que será apresentado na interface gráfica do cartão virtual.
:::caution Atenção
Para configuração de um novo programa em uma integração, o time comercial e o time de implantação da QI Tech deverão ser acionados.
:::
### Cartão Virtual
A API de cartões da QI Tech oferece a funcionalidade de geração de cartões virtuais, que podem ser utilizados em transações online. Essa solução proporciona segurança e comodidade aos portadores de cartão.
Ao utilizar um cartão virtual, os portadores não precisam fornecer os detalhes do cartão físico durante transações pela internet. Em vez disso, eles podem gerar um cartão virtual único, com um número e informações específicas para aquela transação em particular. Isso ajuda a reduzir o risco de fraude e aumenta a confiança nas transações online.
### Cartão Físico
A API de cartões da QI Tech oferece a opção de criação de cartões físicos, proporcionando aos portadores a possibilidade de ter um cartão de plástico para uso em transações presenciais.
Ao solicitar um cartão físico, o portador receberá um cartão de plástico personalizado.
A disponibilidade do cartão físico oferece aos portadores uma forma tradicional e amplamente aceita de realizar pagamentos, garantindo conveniência e praticidade em suas transações presenciais. Além disso, o cartão físico também pode apresentar recursos adicionais, como tecnologia de pagamento por aproximação (contactless) para agilizar as transações.
API de cartões pré pagos da QI Tech, possibilita ao portador do cartão a flexibilidade de escolher entre o uso de cartões virtuais para transações online e a utilização de cartões físicos para transações presenciais, de acordo com suas necessidades e preferências individuais.
---
# Buscar autorização pela Chave da Autorização
URL: /documentation/cards/search/buscar_autorizacao
## Request
ENDPOINT /prepaid/card/(card_key)/authorization/(authorization_key)
MÉTODO GET
## Response
STATUS 200
Response Body
```json
{
"authorization_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"merchant_currency_code": "BRL",
"original_merchant_amount": 25.32,
"billing_currency_code": "BRL",
"original_billing_amount": 25.32,
"merchant_amount": 25.32,
"iof_amount": 0,
"billing_amount": 25.32,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"captured_amount": 25.32,
"authorization_status": "completed",
"card": {
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"type": "virtual",
"card_name": "ecommerce sample",
"printed_name": "Aurora Catarina",
"status": "active",
"brand": "visa",
"bin": "123456",
"last_four_digits": "5695"
},
"balance_transactions": [
{
"balance_transaction_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"balance_transaction_type": "debit",
"account_transaction_key": "595e08f0-da4e-40f7-8db4-f9a25c820000",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"merchant_currency_code": "BRL",
"merchant_amount": 25.32,
"billing_currency_code": "BRL",
"billing_amount": 25.32,
"processing_datetime": "2023-01-10T13:45:52.000Z",
"balance_transaction_status": "transacted",
"transacted_amount": 25.32,
}
],
"authorization_requests": [
{
"authorization_request_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"authorization_code": "473890",
"nsu": "123456",
"acquirer_reference_number": "12312423",
"merchant_currency_code": "BRL",
"merchant_amount": 25.32,
"billing_currency_code": "BRL",
"billing_amount": 25.32,
"processing_datetime": "2023-01-10T13:45:52.000Z",
"number_of_installments": 1,
"authorization_type": "authorization",
"authorization_request_response": "authorized"
}
],
"authorization_events": [
{
"merchant_currency_code": "BRL",
"merchant_amount": 25.32,
"billing_currency_code": "BRL",
"billing_amount": 25.32,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "authorization"
}
]
}
```
### Objeto Autorização
| Campo | Tipo | Descrição |
|---|---| ---|
| authorization_key | string | Identificador único da autorização |
| merchant_currency_code | string | A moeda utilizada na transação - ISO 4217-alpha |
| original_merchant_amount | decimal | Valor original da transação na moeda em que a transação foi realizada |
| billing_currency_code | string | A moeda de cobrança do portador do cartão - ISO 4217-alpha |
| original_billing_amount | decimal | Valor original da transação na moeda de cobrança do portador do cartão |
| merchant_amount | decimal | Somatório do Valor da transação na moeda em que a transação foi realizada de todas requisições de autorização |
| iof_amount | decimal | Somatório do valor de IOF pago no câmbio quando as moedas da transação e de cobrança do portador forem diferentes |
| billing_amount | decimal | Somatório do valor da transação na moeda de cobrança do portador do cartão de todas requisições de autorização |
| processing_datetime | datetime UTC | Horário em que o objeto de autorização foi criado, em geral, horário da primeira requisição de autorização feita |
| captured_amount | decimal | Somatório do valor total capturado por todas requisições de autorização |
| authorization_status | enumerator | Enumerador de **[Status da Autorização](#status-da-autorizacao)** |
| card | object |**[Objeto Card](#objeto-card)** |
| balance_transactions | list of objects |**[Objeto Balance Transaction](#objeto-balance-transaction)** |
| authorization_requests | list of objects |**[Objeto Requisição de Autorização](#objeto-rquisicao-de-autorizacao)** |
| authorization_events | list of objects | **[Objeto Evento de Autorização](#objeto-evento-autorizacao)** |
### Objeto Card
| Campo | Tipo | Descrição |
|---| ---| ---|
| card_key | string | Chave de identificação do cartão|
| account_key | string | Identificador da conta do titular |
| type | string | Tipo de cartão |
| card_name | string | Identificador alphanumérico do cartão|
| printed_name | string | Nome impresso no cartão |
| cvv_rotation_interval_hours | int | Intervalo de rotação do CVV |
| status | string | Status atual do cartão |
| brand | string | Bandeira do cartão |
| bin | string | BIN do cartão |
| last_four_digits | string | Últimos 4 dígitos do cartão |
### Objeto Balance Transaction
O objeto `Balance Transaction` representa qualquer movimentação na QI Conta do titular do cartão que precise ser efetuada. Podem ser transações de *débito* por ocasião de uma Autorização aprovada, como podem ser de *crédito* numa situação de cancelamento de autorização por exemplo.
| Campo | Tipo | Descrição |
|---| ---| ---|
| balance_transaction_key | string | Identificador único da transação |
| balance_transaction_type | enumerador | *credit* quando se tratar de um crédito em conta e *debit* quando se tratar de um débito em conta|
| account_key | string | Identificador da QI Conta relacionada com o cartão usado na transação |
| merchant_currency_code | string | A moeda utilizada na transação - ISO 4217-alpha |
| merchant_amount | decimal | Equivalente de valor cobrado na moeda da transação |
| billing_currency_code | string | A moeda de cobrança do portador do cartão - ISO 4217-alpha |
| billing_amount | decimal | Valor da transação na moeda de cobrança do portador do cartão |
| processing_datetime | datetime | Representa a data de processamento e criação da transação. Como a transação efetiva na QI Conta pode não ocorrer, este valor é uma referência de quando a cobrança ou crédito foram gerados |
| balance_transaction_status | enumerator | Descreve se a transação foi executada na QI Conta do portador do cartão, podendo estar pendente (`pending_transaction_execution`), parcialmente transacionada (`partially_transacted`) ou transacionada (`transacted`)|
| transacted_amount | decimal | Valor total na moeda do portador do cartão do débito ou crédito que já foram executados na QI Conta |
### Objeto Requisição de Autorização
Detalhado em [Requisição de Autorização](/documentation/cards/autorizacao/)
### Objeto Evento de Autorização
O objeto `Authorization Event` representa os eventos que ocorrem com uma Autorização. Uma forma mais detalhada de como eles podem ocorrer está descrita em [Manuais](/documentation/manual_pre_pago/casos_uso/)
| Campo | Tipo | Descrição |
|---| ---| ---|
| merchant_currency_code | string | A moeda utilizada na transação - ISO 4217-alpha |
| merchant_amount | decimal | Equivalente de valor cobrado na moeda da transação |
| billing_currency_code | string | A moeda de cobrança do portador do cartão - ISO 4217-alpha |
| billing_amount | decimal | Valor do evento na moeda de cobrança do portador do cartão |
| processing_datetime | datetime | Representa a data de processamento do evento |
| authorization_event_type | enumerator | **[Tipos de Evento de Autorização](#tipos-evento-autorizacao)** |
### Status da Autorização
| Estado | Descrição |
|---|---|
| pending | Requisição de autorização foi aprovada e nenhum evento de captura ou cancelamento foi processado |
| unauthorized | Requisição de autorização não foi aprovada |
| completed | Pelo menos um valor capturado com sucesso para a autorização em questão (seja um valor igual, a menor ou a maior que o valor total aprovado nas requisições de autorização) |
| reversed | Autorização foi estornada por completo ou expirou sem captura |
### Tipos de Evento de Autorização
| Tipo | Descrição |
|---|---|
| authorization | Informe de que uma requisição de autorização foi respondida |
| incremental_authorization | Informe de que uma requisição de autorização incremental foi respondida |
| authorization_reversal | Informe de que um cancelamento de autorização foi processado |
| partial_authorization_reversal | Informe de que um cancelamento parcial de autorização foi processado |
| authorization_expiration | Informe de que uma autorização expirou |
| capture | Informe de que um determinado valor foi capturado para uma autorização |
| refund | Informe de que uma autorização foi reembolsada |
| partial_refund | Informe de que uma autorização foi reembolsada parcialmente |
---
# Buscar Authorizações
URL: /documentation/cards/search/buscar_autorizacoes
## Request
ENDPOINT /prepaid/card/(card_key)/authorizations
MÉTODO GET
PARÂMETROS from_date, to_date, size, page
## QUERY PARAMS
| Campo | Tipo | Descrição |
|-----------------|--------|----------------------------------------------------------|
| `size` | int | Quantidade de registros que será retornado. Default 10. |
| `page` | int | Página que será realizado a busca. Default 1. |
| `from_date` | date | Data de início do período desejado |
| `to_date` | date | Data de fim do período desejado |
## Response
STATUS 200
Response Body
```json
{
"pagination": {
"current_page": 1,
"rows_per_page": 10,
"next_page": 2
},
"data": [
{
"authorization_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"merchant_currency_code": "BRL",
"original_merchant_amount": 25.31,
"billing_currency_code": "BRL",
"original_billing_amount": 25.31,
"merchant_amount": 25.31,
"iof_amount": 0,
"billing_amount": 25.31,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"captured_amount": 25.31,
"authorization_status": "completed"
},
{
"authorization_key": "9a7b2586-7070-4543-99eb-989d9165814e",
"merchant_currency_code": "BRL",
"original_merchant_amount": 65,
"billing_currency_code": "BRL",
"original_billing_amount": 65,
"merchant_amount": 65,
"iof_amount": 0,
"billing_amount": 65,
"processing_datetime": "2023-07-24T13:00:00.000Z",
"captured_amount": 65,
"authorization_status": "completed"
}
]
```
---
# Buscar cartão por chave
URL: /documentation/cards/search/buscar_cartao_by_key
## Request
ENDPOINT /prepaid/card/ CARD_KEY
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
## Response
STATUS 200
Response Body
```json
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
"type": "virtual",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"cvv_rotation_interval_hours": 72,
"created_at": "2023-02-20T19:28:16Z",
"updated_at": "2023-02-22T19:28:16Z",
"status": "active",
"brand": "visa",
"last_four_digits": "5695",
"status_events": [
{
"status": "created",
"created_at": "2023-02-20T19:28:16Z"
},
{
"status": "active",
"created_at": "2023-02-20T19:35:10Z"
}
]
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Not Found Card",
"code": "CARD000011"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000016| 400 | We're sorry, but the card could not be fetch. Please try again later.|
---
# Buscar dados PCI
URL: /documentation/cards/search/buscar_dados_pci
## Request
ENDPOINT /prepaid/card/ CARD_KEY /pci
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
## Response
STATUS 200
Response Body
```json
{
"printed_name": "Aurora Catarina",
"valid_until": "2023-02-20T10:04:12Z",
"expiration_date": "03/24",
"card_number": "4539347744299311",
"cvv": "713"
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Not Found Card",
"code": "CARD000011"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400 | It was not possible to fetch PCI for the card_key \{card_key\}.|
---
# Buscar entrega por chave de cartão
URL: /documentation/cards/search/buscar_entrega_by_key
## Request
ENDPOINT /card/ CARD_KEY /tracking
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
## Response
STATUS 200
Response Body
```json
{
"card_key": "92b4e2bd-4a6f-4c56-859e-17c729e1f0c8",
"tracking_code": "4F68A72B902317",
"status": "posted",
"recipient": "João Silva",
"address": {
"zip_code": "1234567",
"street": "Rua das Flores",
"number": 123,
"complement": "Bloco A",
"neighborhood": "Centro",
"city": "Cidade Exemplo",
"state": "SP"
},
"event": [
{
"created_at": "2024-02-27T08:30:00Z",
"old_status": "pending",
"new_status": "posted",
"description": "Pedido recebido e postado",
"place": "SAO PAULO"
}
]
}
```
### Enumeradores DeliveryStatus
| Enumerador | Tradução |
|--------------------|---------------------|
| pending | Pendente |
| posted | Postado |
| prepared | Preparado |
| in_transfer | Em transferência |
| in_delivery_unit | Na unidade de entrega |
| on_route | Em rota |
| attempt_failed | Tentativa falhou |
| awaiting_withdrawal| Aguardando retirada |
| returning | Retornando |
| delivered | Entregue |
| returned | Devolvido |
| canceled | Cancelado |
| failed | Falhou |
| resend | Reenviado |
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Tracking for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Not Found",
"code": "TRACK000011"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| TRACK000011| 404 | It was not possible to fetch the Tracking for the card_key \{card_key\}.|
| TRACK000016| 400 | We're sorry, but the tracking could not be fetch. Please try again later.|
---
# Buscar Senha PCI
URL: /documentation/cards/search/buscar_senha
## Request
ENDPOINT /prepaid/card/ CARD_KEY /pci/password
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
## Response
STATUS 200
Response Body
```json
{
"pin": "1234"
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "It was not possible to fetch PCI for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Fetch PCI failed",
"code": "CARD000012"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400 | It was not possible to fetch PCI for the card_key \{card_key\}.|
---
# Listar cartões
URL: /documentation/cards/search/listar_cartoes
## Request
ENDPOINT /prepaid/card
MÉTODO GET
PARÂMETROS account_key, size, page
## QUERY PARAMS
| Campo | Tipo | Descrição | Caracteres |
|-----------------|--------|----------------------------------------------------------|------------|
| `account_key` * | string | Chave de identificação da conta de pagamento na QI Tech. | uuid |
| `size` | int | Quantidade de registros que será retornado. Default 10. | - |
| `page` | int | Página que será realizado a busca. Default 0. | - |
## Response
STATUS 200
Response Body
```json
{
"pagination": {
"current_page": 1,
"rows_per_page": 0,
"next_page": 2
},
"data": [
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
"type": "virtual",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"cvv_rotation_interval_hours": 72,
"created_at": "2023-02-20T19:28:16Z",
"updated_at": "2023-02-22T19:28:16Z",
"status": "active",
"brand": "visa"
},
{
"card_key": "ee084f00-d72e-4263-87fb-3a3c11a418c6",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
"type": "virtual",
"card_name": "uber",
"printed_name": "Aurora Catarina",
"cvv_rotation_interval_hours": 72,
"created_at": "2023-02-10T11:28:16Z",
"updated_at": "2023-02-15T11:28:16Z",
"status": "canceled",
"brand": "visa"
}
]
}
```
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Account for the account_key 94f982c0-164c-45e3-8a0e-69f54ad7b155.",
"translation": "Not Found Account",
"code": "CARD000006"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| CARD000006| 404 | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000021| 400 | Account key can not be null when search for cards.|
| CARD000022| 400 | Invalid integer value for page or size querystring parameters.|
---
# Ativar cartão físico
URL: /documentation/cards/status/ativar_cartao
Todo cartão físico precisa ser ativado através de um código de ativação que é enviado junto do cartão físico, ao portador.
Ao receber o cartão por correspondência, o portador do cartão precisa informar ao parceiro da QI, para que o parceiro realize a ativação do cartão através deste endpoint.
:::caution Atenção
Por motivos de segurança, não existe a possibilidade de consulta do código de ativação via API por parte do parceiro.
Este código é enviado, exclusivamente ao portador do cartão, no momento da postagem do cartão físico.
Para realizar testes de integração, esse código é devolvido em ambiente de sandobox ao consultar um cartão.
:::
## Request
ENDPOINT /prepaid/card/ CARD_KEY /activate
MÉTODO PATCH
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
Request Body
```json
{
"code": "253615"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
|-----------|--------|-------------------------------|------------|
| `code` * | string | Código de ativação do cartão. | 6 |
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Not Acceptable",
"description": "Invalid activation code [1254].",
"translation": "Unable to activate card",
"code": "CARD000020"
}
```
| Code | Status code | Description |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000017| 406 | The activation operation is not valid for the current card status [\{card_status\}].|
| CARD000018| 400 | We're sorry, but the card could not be activate. Please try again later.|
| CARD000020| 406 | Invalid activation code [\{code\}].|
| CARD000023| 406 | The card type is invalid for this operation. Only plastic cards are allowed.|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card",
"event_datetime": "2023-07-25T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
"type": "plastic",
"status": "active",
"old_status": "embossing"
}
}
```
---
# Atualizar status
URL: /documentation/cards/status/update_status_cartao
## Request
ENDPOINT /prepaid/card/ CARD_KEY
MÉTODO PATCH
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
Request Body
```json
{
"status": "blocked"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
|-------------|--------|-------------------|-----------------------------------------------|
| `status` * | string | Status do cartão. | **[Enumeradores](#enumeradores-card_status)** |
### Enumeradores card_status
| Enumerador | Tradução | Tipo |
|------------|---------------------|-----------------|
| created | Criação solicitada | Initial |
| building | Em construção | Initial |
| active | Apto a transacionar | Active |
| embossing | Em produção | Temporary block |
| blocked | Bloqueado | Temporary block |
| warning | Com suspeita | Temporary block |
| pending | Pendente | Temporary block |
| lost | Perdido | Terminated |
| robbed | Roubado | Terminated |
| fraud | Fraudado | Terminated |
| canceled | Cancelado | Terminated |
| theft | Furtado | Terminated |
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Not Acceptable",
"description": "The operation is not valid for the current status of the card [canceled]",
"translation": "Unable to transition",
"code": "CARD000014"
}
```
| Code | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000013| 406 | Unable to transition from \{old_status\} to \{new_status\}.|
| CARD000014| 406 | The operation is not valid for the current status of the card [\{card_status\}].|
| CARD000015| 400 | We're sorry, but the card could not be update. Please try again later|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card",
"event_datetime": "2023-07-25T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
"type": "virtual",
"status": "active",
"old_status": "created"
}
}
```
---
# Configuração do contactless
URL: /documentation/cards/update/contactless_cartao
Ativar ou desativar a funcionalidade de pagamento por aproximação (contactless) para uso presencial.
Para ativar ou desativar o pagamento por aproximação do cartão, o status do cartão deve ser do tipo **Ativo** ou **Bloqueio temporário**. (Para obter informações sobre os tipos de status, consulte [aqui](../../cards/status/update_status_cartao#enumeradores-card_status))
## Request
ENDPOINT /prepaid/card/ CARD_KEY /contactless
MÉTODO PATCH
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
Request Body
```json
{
"contactless_enabled": false
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------|------------|
| `contactless_enabled` * | Boolean | Indica se está habilitado ou não. | true/false |
## Response
STATUS SUCCESS 200
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "We're sorry, but the card could not be update contactless. Please try again later.",
"translation": "Unexpected error update contactless card",
"code": "CARD000026"
}
```
| Código | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406 | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000026| 400 | We're sorry, but the card could not be update contactless. Please try again later.|
| CARD000025| 406 | The status \{status\} is invalid for the operation.|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card.updated.contactless
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card.updated.contactless",
"event_datetime": "2023-07-25T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
"contactless_enabled": true
}
}
```
---
# Alterar senha cartão físico
URL: /documentation/cards/update/password_cartao
Todo cartão físico tem uma senha para autorizar a transação, e ela pode ser atualizada caso necessária.
Para atualizar a senha do cartão o status tem que ter o tipo **Active** ou **Temporary block**.(Para conhecer sobre status consulte [aqui](../../cards/status/update_status_cartao#enumeradores-card_status))
:::caution Atenção
Por motivos de segurança, cuidado ao atualizar uma senha, pois ela pode impactar na autorização de um cartão.
Crie regras para melhorar a segurança da autorização da senha, como não utilizar data de aniversário, números repetidos (ex: 3333).
:::
## Request
ENDPOINT /prepaid/card/ CARD_KEY /password
MÉTODO PATCH
### Path params
| Campo | Tipo | Descrição | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid |
Request Body
```json
{
"pin": "2143"
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
|-----------|--------|-----------------------------------------------|------------|
| `pin` * | string | Senha do cartão para autorizar uma transação. | 4 |
## Response
STATUS SUCCESS 200
### Erros
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "We're sorry, but the card could not be update password. Please try again later.",
"translation": "Unexpected error update password card",
"code": "CARD000024"
}
```
| Código | Status code | Descrição |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406 | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000024| 400 | We're sorry, but the card could not be update password. Please try again later.|
| CARD000025| 406 | The status \{status\} is invalid for the operation.|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card.updated.password
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card.updated.password",
"event_datetime": "2023-07-25T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1"
}
}
```
---
# Atualizar endereço de entrega
URL: /documentation/cards/update/update_delivery_address
A atualização do endereço de entrega serve para corrigir o endereço caso alguma inconsistência seja encontrada ou a entrega seja mal sucedida três vezes.
## Request
ENDPOINT /account/ ACCOUNT_KEY /card/ CARD_KEY /address
MÉTODO POST
### Path parameters
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta, no formato uuid v4 | 36 |
| `card_key` | uuidv4 | Chave única de identificação do cartão, no formato uuid v4 | 36 |
Request Body
```json
{
"postal_code": "5425020",
"street": "Rua Gilberto Sabino",
"number": 215,
"complement": "4 andar",
"neighborhood": "Pinheiros",
"city": "So Paulo",
"state": "SP",
"reference": "Terminal Pinheiros",
"address_type": "commercial",
"notes": ["obs1", "obs2"],
"phones": [
{"country_code": "55", "area_code": "19", "number": "983151110"},
{"country_code": "55", "area_code": "16", "number": "992334318"},
],
}
```
### Request Body
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------------|------------|
| `street` * | string | Logradouro | 100 |
| `number` | string | Número | 10 |
| `neighborhood` * | string | Bairro | 100 |
| `postal_code` * | string | CEP | 8 |
| `city` * | string | Cidade | 100 |
| `complement` | string | Complemento | 100 |
| `reference` | string | Ponto de referência | 100 |
| `notes` | string array | Observações relacionadas ao endereço | 100 |
| `phones` | object array | Telefones de contato | **[Objeto phone](#objeto-phone)** |
| `state` * | string | Estado (UF) | **[Enumeradores state](#enumeradores-state)** |
| `address_type` * | string | Tipo de endereço | **[Enumeradores address_type](#enumeradores-address_type)** |
:::caution Atenção!
O campo `number` é opcional. Endereços sem numeração podem ser enviados sem este campo.
:::
:::caution Atenção!
Podem ser enviados até dois telefones de contato e quatro observações. Caso não haja telefone de contato e/ou observações, esses campos (`phones` e `notes`) não devem ser enviados.
:::
### Objeto phone
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` * | string | Código DDI (Discagem Direta Internacional) | 2 |
| `area_code` * | string | Código DDD (Discagem Direta à Distância) | 2 |
| `number` * | string | Complemento | 9 |
### Enumeradores address_type
| Enumerador | Descrição |
|--------------------|--------------------------|
| residential | endereço residencial |
| commercial | endereço comercial |
| other | outros tipos de endereço |
### Enumeradores state
| Enumerador | Descrição |
|--------------------|-----------------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MG | Minas Gerais |
| MS | Mato Grosso do Sul |
| MT | Mato Grosso |
| PA | Pará |
| PB | Paraíba |
| PE | Pernambuco |
| PI | Piauí |
| PR | Paraná |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RO | Rondônia |
| RR | Roraima |
| RS | Rio Grande do Sul |
| SC | Santa Catarina |
| SE | Sergipe |
| SP | São Paulo |
| TO | Tocantins |
| EX | Exceção |
## Response
STATUS 200
Response Body
```json
{
"card_key": "1e3183f0-1bac-4e59-81e8-2d89db224040",
"tracking_code": "FD89B071241022",
"address": {
"city": "So Paulo",
"notes": [
"obs1",
"obs2"
],
"state": "SP",
"number": 215,
"phones": [
{
"number": "983151110",
"area_code": "19",
"country_code": "55"
},
{
"number": "992334318",
"area_code": "16",
"country_code": "55"
}
],
"street": "Rua Gilberto Sabino",
"reference": "Terminal Pinheiros",
"complement": "4 andar",
"postal_code": "5425020",
"address_type": "commercial",
"neighborhood": "Pinheiros"
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|-------------------------------------------------------------------------------------------------|------------|
| `card_key` * | uuidv4 | Chave única de identificação do cartão, no formato uuid v4 | 36 |
| `tracking_code` * | string | Código de rastreio da entrega do cartão | 14 |
| `address` | object | Objeto do tipo `address`, semelhante ao que é enviado na requisição | **[Objeto address](#objeto-address)** |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 403 | QIT000005 | Permission Validator Error | Selected agent and person_key are different | Agente selecionado e person_key são diferentes |
| 400 | TRACK000004 | Bad Request | Invalid status to change delivery address. | Status inválido para mudar o endereço de entrega. |
| 500 | TRACK000007 | Internal Server Error | Failed to update delivery address at delivery service provider. Please, try again later! | Falha ao atualizar endereço de entrega junto à provedora de serviços de delivery. Por favor, tente novamente mais tarde! |
| 404 | TRACK000012 | Not Found | Tracking not found for the given 'card_key'. | Rastreio não encontrado para a 'card_key' fornecida. |