Transação

1) Instanciando a PayOsSdkPayment

Obtendo a instância da SDK:

private val payOsSdkPaymentInstance = PayOsSdkPayment.instance

Interface exposta pela PayOsSdkPayment:

interface PayOsSdkPayment {
    fun configure(context: Context)
    fun init(activationCode: String, callback: ConnectorCallback)
    fun isInitialized(): Boolean
    fun resetTerminalConfigurations()
    fun updateTerminalConfigurations(callback: ConnectorCallback)
    fun selectApplication(position: Int)
    fun setLastDigits(lastDigits: String)
    fun setCvvType(cvvType: CvvTypeEnum)
    fun setCvv(cvv: String)
    fun abort()
    fun tableLoad(callback: ConnectorCallback)
    suspend fun getActiveEstablishmentDetails(): PayOsSdkEstablishment?
    fun makeTransaction(params: PayOsSdkTransactionParams, callback: ConnectorCallback)
    fun revertTransaction(gatewayKey: String, callback: ConnectorCallback)
    fun listTransactions(callback: ConnectorCallback)
    fun getTransaction(gatewayKey: String, callback: ConnectorCallback)
    fun getPixTransactionFromCloud(gatewayKey: String, callback: ConnectorCallback)
    fun syncTransactionToCloud(gatewayKey: String, callback: ConnectorCallback)
}

1.1) Configuração

Para começar, é necessário chamar o método de configuração. O funcionamento de todos os outros métodos está atrelado à configuração, já que o context da aplicação é utilizado por todo o SDK.

É necessário que este método seja chamado apenas uma vez. Recomenda-se chamá-lo no lifecycle de onCreate da aplicação.

payOsSdkPaymentInstance.configure(applicationContext)

1.2) Inicialização

Para habilitar o uso da PayOsSdkPayment, é necessário chamar o método de inicialização. Informe o código do estabelecimento (disponível no cadastro do estabelecimento no portal). Execute uma única vez.

payOsSdkPaymentInstance.init(activationCode = “COD_ATIVACAO”, callback)

callback é uma instância da interface ConnectorCallback, que é usada para tratar as respostas da inicialização.

2) Realizar transação

Transações são realizadas através do método makeTransaction.

O método makeTransaction recebe dois parâmetros: params e callback.

params é uma instância da classe PayOsSdkTransactionParams, que contém os detalhes da transação (por exemplo, a valor da transação, o tipo de crédito - à vista ou parcelado, a quantidade de parcelas e o tipo de transação - CREDIT, DEBIT e PIX).

callback é uma instância da interface ConnectorCallback, que é usada para tratar as respostas da transação.

2.1) Realizar transação CREDIT ou DEBIT

val params = PayOsSdkTransactionParams(
    amount = 1000,
    creditType = CreditType.NO_INSTALLMENT,
    installment = null, // or an integer
    typeTransaction = TypeTransaction.CREDIT
)

payOsSdkPaymentInstance.makeTransaction(params, callback)

No callback de onApproved, o parâmetro retornado é o objeto da transação, do tipo PayOsSdkTransactionStore. O status da transação retornado nesse callback já é o
status final, isso significa que o onApproved (para transações de cartão) sempre
retornará uma transação com status CONFIRMED.

val callback = object: ConnectorCallback {
    override fun onRequest(
        p0: RequestFlowEnum,
        requestAny: Any?
    ) {
        // Solicitações de interação
    }

    override fun onMessage(
        p0: NotificationType,
        p1: String
    ) {
        // Mensagens para exibição
    }

    override fun onApproved(p0: Any?) {
        if(p0 is PayOsSdkTransactionStore) {
            // Transação realizada com sucesso
        }
    }

    override fun onError(
        p0: ReturnCodes,
        p1: List<String>,
        p2: Int?
    ) {
        // Erros
    }
}

2.2) Realizar transação PIX

Embora transações PIX também sejam realizadas através do método makeTransaction, mantendo a mesma assinatura, o fluxo de confirmação da transação difere um pouco. Isso porque as transações PIX são primeiro criadas junto ao processador de pagamento e depois é realizada a confirmação.

val params = PayOsSdkTransactionParams(
    amount = 1000,
    typeTransaction = PayOsSdkTransactionType.PIX
)

payOsSdkPaymentInstance.makeTransaction(params, callback)

No callback de onApproved, o parâmetro retornado é o objeto da transação, do tipo PayOsSdkTransactionStore.

A grande diferença entre transações PIX e CREDIT/DEBIT encontra-se no callback de onApproved. Enquanto que para transações CREDIT/DEBIT o onApproved sempre retorna o status CONFIRMED, para transações PIX o status retornado poderá ser PENDING, FAILED, CANCELLED ou CONFIRMED.

Os status FAILED, CANCELLED e CONFIRMED são status finais da transação. Quando algum desses status for retornado, pode considerar a transação finalizada.

• FAILED - houve uma falha ao criar a transação junto ao processador de pagamentos ou o pagamento não foi confirmado;
• CANCELLED - na maioria das vezes se trata de QR Code expirado. O campo expiration do PayOsSdkTransactionStore informa a data/hora de expiração do QR Code;
• CONFIRMED - pagamento realizado com sucesso;

O status PENDING é um status transitório. Ao iniciar uma transação PIX com sucesso, o primeiro retorno do onApproved será sempre um item PayOsSdkTransactionStore com transactionStatus = PENDING. A partir daí, a SDK irá notificar novamente, no próprio onApproved, qualquer alteração do status, até o
tempo de expiração (transaction.expiration) + 1min30s.

2.2.1) Simulação de transação PIX em ambiente de testes/Sandbox

Atualmente é possível simular 4 cenários para transações PIX no ambiente de testes:

• Valor par: fluxo normal, transação é criada como PENDING e notificada como CONFIRMED após 2 consultas;
• Valor terminado em 1: transação é criada como PENDING e notificada como CANCELLED após 2 consultas. Ex: 10001, 10011, 10021;
• Valor terminado em 3: transação é criada como PENDING e notificada como CANCELLED após o tempo de expiração. Ex: 10003, 10013, 10023;
• Valor ímpar: simular falha na criação do PIX. Transação é criada e retornada com status FAILED.

val callback = object: ConnectorCallback {
    override fun onRequest(
        p0: RequestFlowEnum,
        requestAny: Any?
    ) {
				// Não aplicável para PIX - ignorar
    }

    override fun onMessage(
        p0: NotificationType,
        p1: String
    ) {
        // Mensagens para exibição - não obrigatórias
    }

    override fun onApproved(p0: Any?) {
        if(p0 is PayOsSdkTransactionStore) {
            // Transação realizada com sucesso
        }
    }

    override fun onError(
        p0: ReturnCodes,
        p1: List<String>,
        p2: Int?
    ) {
        // Erros
    }
}

3) Cancelamento/estorno de transação

Transações são estornadas através do método revertTransaction.

O método revertTransaction recebe dois parâmetros: gatewayKey e callback.

gatewayKey é um campo do tipo String retornado dentro do PayOsSdkTransactionStore quando uma transação é realizada.

callback é uma instância da interface ConnectorCallback, que é usada para tratar as respostas da transação.

payOsSdkPaymentInstance.revertTransaction(gatewayKey, callback)

4) Listagem de transações (local)

Lista as transações executadas no dispositivo. O retorno do callback de sucesso retorna uma Lista de PayOsSdkTransactionStore. No momento, nenhuma opção de filtros é oferecida.

payOsSdkPaymentInstance.listTransactions()

5) Obter transação via gatewayKey (local)

Obtém os dados de uma transação local através do gatewayKey dessa transação. O retorno do callback de sucesso retorna um item do tipo PayOsSdkTransactionStore ou null.

payOsSdkPaymentInstance.getTransaction(gatewayKey: String, callback: ConnectorCallback)

6) Obter transação Pix via gatewayKey (cloud)

Obtém os dados de uma transação do tipo PIX através do gatewayKey dessa transação.

Este método realiza uma consulta à API e retorna os dados atualizados da transação
PIX, como o status do pagamento no BC. Além disso, a entidade local é atualizada
com os dados remotos retornados.

O retorno do callback de sucesso retorna um item do tipo PayOsSdkTransactionStore.

payOsSdkPaymentInstance.getPixTransactionFromCloud(gatewayKey: String, callback: ConnectorCallback)

7) Sincronizar/enviar transação via gatewayKey (cloud)

Envia os dados da transação para a API, mantendo o sincronismo entre as transações no dispositivo e em cloud. A ação é individual para cada transação, sendo necessário informar o gatewayKey no momento da chamada.

Este método deve ser utilizado apenas quando for identificado uma falha na sincronização automática de transações. Todas as transações já são sincronizadas ao serem realizadas/estornadas.

É possível identificar se uma transação não foi sincronizada através do campo syncedToCloudAt do PayOsSdkTransactionStore. Quando syncedToCloudAt for null, houve um problema na sincronização.

Da mesma forma, para estorno de transações, deve-se verificar se syncedToCloudAt é maior (mais recente) que cancelledAt. Se não for, houve uma falha na sincronização do estorno, e faz-se necessário uma sincronização manual. O retorno do callback de sucesso retorna um item do tipo PayOsSdkTransactionStore.

payOsSdkPaymentInstance.syncTransactionToCloud(gatewayKey: String, callback: ConnectorCallback)

8) ConnectorCallback

O ConnectorCallback é a interface que expõe callbacks assíncronos utilizados pelos métodos do SDK.

val callback = object: ConnectorCallback {
    override fun onRequest(
        p0: RequestFlowEnum,
        requestAny: Any?
    ) {
        // Solicitações de interação
    }

    override fun onMessage(
        p0: NotificationType,
        p1: String
    ) {
        // Mensagens para exibição
    }

    override fun onApproved(p0: Any?) {
        // Realizado/finalizado com sucesso
    }

    override fun onError(
        p0: ReturnCodes,
        p1: List<String>,
        p2: Int?
    ) {
        // Erros
    }
}

8.1) onRequest - Interações possíveis

Durante o processo de transação, é possível que sejam requisitadas algumas informações adicionais como o CVV, os últimos dígitos do cartão, entre outros.

Estas solicitações são feitas através do método onRequest da interface ConnectorCallback.

Este callback é chamado quando uma ação requer uma interação. As interações possíveis são representadas pelo enum RequestFlowEnum, e a informação específica da solicitação é passada através do parâmetro requestAny.

• APPLICATION: escolher a aplicação de pagamento;
• LAST_DIGITS_CONFIRMATION: confirmar os últimos dígitos do cartão;
• CVV_TYPE: definir tipo do CVV;
• CVV: informar CVV;
• PRINT_ERROR: tratar erro de impressão.

override fun onRequest(
    p0: RequestFlowEnum,
    p1: Any?
) {
    when (p0) {
        RequestFlowEnum.APPLICATION -> {
            // Listar opções possíveis
            val menuApplication = p1 as MenuApplication

            // Responder à interação com a posição do item no menu
            payOsSdkInstance.selectApplication(position = 0)
        }
        RequestFlowEnum.LAST_DIGITS_CONFIRMATION -> {
            payOsSdkInstance.setLastDigits(lastDigits = "1234")
        }
        RequestFlowEnum.CVV_TYPE -> {
            payOsSdkInstance.setLastDigits(cvvType = CvvTypeEnum.EXISTS)
        }
        RequestFlowEnum.CVV -> {
            payOsSdkInstance.setCvv(cvv = "123")
        }
        RequestFlowEnum.PRINT_ERROR -> {
            // Tratar erro de impressão
        }
        else -> ConnectorCallback.DefaultImpls.onRequest(this, p0, p1)
    }
}

8.2) onMessage

Mensagens informativas emitidas pelo SDK. São obrigatórias para exibição integral.

9) Outras operações

Sobre as operações da PayOsSdkPayment.

9.1) isInitialized(): Boolean

Retorna se a SDK está inicializada ou não;

9.2) selectApplication(position: Int)

Seleciona a aplicação de pagamento (para cartões com múltiplas aplicações).

9.3) setLastDigits(lastDigits: String)

Confirma os últimos dígitos do cartão (fluxo de tarja).

9.4) setCvvType(cvvType: CvvTypeEnum)

Define o tipo de CVV.

9.5) setCvv(cvv: String)

Define o valor do CVV.

9.6) abort()

Aborta a chamada atual (não surte efeito durante envio de transação/cancelamento).

9.7) resetTerminalConfigurations()

Apaga todo o conteúdo da base e restaura as configurações padrão do terminal.

9.8) updateTerminalConfigurations(callback: ConnectorCallback)

Atualiza os dados do estabelecimento ativo, atualiza permissões (como, por exemplo, permissão de estorno) e outros dados de personalização do marketplace (como, por exemplo, logo do recibo). Além disso, atualiza dados usados para verificar a integração com o terminal.

Aconselha-se expor, no aplicativo, um botão que chame este método, de forma manual.

9.9) tableLoad()

Realiza novamente a carga de tabelas. Este método pode ser chamado, por exemplo,
se houver o erro EXPIRED TABLES ao tentar realizar uma transação. Assim, após chamar esse método, é possível realizar a transação novamente.

9.10) getActiveEstablishmentDetails()

Retorna os dados do estabelecimento ativo. Observar que essa é uma função suspend fun, que só pode ser chamada dentro de outra suspend fun ou dentro de uma Coroutine.

6) Como forçar fluxos de interação (para testes)

Alguns fluxos podem ser forçados para testes de UI/integração.

6.1) APPLICATION

Para induzir o fluxo de seleção de aplicação:

• Passe TypeTransaction.NONE na chamada da transação;
• Insira um cartão com duas ou mais operações (crédito/débito, por exemplo).

val params = PayOsSdkTransactionParams(
    amount = 1000,
    creditType = CreditType.NO_INSTALLMENT,
    installment = null, // or an integer
    typeTransaction = TypeTransaction.NONE
)

6.2) LAST_DIGITS_CONFIRMATION, CVV_TYPE e CVV (fluxos de tarja)

Para induzir o fluxo de tarja:

• Use um cartão de tarja (sem chip), ou;
• Force fallback para tarja com um cartão chip: insira o cartão de cabeça para baixo, aguarde o erro de chip, então passe na tarja.