Criar um Pagamento Pré-autorizado

Aprenda a gerenciar o ciclo de vida completo de pré-autorizações utilizando o PreauthorizationRepository. Uma pré-autorização permite verificar e reservar um valor específico no cartão de um cliente sem a captura imediata dos fundos. Isso garante a disponibilidade do valor para um pagamento futuro, sendo a solução ideal para o setor de hotelaria, aluguel de veículos ou qualquer cenário onde o preço final do serviço é definido apenas na sua conclusão.

O ciclo de vida de uma pré-autorização consiste em quatro operações principais:

1. Criar (Create): Reserva os fundos no cartão.
2. Confirmar (Confirm): Finaliza a cobrança (captura o valor).
3. Substituir (Replace): Modifica o valor reservado anteriormente.
4. Anular (Annul): Cancela a reserva e libera o limite do cliente.

Antes de realizar qualquer operação, certifique-se de que você já inicializou o TPV.

1. Criando uma Pré-autorização

Para iniciar o fluxo, use o método makePreauthorization. Isso verifica se o cartão possui fundos suficientes e coloca uma reserva neles.

Função: makePreauthorization

Parâmetros:

• amount: O objeto Money representando o valor a ser reservado.
• shiftInfo (Opcional): Informações sobre o turno atual.
• proprietaryExtraData (Opcional): Dados de terceiros.
• language (Opcional): Idioma para a interface do serviço.

Exemplo:

suspend fun reserveFunds(amount: Money) {
    val result = preauthorizationRepository.makePreauthorization(
        amount = amount
    )
    handlePreauthResult(result)
}

2. Confirmando uma Pré-autorização

Assim que o valor final for conhecido (ex: no momento do checkout), você deve confirmar a pré-autorização para efetivar a cobrança no cartão. Você precisará do operationId retornado na etapa de criação.

Função: confirmPreauthorization

Parâmetros:

• amount: O valor final a ser cobrado.
• operationId: O identificador da pré-autorização original.
• shiftInfo (Opcional): Informações de turno.
• proprietaryExtraData (Opcional): Dados de terceiros.
• language (Opcional): Idioma para a interface do serviço.

Exemplo:

suspend fun finalizeCharge(originalId: String, finalAmount: Money) {
    val result = preauthorizationRepository.confirmPreauthorization(
        operationId = originalId,
        amount = finalAmount
    )
    handlePreauthResult(result)
}

3. Substituindo (Modificando) uma Pré-autorização

Se o custo estimado mudar (ex: extensão de um aluguel), você pode atualizar o valor reservado.

Função: replacePreauthorization

Parâmetros:

• amount: O novo valor a ser reservado.
• operationId: O identificador da pré-autorização original.
• shiftInfo (Opcional): Informações de turno.
• proprietaryExtraData (Opcional): Dados de terceiros.
• language (Opcional): Idioma para a interface do serviço.

Exemplo:

suspend fun updateReservation(originalId: String, newAmount: Money) {
    val result = preauthorizationRepository.replacePreauthorization(
        operationId = originalId,
        amount = newAmount
    )
    handlePreauthResult(result)
}

4. Anulando uma Pré-autorização

Se o serviço for cancelado ou a reserva não for mais necessária, você pode liberar o bloqueio dos fundos.

Função: annulPreauthorization

Parâmetros:

• operationId: O identificador da pré-autorização a ser cancelada.
• language (Opcional): Idioma para a interface do serviço.

Exemplo:

suspend fun cancelReservation(originalId: String) {
    val result = preauthorizationRepository.annulPreauthorization(
        operationId = originalId
    )
    handlePreauthResult(result)
}

Interpretando o Resultado

Todas as quatro operações retornam um RepositoryResult contendo um PreauthorizationResult.

Estados do Resultado

• Aceito (PreauthorizationResult.Accepted): A operação foi aprovada pelo host.
  • Dados: Contém um objeto Transaction. Para a etapa de criação, salve o transaction.operationInfo.identifier para usar nas chamadas subsequentes de Confirmar/Substituir/Anular.
• Negado (PreauthorizationResult.Denied): A operação foi rejeitada.

Exemplo de Lógica de Tratamento

fun handlePreauthResult(result: RepositoryResult<PreauthorizationResult>) {
    when (result) {
        is RepositoryResult.Success -> {
            when (val preAuthOutcome = result.data) {
                is PreauthorizationResult.Accepted -> {
                    val tx = preAuthOutcome.data
                    println("✅ Operation Approved. ID: ${tx.operationInfo.identifier}")
                    // Save tx.operationInfo.identifier for future use
                }
                is PreauthorizationResult.Denied -> {
                    println("❌ Operation Denied")
                }
            }
        }
        is RepositoryResult.ConnectionError -> println("❌ Connection Error")
        is RepositoryResult.Cancelled -> println("⚠️ Cancelled by user")
        is RepositoryResult.ProtocolError -> println("❌ Error: ${result.type}")
    }
}

Próximos Passos

• Gerenciar Turnos e Sessões: Gerencie o tempo operacional.
• Histórico de Transações: Revise operações passadas.