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 |
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. |
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:
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).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;
}
}