Integração com Pagamentos V2¶

Uma das formas de se integrar com a aplicação de pagamentos da Phoebus é via IPC. Para isto, é fornecida uma biblioteca, a payments-api-x.x.x.x.aar, contendo todo o código necessário a ser usado para tais chamadas.

Usando esta API, é possível realizar todo o fluxo de pagamento, ou seja, a confirmação (ou o desfazimento) e o estorno. O pagamento pode ser realizado com um valor pré-definido ou com um valor em aberto, a ser digitado pelo operador do terminal. Além disso, pode-se informar uma lista de tipos de pagamentos (débito, crédito à vista, crédito parcelado, etc.) permitidos.

Ainda que esta integração se dê através de uma API, a aplicação de pagamentos da Phoebus pode exibir informações na interface do terminal, tais como mensagens (e.g., "Insira ou passe o cartão"), ou mesmo solicitar informações do operador (e.g., CVV). Assim sendo, durante a realização de qualquer operação, a aplicação que solicitou a operação não deve interagir com a interface do dispositivo até que a operação seja concluída.

A seguir, temos a especificação detalhada das operações disponíveis.

Para integração com a API de pagamentos, é fornecida a interface PaymentClient presente na biblioteca.

Fluxo de Pagamento¶

O pagamento só é finalizado quando existe uma confirmação ou um cancelamento (desfazimento). Em caso de confirmação, o comprovante estará disponível para impressão ou envio por SMS/e-mail, dependendo das funcionalidades do terminal.

A partir da versão 3.1.4.3

Quando uma transação é feita e o app solicita sua confirmação (confirmPayment()) ou desfazimento (cancelPayment()), a resposta solicitação será enviada ao app assim que a transação for resolvida localmente pelo terminal, eliminando a necessidade de o app esperar a resolução com o autorizador para dar continuidade ao fluxo.

Após isto, o terminal tentará resolver a transação com o autorizador. Isto pode ocorrer imediatamente ao finalizar a transação, ou posteriormente, na resolução de pendências.

Métodos¶

startPaymentV2()¶

Este método deve ser chamado quando se deseja fazer uma solicitação de autorização de pagamento. Durante sua execução, os dados do pagamento serão validados, informações adicionais serão solicitadas ao operador (e.g. senha e CVV), e a autorização junto à adquirente será feita.

Parâmetros

Detalhe dos Parâmetros

request (PaymentRequestV2)

callback (PaymentCallback)

confirmPayment()¶

Este método deve ser chamado para confirmar uma transação que o terminal conseguiu processar completamente a perna de autorização enviada pelo Autorizador.

Este método não deve ser chamado para uma transação já confirmada, ou seja, em que já se executou o método confirmPayment() anteriormente.

Este método não deve ser chamado para uma transação já desfeita, ou seja, em que já se executou o método cancelPayment() anteriormente.

Este método não deve ser chamado para uma transação que foi negada pelo Autorizador, ou seja, a transação precisa ter sido autorizada pelo Autorizador.

Após a execução desta confirmação, a transação só poderá ser cancelada através de uma operação de estorno (o estorno é a operação executada pelo menu CANCELAMENTO do terminal).

Caso o App consumidor desta API tenha finalizado o seu processo de negócio com êxito, porém não tenha chamado o método confirmPayment(), a transação permanecerá com o seguinte status: Situação PayStore = "Pendente". Resolução no Adquirente = "Pendente".

Como resultado, poderemos ter uma inconsistência transacional, visto que, na virada do dia, algumas redes adquirentes confirmam automaticamente as transações que não receberam a perna de confirmação. Outras redes adquirentes trabalham apenas com duas pernas, sem a necessidade de perna de confirmação. Neste caso, se houver algum problema na conclusão da transação no lado do terminal, é imperativo que a solução de captura execute o método cancelPayment(), a fim de desfazer a transação no adquirente e evitar cobrança para o cliente Portador do Cartão.

Parâmetros

Detalhe dos parâmetros

callback

cancelPayment()¶

Este método deve ser sempre chamado para desfazer uma transação que o terminal não conseguiu processar completamente a perna de autorização enviada pelo Autorizador.

Este método não deve ser chamado para uma transação já confirmada, ou seja, em que já se executou o método confirmPayment() anteriormente.

Este método não deve ser chamado para desfazer uma transação já desfeita, ou seja, em que já se executou o método cancelPayment() anteriormente

Este método não deve ser chamado para uma transação que foi negada pelo Autorizador.

Este método não é um estorno. O estorno é a operação executada pelo menu CANCELAMENTO do terminal. O estorno é executado em transações que foram concluídas com êxito, ou seja, foram confirmadas.

Após a execução do desfazimento, cancelPayment(), a transação não poderá ser mais confirmada pela aplicação do terminal, ou seja, não se pode mais executar o método confirmPayment().

Caso o App consumidor desta API não tenha finalizado o seu processo de negócio com êxito, é imprescindível a chamada do método cancelPayment(). A consequência de não cancelar uma transação que não teve seu processo de negócio concluído é semelhante à consequência de não confirmar. Porém, nesse caso, com um agravante, pois provavelmente o cliente não levará o produto/serviço associado à transação financeira, ou uma nova tentativa de venda poderá ser feita, resultando em uma cobrança em duplicidade para o cliente Portador do Cartão.

Parâmetros

Detalhe dos parâmetros

callback

Campo adicional api_pending¶

Além dos métodos para resolução de pagamentos (confirmPayment e cancelPayment), há a possibilidade de se configurar um campo adicional no Portal Paystore para realizar esta resolução automaticamente, em determinado tempo. Para isto, deve ser criado um campo adicional no Portal Paystore com o tipo JSON e a chave api_pending.

Valor do campo

{
    "confirmationTime": "10",
    "transactionConfirmation": "CONFIRM"
}

Exemplo do fluxo de pagamento¶

import androidx.appcompat.app.AppCompatActivity;

import android.content.Intent;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import android.widget.Toast;

import java.math.BigDecimal;

import br.com.phoebus.android.payments.api.ApplicationInfo;
import br.com.phoebus.android.payments.api.Credentials;
import br.com.phoebus.android.payments.api.ErrorData;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.PaymentRequestV2;
import br.com.phoebus.android.payments.api.PaymentV2;
import br.com.phoebus.android.payments.api.exception.ClientException;

public class MainActivity extends AppCompatActivity implements View.OnClickListener, PaymentClient.PaymentCallback<PaymentV2> {

    Button bt_start;
    private PaymentClient paymentClient;
    public static final String TEST_APPLICATION_ID = "0";
    public static final String TEST_SECRET_TOKEN = "000000000000000000000000";
    public static final String TAG = "TAG_DEMO";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        bt_start = (Button) this.findViewById(R.id.button);
        bt_start.setOnClickListener(this);
        paymentClient = new PaymentClient();

    }


    @Override
    public void onClick(View view) {
        doExecute();
    }

    @Override
    protected void onResume() {
        super.onResume();
        paymentClient.bind(this);
    }

    @Override
    protected void onDestroy() {
        try {
            paymentClient.unbind(this);
        } catch (Exception e) {
            Log.e(TAG, e.getMessage());
        }
        super.onDestroy();
    }

    public void doExecute(){
        PaymentRequestV2 request = new PaymentRequestV2();
        BigDecimal value = BigDecimal.valueOf(5000).movePointLeft(2);
        request.setValue(value);
        request.setAppTransactionId("2d2f7dc7-88e5-467e-86a3-f173fb3c7792");

        Credentials credentials = new Credentials();
        credentials.setApplicationId(TEST_APPLICATION_ID);
        credentials.setSecretToken(TEST_SECRET_TOKEN);

        ApplicationInfo applicationInfo = new ApplicationInfo();
        applicationInfo.setCredentials(credentials);
        applicationInfo.setSoftwareVersion("1.0");

        request.setAppInfo(applicationInfo);

        try {
            paymentClient.startPaymentV2(request, this);
        } catch (ClientException e) {
            Log.e(TAG, "Error starting payment", e);
        }
    }


    @Override
    public void onSuccess(PaymentV2 paymentV2) {
        Log.i(TAG, paymentV2.toString());

        doConfirmPayment(paymentV2);
        /*
          Se, na sua regra de negócio, for preciso desfazer a transação por algum motivo,
          chame o método doCancelPayment(paymentV2)
        **/
    }

    @Override
    public void onError(ErrorData errorData) {
        Log.e(TAG, errorData.getResponseMessage());
        Toast.makeText(this, errorData.getResponseMessage(), Toast.LENGTH_LONG).show();
    }

    private void doConfirmPayment(PaymentV2 paymentV2) {
        try {
            paymentClient.confirmPayment(paymentV2.getPaymentId(),
                    new PaymentClient.PaymentCallback<PaymentV2>() {

                        @Override
                        public void onError(ErrorData errorData) {
                            Log.e(TAG, errorData.getResponseMessage());
                            Toast.makeText(MainActivity.this, errorData.getResponseMessage(), Toast.LENGTH_LONG).show();

                        }

                        @Override
                        public void onSuccess(Object o) {
                            Log.i(TAG, "Confirmação do pagamento realizado com sucesso!");
                        }


                    });
        } catch (ClientException e) {
            Log.e(TAG, "Error confirmPayment", e);
        }

    }

    private void doCancelPayment(PaymentV2 paymentV2) {
        try {
            paymentClient.cancelPayment(paymentV2.getPaymentId(),
                    new PaymentClient.PaymentCallback<PaymentV2>() {

                        @Override
                        public void onError(ErrorData errorData) {
                            Log.e(TAG, errorData.getResponseMessage());
                            Toast.makeText(MainActivity.this, errorData.getResponseMessage(), Toast.LENGTH_LONG).show();

                        }

                        @Override
                        public void onSuccess(Object o) {
                            Log.i(TAG, "Desfazimento Realizado!");
                        }


                    });
        } catch (ClientException e) {
            Log.e(TAG, "Error cancelPayment", e);
        }

    }


}