QI Cartões - Pré-pago
Casos de Uso
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.
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"
}