Ir para o conteúdo

Consulta de Pagos V2 vía API


Se trata de una consulta a través de Content Provider que permite a otras aplicaciones consultar información sobre los pagos realizados, pudiendo realizar filtros y obtener diversos datos de los pagos, incluido su estado.

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

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/transactions

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'

Parámetros de entrada

Nombre Tipo Obligatorio Descripción
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.

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 monto pasada.
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.
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.
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

La consulta de pago devuelve los pagos que cumplen con los filtros informados y las reversiones asociadas a los mismos (incluyendo las reversiones denegadas).

Los filtros informados se aplican solo a los campos de pago.

La lista de pagos devueltos debe ordenarse en orden ascendente por el campo date del pago.

En cada pago, la lista de reversiones devueltas debe ordenarse en orden ascendente por el campo date de la reversión. No devuelve devoluciones no referenciadas.

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).
clientVia String Contenido del recibo - recibo del cliente.
merchantVia 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.
ticketNumber String ticketNumber generado por el terminal para la transacción.
acquirerAdditionalMessage String Mensaje adicional enviado por el adquirente en la respuesta a la transacción.
note String Texto adicional que se ingresa como Nota. (puede ser el número de factura)
dni String Numero del Documento.
aid String AID para identificación de la aplicación que procesa la transacción. Es regresado en transaccións EMV.
cardAppName String APN, o nombre de la aplicación de la tarjeta. Es regresado en transaccións EMV.
ErrorData.paymentsResponseCode String Código de respuesta para el error que ocurrió. Ver Códigos de respuesta
ErrorData.responseMessage String Mensaje descriptivo de la causa de la autorización. Si la transacción ha sido denegada por el adquirente, contendrá el mensaje devuelto por el adquirente.
correlationId String Identificador común de la transacción entre terminal, PhAST y PayStore. Este identificador en formato UUID es único para cada transacción
Ejemplo de devolución cuando dos pagos cumplen los criterios informados

Las estructuras "payments" y "reversals" son las mismas que se utilizan en la consulta última transacción aprobada y confirmada;

[
 {
    "payment": {
        ...
    },
    "reversals": [
      {
         ...
      },
      {
         ...
      },
      {
         ...
      }
    ]
 },
 {
    "payment": {
        ...
    },
    "reversals": [
      {
         ...
      },
      {
         ...
      },
      {
         ...
      }
    ]
 }
]

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. 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).findAllTransactions(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
        SimpleDateFormat isoFormat = new SimpleDateFormat("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;
    }


}