Ir para o conteúdo

Consulta de Pagos vía API


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 para realizar las llamadas de integración.

Mediante esta API es posible realizar todo el flujo de pago, es decir, confirmación (o deshacer). Además, es posible informar una lista de tipos de pagos (débito, crédito en efectivo, 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 de la terminal, como mensajes (por ejemplo, "Insertar o deslizar la tarjeta"), o incluso solicitar información al titular (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.

Integración con la aplicación de pago a través de Content Provider

Integración vía Content Provider permite a otras aplicaciones consultar información sobre los pagos realizados, posibilitando la realización de filtros y la obtención de diversos datos de pago, incluida su situación.

Solo se permitirá listar los pagos realizados por la aplicación que está realizando la consulta.

Declare este permiso en el archivo AndroidManifest.xml de su aplicación para obtener acceso al Content Provider.

<uses-permission android:name="br.com.phoebus.android.payments.provider.READ_PERMISSION"/>

content://br.com.phoebus.android.payments.provider/payments

URI (Uniform Resource Identifier) para información de pago.

Para realizar la solicitud de consulta de pago por período entre fechas es necesario agregar esta dependencia.

implementation 'com.jakewharton.threetenabp:threetenabp:1.0.3'

Filtros

Nombre Tipo Obligatorio Descripción
status PaymentStatus No Filtra los pagos cuyo estado está en la lista anterior (acepta más de un monto).
startDate Date No Filtra los pagos cuya fecha es mayor o igual que el montopasada.
finishDate Date No Filtra los pagos cuya fecha es menor o igual que el monto anterior.
lastUpdateQuery Boolean No Indica si la consulta se realizará en base a la fecha y hora de la transacción (si este campo no se completa o recibe 'false') o en la fecha y hora de su última actualización (si este campo recibe 'true').
startValue BigDecimal No Filtra los pagos cuyo valor es mayor o igual al monto pasado.
finishValue BigDecimal No Filtra los pagos cuyo valor es menor o igual al monto pasado.
paymentId String No Filtra los pagos cuyo identificador de transacción para la aplicación de pagos es el monto transferido.
lastDigits String No Filtra los pagos cuyos últimos 4 dígitos del PAN de la tarjeta utilizada en la transacción es igual al monto pasado.
applicationId Credentials Identificación de la aplicación que está realizando la consulta.
secretToken Credentials Token de acceso de la aplicación que está realizando la consulta.
softwareVersion String Versión de la aplicación que solicita la consulta.
productShortName String No Identificador de producto, devuelve solo transacciones de un producto.
ticketNumber String No ticketNumber generado por el terminal para la transacción.
batchPend Boolean No Filtra las transacciones que aún están en el lote pendiente (nuevas transacciones).
lastBatch Boolean No Filtra las transacciones del último lote cerrado.
batchNumber String No Filtra transacciones de un lote.
acquirerResponseCode String No Filtra transacciones según el código de respuesta del host.
lastTrx Boolean No Filtra la última transacción aprobada.
trxType String No Filtra las transacciones por tipo ("1" - Venta, "2" - Devolución sin referencia).
note String No Texto adicional que se ingresa como Nota. (puede ser el número de factura)
dni String No Número del Documento.
qrId String No Identificador de QrCode generado por el terminal de captura.
operationMethod Integer No Filtra transacciones según la forma de operación. Admita los siguientes valores: 0 - Solo con tarjeta física (leída o mecanografiada); 1 - Solo con QRCode.
appTransactionId String No Identificador de transacción integrado para el software. El identificador referido es el utilizado en la aplicación que originó la solicitud de pago.

Retorno

Nombre Tipo Descripción
id String Identificador de transacción para la aplicación de pagos. Esta es la información que se utilizará para confirmar y deshacer.
value BigDecimal Monto del pago. Este es el monto que fue aprobado por el adquirente. Siempre debe estar validado en la respuesta, incluso si se ha pasado como parámetro, ya que hay compradores que, para algunas situaciones, aprueban valores distintos a los solicitados.
paymentType PaymentType Tipo de pago (débito, crédito, voucher, etc.).
installments Integer Número de cuotas de pago.
acquirerName String Comprador que autorizó el pago.
cardBrand String Banner de tarjeta.
cardBin String BIN de la tarjeta.
cardPanLast4Digits String Últimos 4 dígitos del PAN de la tarjeta.
captureType CaptureType Forma de capturar de la tarjeta.
status PaymentStatus Estado de pago.
date Date Fecha/hora de pago para la aplicación de pagos.
acquirerId String Identificador de transacción para el adquirente. Este es el identificador en el archivo proporcionado por el adquirente (EDI). De esta forma, es posible conciliar el pago con la transacción integrada.
acquirerResponseCode String Código de respuesta del adquirente.
acquirerResponseDate String Fecha/hora devuelta por el adquirente.
acquirerAuthorizationNumber String Número de autorización proporcionado por el adquirente (que se muestra en el recibo del cliente del Titular de la tarjeta).
receiptClient String Contenido del recibo - recibo del cliente.
receiptMerchant String Contenido del recibo - recibo del establecimiento.
additionalValueType AdditionalValueType Presente solo cuando existe un monto adicional en el contexto de la transacción ejecutada.
additionalValue BigDecimal Presente solo cuando existe un monto adicional en el contexto de la transacción ejecutada.
accountTypeId String Presente solo cuando existe un tipo de cuenta en el contexto de la transacción ejecutada.
planId String Presente solo cuando existe un plan en el contexto de la transacción ejecutada.
productShortName String Identificador de producto, devuelve solo transacciones de un producto.
batchNumber String Número de lote.
nsuTerminal String NSU generado por la terminal para la transacción. Los 4 dígitos de la derecha corresponden al Ticket Number. Esta NSU es informada por la terminal para PhAST en el parámetro "merchantTransactionId".
cardholderName String Nombre del cliente en la tarjeta.
lastTrx Boolean Indica 'true' se a última transação foi aprovada e 'false' caso contrário.
terminalId String Identificação do terminal.
originalValue BigDecimal Valor orginal de la venta. Presente en pagos con QRCode, cuyo beneficio se haya aplicado al valor original de la venta.
appTransactionId String Identificador de transacción para la aplicación de pagos. Esta es la información que se utilizará para confirmar y deshacer el pago.
acquirerNsu String NSU Acquirer para consulta e identificación de transacciones.

Info

Puede personalizar qué información estará presente en la respuesta. Para hacer esto, se debe pasar un array de Strings con las columnas deseadas al método query() del Content Resolver. Si usa la API de acceso al proveedor, puede usar el método setColumns() del PaymentProviderRequest.

Info

Para facilitar el uso, se encuentran disponibles clases de acceso al proveedor:

  • PaymentProviderRequest
  • PaymentProviderApi
  • PaymentContract
Ejemplo
import androidx.appcompat.app.AppCompatActivity;

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

import com.jakewharton.threetenabp.AndroidThreeTen;

import java.math.BigDecimal;

import java.text.SimpleDateFormat;
import java.util.Arrays;

import java.util.Date;
import java.util.List;
import java.util.TimeZone;

import br.com.phoebus.android.payments.api.ApplicationInfo;
import br.com.phoebus.android.payments.api.Credentials;

import br.com.phoebus.android.payments.api.Payment;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.PaymentStatus;
import br.com.phoebus.android.payments.api.provider.PaymentContract;
import br.com.phoebus.android.payments.api.provider.PaymentProviderApi;
import br.com.phoebus.android.payments.api.provider.PaymentProviderRequest;

public class MainActivity extends AppCompatActivity implements View.OnClickListener {

    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();
        AndroidThreeTen.init(getApplication());

    }


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


    public void doExecute() {
        //estableciendo las credenciales
        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");

        //creando objeto request para payment content provider
        PaymentProviderRequest request = createRequest(applicationInfo);

        //seleccionando propiedades devueltas
        String[] columns = new String[]{
                PaymentContract.column.ID,
                PaymentContract.column.VALUE,
                PaymentContract.column.PAYMENT_STATUS,
                PaymentContract.column.PAYMENT_DATE,
                PaymentContract.column.CARD_BRAND,
        };

        try {
            //solicitando la lista de pagos
            request.setColumns(columns);
            List<Payment> paymentsList = PaymentProviderApi.create(this).findAll(request);
            //********* Otra forma de realizar la consulta ******************************************
            // Cursor cursor = getApplicationContext().getContentResolver().query(request.getUriBuilder().build(), columns, null, null, null);
            // List<Payment> paymentsList = Payment.fromCursor(cursor);
            //***************************************************************************************

            Toast.makeText(this, paymentsList.size()+"", Toast.LENGTH_LONG).show();

        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }
    }

    private PaymentProviderRequest createRequest(ApplicationInfo appInfo) {


        PaymentProviderRequest paymentRequest = new PaymentProviderRequest();
        paymentRequest.setApplicationInfo(appInfo);


        //filtrando por paymentId
        paymentRequest.setPaymentId("000000000");

        //filtrando por período
         pleDateFormat isoFormat = new  pleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS");
        isoFormat.setTimeZone(TimeZone.getTimeZone("UTC"));

        try {

            Date dateStart = isoFormat.parse("2020-04-06T00:00:00.000");
            Date dateFinish =isoFormat.parse("2020-04-06T23:59:59.000");
            paymentRequest.setStartDate(dateStart);
            paymentRequest.setFinishDate(dateFinish);
        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);

        }

        //filtrando por rango de montos de pago
        paymentRequest.setStartValue(new BigDecimal("0.00"));
        paymentRequest.setFinishValue(new BigDecimal("1000.00"));

        //filtrando por los últimos 4 dígitos de la tarjeta
        paymentRequest.setLastDigits("9636");

        //filtrando por los últimos 4 dígitos de la tarjeta
        List<PaymentStatus> status = Arrays.asList(new PaymentStatus[]{
                PaymentStatus.PENDING,
                PaymentStatus.CONFIRMED,
                PaymentStatus.CANCELLED,
                PaymentStatus.REVERSED
        });

        return paymentRequest;
    }


}