Skip to main content

QI Cartões - Pré-pago

Casos de Uso​

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.

Reenvio de Webhooks

Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: Reenvio de Webhooks.

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. 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 pode ser detalhado nesta 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
{
	"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
{
	"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. 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
{
	"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
{
	"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. 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
{
	"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
{
	"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
{
	"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. 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
{
	"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
{
	"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
{
	"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"
}