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 |
Sí | Identificación de la aplicación que está realizando la consulta. |
secretToken |
Credentials |
Sí | Token de acceso de la aplicación que está realizando la consulta. |
softwareVersion |
String |
Sí | 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:
PaymentProviderRequestPaymentProviderApiPaymentContract
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
Sí pleDateFormat isoFormat = new Sí 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;
}
}