Consulta de Anulación/Devolución vía API¶
Esta es una consulta vía Content Provider que permite a otras aplicaciones consultar información sobre Anulación/Devolución, pudiendo realizar filtros y obtener diferentes datos de las Anulación/Devolución según el objeto de retorno.
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/reversals
URI (Uniform Resource Identifier) para información de anulación/devolución.
Para realizar la solicitud de consulta 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 |
ReversalStatus |
No | Filtra reversiones cuya situación se encuentra en la última lista (acepta más de un valor). |
startDate |
Date |
No | Filtra reversiones cuya fecha es mayor o igual al valor pasado. |
finishDate |
Date |
No | Filtra reversiones cuya fecha es menor o igual al valor pasado. |
lastUpdateQuery |
Boolean |
No | Indica si la consulta se basará en la fecha y hora de la reversión (si este campo no se llena o recibe 'falso') o en la fecha y hora de la última actualización de la reversión (si este campo recibe 'verdadero'). |
startValue |
BigDecimal |
No | Filtra reversiones cuyo valor es mayor o igual al valor pasado. |
finishValue |
BigDecimal |
No | Filtra reversiones cuyo valor es menor o igual al valor pasado. |
paymentId |
String |
No | Filtra reversiones cuyo identificador de pago para la aplicación de pago es el valor pasado. |
lastDigits |
String |
No | Filtra reversiones cuyos últimos 4 dígitos del PAN de la tarjeta son iguales al último valor. |
productShortName |
String |
No | Identificador de producto, solo devoluciones contracargos realizados con un producto específico. |
ticketNumber |
String |
No | ticketNumber generado por el terminal para la reversión. |
batchPend |
Boolean |
No | Filtra las reversiones que todavía están en el lote pendiente (nuevas reversiones). |
lastBatch |
Boolean |
No | Filtra las reversiones del último lote cerrado. |
batchNumber |
String |
No | Filtre las reversiones de un lote con un número específico (cerrado o abierto). |
acquirerResponseCode |
String |
No | Filtra las reversiones según el código de respuesta del host. |
appTransactionId |
String |
No | Filtra reversiones con un identificador específico, informado por la aplicación integrada en reversePaymentV2(), en el campo appTransactionId. |
Retorno¶
La consulta de Anulación/Devolución devuelve las reversiones referenciadas que cumplen con los filtros informados, y sus pagos asociados.
No devuelve Anulación/Devolución que no cumplan con los filtros informados.
Los filtros informados se aplican solo a los campos de reversión.
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 |
|---|---|---|
paymentId |
String |
Identificador de transacción para la aplicación de pago. Esta es la información que se utilizará para confirmar y deshacer. |
cancelable |
Boolean |
Indica 'true', si esta transacción se puede deshacer y 'false' en caso contrario. |
acquirerResponseCode |
String |
Código de respuesta del adquirente. |
acquirerAuthorizationNumber |
String |
Número de autorización proporcionado por el adquirente (aparece en el recibo de cliente del Titular de la Tarjeta). |
Receipt.clientVia |
String |
Contenido del cupón: copia del cliente. |
Receipt.merchantVia |
String |
Contenido del cupón - copia del establecimiento. |
acquirerAdditionalMessage |
String |
Mensaje adicional enviado por el adquirente en la respuesta de la transacción. |
ticketNumber |
String |
ticketNumber generado por el terminal para la transacción. |
batchNumber |
String |
Numero de lote. |
nsuTerminal |
String |
NSU generado por el terminal para la transacción. |
cardholderName |
String |
Nombre del cliente en la tarjeta. |
cardBin |
String |
BIN de la tarjeta. |
panLast4Digits |
String |
Últimos 4 dígitos del PAN de la tarjeta. |
terminalId |
String |
Identificación de terminales. |
value |
BigDecimal |
Valor de la transacción. Este es el valor que fue aprobado por el adquirente. Siempre se debe validar en la respuesta, aunque se haya pasado como parámetro, ya que hay compradores que para algunas situaciones aprueban valores diferentes a los solicitados. |
captureType |
CaptureType |
Formas de capturar la tarjeta. |
status |
PaymentStatus |
Estado de pago. |
date |
Date |
Fecha/hora de pago para la aplicación de pagos. Data/hora do pagamento para a aplicação de pagamentos. |
additionalValueType |
AdditionalValueType |
Solo presente cuando hay un valor adicional en el contexto de la transacción ejecutada. |
additionalValue |
BigDecimal |
Solo presente cuando hay un valor adicional en el contexto de la transacción ejecutada. |
lastTrx |
Boolean |
Indica 'true' ' si es la última transacción aprobada y 'falso' en caso contrario. |
appTransactionId |
String |
Identificador de transacción para la aplicación de pago. 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. |
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¶
Las estructuras de "pago" y "reversiones" son las mismas que se utilizan en la consulta última transacción aprobada y confirmada;
- Cuando dos reversiones de un pago y una reversión de otro pago cumplen con los criterios informados (por ejemplo, filtro con estado = CANCELLED):
[
{
"payment": {
...
},
"reversals": [
{
...
},
{
...
}
]
},
{
"payment": {
...
},
"reversals": [
{
...
}
]
}
]
Info
Para facilitar el uso, se dispone de clases de acceso al provider:
ReversalProviderRequestPaymentProviderApi
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() {
//Establecer las credenciais
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");
//criando objeto de request para o payment content provider
ReversalProviderRequest request = createRequest(applicationInfo);
try {
//solicitando a lista de reversiones
List<TransactionProviderResponse> transactionsList = PaymentProviderApi.create(this).findAllReversals(request);
//********* Otra forma de consultar ******************************************
// Cursor cursor = getApplicationContext().getContentResolver().query(request.getUriBuilder().build(), null, null, null, null);
// List<TransactionProviderResponse> transactionsList = TransactionProviderResponse.fromCursor(cursor);
//***************************************************************************************
Toast.makeText(this, transactionsList.size()+"", Toast.LENGTH_LONG).show();
} catch (Exception e) {
Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
Log.e(TAG, e.getMessage(), e);
}
}
private ReversalProviderRequest createRequest(ApplicationInfo appInfo) {
ReversalProviderRequest reversalRequest = new ReversalProviderRequest();
reversalRequest.setApplicationInfo(appInfo);
//Filtrado por ID de pago
reversalRequest.setPaymentId("000000000");
//filtrado 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");
reversalRequest.setStartDate(dateStart);
reversalRequest.setFinishDate(dateFinish);
} catch (Exception e) {
Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
Log.e(TAG, e.getMessage(), e);
}
//filtrado por rango de montos de pago
reversalRequest.setStartValue(new BigDecimal("0.00"));
reversalRequest.setFinishValue(new BigDecimal("1000.00"));
//filtrado por los últimos 4 dígitos de la tarjeta
reversalRequest.setLastDigits("9636");
//filtrado por los últimos 4 dígitos de la tarjeta
List<ReversalStatus> status = Arrays.asList(new ReversalStatus[]{
ReversalStatus.PENDING,
ReversalStatus.PROCESSING,
ReversalStatus.CONFIRMED,
ReversalStatus.CANCELLED
});
return reversalRequest;
}
}