Integración con Pagos V2¶

Una de las formas de integrarse con la aplicación de pagos Phoebus es a través de IPC. Para ello, se proporciona una biblioteca, la payments-api-x.x.x.x.aar, que contiene todo el código necesario que se utilizará para dichas llamadas.

Mediante esta API es posible realizar todo el flujo de pago, es decir, confirmación (o deshacer) y reverso del pago. El pago se puede realizar con una cantidad predefinida o con una cantidad abierta, a ser ingresada por el operador de la terminal. Además, es posible informar una lista de tipos de pagos (débito, crédito, crédito en cuotas, etc.) permitidos.

Aunque esta integración se lleva a cabo a través de una API, la aplicación de pago puede mostrar información en la interfaz del terminal, como mensajes (por ejemplo, "Insertar o deslizar la tarjeta"), o incluso solicitar información al operador (por ejemplo, CVV). Por lo tanto, durante la realización de cualquier operación, la aplicación que solicitó la operación no debe interactuar con la interfaz del dispositivo hasta que se complete la operación.

La siguiente es una especificación detallada de las operaciones disponibles.

Para la integración con la API de pagos, se proporciona la interfaz PaymentClient.

Flujo de Pago¶

El pago solo se finaliza cuando hay una confirmación o una cancelación (deshacer). En caso de confirmación, el recibo estará disponible para impresión o envío por SMS/correo electrónico, dependiendo de las funcionalidades de la terminal.

A partir de la versión 3.1.4.3

Cuando se realiza una transacción y la aplicación solicita su confirmación (confirmPayment()) o deshacer (cancelPayment()), la respuesta de la solicitud se enviará a la aplicación tan pronto como la transacción se resuelva localmente en el terminal, eliminando la necesidad de que la aplicación espere la resolución con el autorizador para continuar el flujo.

Después de eso, el terminal intentará resolver la transacción con el autorizador. Esto puede ocurrir inmediatamente al finalizar la transacción, o más tarde, en la resolución de asuntos pendientes.

Métodos¶

startPaymentV2()¶

Se debe llamar a este método cuando desee realizar una solicitud de autorización de pago. Durante su ejecución, se validarán los datos del pago, se solicitará información adicional al operador (por ejemplo, contraseña y CVV), y se realizará la autorización del adquirente.

Parámetros

Detalle de los Parámetros

request (PaymentRequestV2)

callback (PaymentCallback)

confirmPayment()¶

Se debe llamar a este método para confirmar una transacción que la terminal pudo procesar completamente el tramo de autorización enviado por el Autorizador.

Este método no debe ser llamado para una transacción que ya ha sido confirmada, es decir, en la que se ha ejecutado previamente el método confirmPayment(), o en pagos con C�digo QR, ya que en este caso la transacción se confirma automáticamente.

Este método no debe ser llamado para una transacción que ya se ha deshecho, es decir, en la que se ha ejecutado previamente el método cancelPayment().

Este método no debe ser llamado para una transacción que fue denegada por el Autorizador, es decir, la transacción debe haber sido autorizada por el Autorizador.

Después de ejecutar esta confirmación, la transacción solo se puede cancelar mediante una operación de reverso. (el reverso es la operación realizada por el menú CANCELACIÓN de la terminal).

Si el consumidor de la aplicación de esta API ha completado con éxito su proceso comercial, pero no ha llamado al método confirmPayment(), la transacción permanecerá con el siguiente estado: Situación PayStore = "Pendiente". Resolución sobre el Comprador = "Pendiente".

Como resultado, es posible que tengamos una inconsistencia transaccional, ya que, al final del día, algunas redes adquirentes confirman automáticamente transacciones que no recibieron el tramo de confirmación. Otros adquirentes trabajan con solo dos tramos, sin necesidad de un tramo de confirmación. En este caso, si hay algún problema para completar la transacción en el lado del terminal, es imperativo que la solución de captura ejecute el método cancelPayment(), para deshacer la transacción en el adquirente y evitar cobrarle al cliente Titular de la Tarjeta.

Parámetros

Detalle de los Parámetros

callback

cancelPayment()¶

Este método siempre debe invocarse para deshacer una transacción en la que la terminal no pudo procesar completamente el tramo de autorización enviado por el Autorizador.

Este método no debe ser llamado para una transacción que ya ha sido confirmada, es decir, en la que se ha ejecutado previamente el método confirmPayment(), o en pagos con C�digo QR, ya que en este caso la transacción se confirma automáticamente.

Este método no debe ser llamado para deshacer una transacción que ya se ha deshecho, es decir, en la que se ha ejecutado previamente el método cancelPayment().

Este método no debe ser llamado para una transacción que haya sido denegada por el autorizador.

Este método no es un reverso. La inversión es la operación realizada por el menú CANCELACIÓN de la terminal. La reversión se realiza en transacciones que se han completado con éxito, es decir, que han sido confirmadas.

Después de ejecutar deshacer, cancelPayment(), la aplicación de la terminal ya no puede confirmar la transacción, es decir, el método confirmPayment() ya no se puede ejecutar.

Si la aplicación que consume esta API no ha completado con éxito su proceso de negocio, es esencial llamar al método cancelPayment(). La consecuencia de no cancelar una transacción que no ha completado su proceso de negocio es similar a la consecuencia de no confirmar. Sin embargo, en este caso, con un factor agravante, ya que es poco probable que el cliente tome el producto / servicio asociado con la transacción financiera, o se puede realizar un nuevo intento de venta, lo que resultará en un cargo doble para el Cliente Titular de la Tarjeta.

Parámetros

Detalle de los Parámetros

callback

Campo adicional api_pending¶

Además de los métodos de resolución de pago (confirmPayment ycancelPayment), existe la posibilidad de configurar un campo adicional en el Portal Paystore para realizar esta resolución de forma automática, en un momento determinado. Para esto, se debe crear un campo adicional en el Portal Paystore con el tipo JSON y la clave api_pending.

Valor del campo

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

Ejemplo de flujo de pago¶

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);
        /*
          Si, en su regla de comercial, necesita deshacer la transacción por algún motivo,
          llamar al método CancelPayment(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, "¡Confirmación del pago realizado con éxito!");
                        }


                    });
        } 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, "Deshacer completado!");
                        }


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

    }


}