# QI Tech — Cards

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
1 página(s).

Índice:
- QI Cartões - Pré-pago (/en/documentation/manual_pre_pago/casos_uso)

---

# QI Cartões - Pré-pago

URL: /en/documentation/manual_pre_pago/casos_uso

## Casos de Uso

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

---

Para facilitar o entendimento, o cliente de BaaS que irá emitir e fornece o serviço de cartões para seus clientes será tratado como "Cliente". O cliente final portador do cartão emitido será tratado com "Portador".

## 1. Autorização e confirmação completa de uma transação

Este é o caminho mais comum para as transações de cartão, o Portador passa seu cartão para uma transação de valor financeiro X e a adquirente captura exatamente este valor do emissor do cartão. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](https://docs.qitech.com.br/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisção informando um parecer *autorization_request_response* = authorized.

O [Objeto Autorização](https://docs.qitech.com.br/documentation/cards/search/buscar_autorizacao) pode ser detalhado [nesta](https://docs.qitech.com.br/documentation/cards/search/buscar_autorizacao) referência.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a autorização que acaba de ser aprovada.

Webhook de autorização autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A adquirente, após ter uma transação autorizada, realiza a captura deste valor. Essa captura é processada pela QI e um webhook de atualização de estado da autorização é enviado passando essa transação para o estado *completed*. O valor capturado pode ser consultado na variável *captured_amount* do objeto `Authorization`.

Webhook de autorização confirmada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "capture",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

## 2. Autorização e confirmação a menor de uma transação

Neste caso, a adquirente captura um valor menor do que o valor estipulado na autorização. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](https://docs.qitech.com.br/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisição informando um parecer *autorization_request_response* = authorized.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a autorização que acaba de ser aprovada.

Webhook de autorização autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A adquirente, após ter uma transação autorizada, realiza a captura deste valor. Essa captura é processada pela QI e um webhook de atualização de estado da autorização é enviado passando essa autorização para o estado *completed*. O valor capturado pode ser consultado na variável *captured_amount* do objeto `Authorization`. 

Webhook de autorização confirmada a menor

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 23,
		"billing_currency_code": "BRL",
		"billing_amount": 23,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "capture",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

Caso a autorização expire sem ter seu valor total capturado, o excedente será creditado em conta para o Portador no valor da diferença pendente.

## 3. Autorização e confirmação a maior de uma transação

Neste caso, a adquirente captura um valor maior do que o valor estipulado na autorização. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](https://docs.qitech.com.br/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisção informando um parecer *autorization_request_response* = authorized.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a transação que acaba de ser autorizada.

Webhook de autorização autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A adquirente, após ter uma transação autorizada, realiza a captura deste valor. Essa captura é processada pela QI e um webhook de atualização de estado da autorização é enviado passando essa autorização para o estado *completed*. O valor capturado pode ser consultado na variável *captured_amount* do objeto `Authorization`. Neste caso de uso, o valor capturado será maior do que o valor original autorizado.

Webhook de autorização confirmada a maior

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 27,
		"billing_currency_code": "BRL",
		"billing_amount": 27,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "capture",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

Esta situação produzirá um débito em conta para o Portador no valor da diferença a maior, neste exemplo seria debitado R$ 2,00 na QI Conta do Portador. Caso não seja possível realizar esse débito em nenhuma instância a QI irá tratar particularmente esses casos junto ao cliente (Cliente de BaaS utilizando serviço de cartões da QI).

### Cancelamento parcial

Ainda nesta situação de confirmação a maior, a adquirente pode decidir corrigir o eventual engano enviano o reembolso total `refund` ou parcial `partial_refund` que serão representados na forma de eventos de autorização. Abaixo um exemplo de reembolso parcial dos R$2,00 cobrados indevidamente.

Webhook de autorização com reembolso parcial

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 2,
		"billing_currency_code": "BRL",
		"billing_amount": 2,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "partial_refund",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

## 4. Autorização e cancelamento de uma transação

Neste caso, a transação é autorizada mas por algum motivo o vendedor decide cancelar essa transação no POS antes que ela seja capturada. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](https://docs.qitech.com.br/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisção informando um parecer *approve* = true.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a transação que acaba de ser autorizada

Webhook de transação autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A vendedor, após ter uma transação autorizada, decide cancelar essa transação por algum motivo, um erro de digitação por exemplo. Esse mensagem de cancelamento é processada pela QI e um webhook de atualização de estado da transação é enviado passando essa transação para o estado de estornada *reversed*. Nesta situação, o valor total da autorização foi cancelado.

Webhook de autorização estornada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 27,
		"billing_currency_code": "BRL",
		"billing_amount": 27,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization_reversal",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

Nesta situação um crédito no valor total cancelado é feito na Qi Conta do Portador.

### Autorização expirada

Pode ocorrer que uma autorização seja aprovada, mas não seja capturada dentro dos prazos estipulados pela bandeira do cartão. Nesta situação, será enviado um webhook de autorização expirada e o um crédito no valor não capturado será feito na Qi Conta do portador.

Webhook de autorização expirada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization_expiration",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```