Integração com Estorno 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 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.

Fluxo de Estorno¶

O estorno só é finalizado quando existe uma confirmação ou um desfazimento. Em caso de confirmação, o comprovante será impresso.

A partir da versão 3.1.5.0

Quando uma transação é feita, anteriormente, poderia ser confirmado realizando sua impressão (ou via printReceipt), ou ao realizar uma nova transação. Agora, o estorno também pode ser confirmado ao usar o novo parâmetro autoConfirm - indicando se deve ou não confirmar independente da impressão - ou utilizando o novo método confirmReversePayment().

Métodos¶

reversePaymentV2()¶

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

Note que a transação de estorno não possui confirmação, mas apenas desfazimento. Assim, a confirmação ocorrerá naturalmente com o não envio do desfazimento, a depender do comportamento de cada adquirente. Caso haja impressão do comprovante do estorno, quando for passado algum dos parâmetros printMerchantReceipt ou printCustomerReceipt com valor true, o estorno será confirmado automaticamente. Neste caso, o desfazimento não será permitido.

Também a depender do comportamento de cada adquirente, é possível que não haja desfazimento para a transação de estorno. Neste caso, estornos aprovados retornarão o valor false no campo "ReversePayment.cancelable". Além disto, caso seja chamado o método cancelReversePayment(), um erro específico será retornado informando que não é possível executar tal operação (vide Códigos de Resposta).

Parâmetros

Detalhe dos parâmetros

request (ReversePaymentRequestV2)

callback (ReversePaymentCallback)

confirmReversePayment()¶

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

Este método não deve ser chamado para um estorno já confirmado, ou seja, em que já se executou o método confirmReversePayment() anteriormente.

Este método não deve ser chamado para um estorno já desfeito, ou seja, em que já se executou o método cancelReversePayment() anteriormente.

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

Parâmetros

Detalhe dos parâmetros

callback

cancelReversePayment()¶

Este método deve ser chamado para desfazer uma transação de estorno anteriormente autorizada. Esta transação deve não ter sido desfeita ainda e deve ter sido autorizada (não negada) previamente.

Como dito na descrição de reversePayment(), é possível que não haja desfazimento para a transação de estorno para uma determinada adquirente. Assim, o método cancelReversePayment() pode retornar um erro específico informando que não é possível executar tal operação (vide Códigos de Resposta).

Parâmetros

Detalhe dos parâmetros

callback

Exemplo do fluxo de Estorno¶

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.Credentials;
import br.com.phoebus.android.payments.api.ErrorData;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.ReversePayment;
import br.com.phoebus.android.payments.api.ReversePaymentRequestV2;
import br.com.phoebus.android.payments.api.exception.ClientException;

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

    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(){
        ReversePaymentRequestV2 request = new ReversePaymentRequestV2();
        BigDecimal value = BigDecimal.valueOf(5000).movePointLeft(2);
        request.setValue(value);
        request.setAppTransactionId("123456");

        request.setPaymentId("999999");
        request.setPrintCustomerReceipt(true);
        request.setPrintMerchantReceipt(true);

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

        request.setCredentials(credentials);

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


    @Override
    public void onSuccess(ReversePayment  reversePayment) {
        Log.i(TAG, reversePayment.toString());

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

    }

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

    private void doCancelReversePayment(ReversePayment reversePayment) {
        try {
            paymentClient.cancelReversePayment(reversePayment.getPaymentId(),
                    new PaymentClient.PaymentCallback<ReversePayment>() {

                        @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 cancelReversePayment", e);
        }


    }


}