Ir para o conteúdo

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 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 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:

  • ReversalProviderRequest
  • PaymentProviderApi
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;
    }


}