Ir para o conteúdo

Consulta de devolución no referenciada a través de API


Se trata de una consulta vía Content Provider que permite a otras aplicaciones consultar información sobre declaraciones no referenciadas, pudiendo realizar filtros y obtener diferentes datos de declaraciones no referenciadas, según el objeto de la declaración.

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

URI (Uniform Resource Identifier) para información de devolución no referenciada.

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 Não Filtra declaraciones no referenciadas cuyo estado está en la lista aprobada (acepta más de un valor).
startDate Date Não Filtra las declaraciones sin referencia cuya fecha es mayor o igual que el valor pasado.
finishDate Date Não Filtra las declaraciones sin referencia cuya fecha es menor o igual que el valor pasado.
lastUpdateQuery Boolean Não Indica si la consulta se basará en la fecha y hora de la declaración no referenciada (si este campo no está lleno o recibe 'false') o en la fecha y hora de la última actualización de la declaración no referenciada (si este campo recibe 'true').
startValue BigDecimal Não Filtra las declaraciones no referenciadas cuyo valor es mayor o igual que el valor pasado.
finishValue BigDecimal Não Filtra las declaraciones no referenciadas cuyo valor es menor o igual que el valor pasado.
refundId String Não Filtra declaraciones no referenciadas cuyo identificador para la aplicación de pago es el valor pasado.
lastDigits String Não Filtra devoluciones no referenciadas cuyos 4 últimos dígitos del PAN de la tarjeta utilizada en la transacción sean iguales al valor pasado.
productShortName String Não Identificador de producto, devoluciones solo devoluciones no referenciadas realizadas con un producto específico.
ticketNumber String Não ticketNumber generado por el terminal para la devolución.
batchPend Boolean Não Filtra las devoluciones sin referencia que todavía están en el lote pendiente (nuevas devoluciones).
lastBatch Boolean Não Filtra las devoluciones sin referencia del último lote cerrado.
batchNumber String Não Filtra devoluciones no referenciadas de un lote con un número específico (cerrado o abierto).
acquirerResponseCode String Não Filtra los rebotes sin referencia según el código de respuesta del host.
appTransactionId String Não Filtra las devoluciones que no están referenciadas con un Identificador específico, informado por la aplicación integrada en reversePaymentV2(), en el campo appTransactionId.

Retorno

La consulta de devolución no referenciada devuelve las declaraciones no referenciadas que cumplen con los filtros informados.

Los filtros informados se aplican solo a los campos de declaraciones no referenciadas.

La lista de rebotes sin referencia devueltos debe ordenarse en orden ascendente por el campo date.

Nombre Tipo Descripción
id String Identificador de transacción para la aplicación de pago.
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.
paymentType PaymentType Tipo de pago (Débito, Crédito, Vale, etc.).
acquirerName String Adquirente que autorizó el pago.
cardBrand String Bandera de la 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 que aparece en el fichero que proporciona 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 (aparece en el recibo de cliente del Titular de la Tarjeta).
clientVia String Contenido del cupón - copia del cliente.
merchantVia String Contenido del cupón - copia del establecimiento.
accountTypeId String Solo presente cuando existe un tipo de cuenta en el contexto de la transacción ejecutada.
productShortName String Identificador de producto, devuelve solo transacciones de un producto.
batchNumber String Numero de lote.
nsuTerminal String NSU generado por el terminal para la transacción.
cardholderName String Nombre del cliente en la tarjeta.
lastTrx Boolean Indica 'true' si es la última transacción aprobada y 'false' en caso contrario.
terminalId String Identificación de terminales.
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.
Ejemplo de retorno

La estructura de "refund" es la misma que se usa en la consulta última transacción aprobada y confirmada;

  • Cuando 2 declaraciones cumplen los criterios informados:
{
  [
     {
        "refund": { 
            ...
        }       
     },
     {
        "refund": { 
            ...
        }   
     }   
  ]
}

Info

Para facilitar el uso, acceda a las clases del provider:

  • RefundProviderRequest
  • 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() {
        //definindo as 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");

        //creación de objeto de solicitud de pago content provider
        RefundProviderRequest request = createRequest(applicationInfo);

        try {
            //solicitando lista de refund
            List<RefundProviderResponse> refundList = PaymentProviderApi.create(this).findAllRefunds(request);
            //********* Otra forma de consultar ******************************************
            // Cursor cursor = getApplicationContext().getContentResolver().query(request.getUriBuilder().build(), null, null, null, null);
            // List<RefundProviderResponse> refundList = RefundProviderResponse.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 RefundProviderRequest createRequest(ApplicationInfo appInfo) {


        RefundProviderRequest refundRequest = new RefundProviderRequest();
        refundRequest.setApplicationInfo(appInfo);


        //filtrando a través  refundId
        refundRequest.setRefundId("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");
            refundRequest.setStartDate(dateStart);
            refundRequest.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
        refundRequest.setStartValue(new BigDecimal("0.00"));
        refundRequest.setFinishValue(new BigDecimal("1000.00"));

        //filtrado por los últimos 4 dígitos de la tarjeta
        refundRequest.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 refundRequest;
    }


}