Ir para o conteúdo

Consulta de Devolução não referenciada via API

Esta é uma consulta via Content Provider que possibilita que outros aplicativos possam consultar informações sobre devoluções não referenciadas, sendo possível realizar filtros e obter diversos dados das devoluções não referenciadas, conforme objeto de retorno.


Integração com Aplicação de Pagamentos via Content Provider

Só será permitido listar pagamentos feitos pela própria aplicação que está realizando a consulta.

Declare essa permissão no AndroidManifest.xml do seu Aplicativo para ter acesso ao 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 obtenção de informações de devoluções não referenciadas.

Para realizar o request da consulta de pagamento por período entre datas, é necessário adicionar esta dependência:

implementation 'com.jakewharton.threetenabp:threetenabp:1.0.3'

Parâmetros de entrada

Nome Tipo Obrigatório Descrição
applicationId Credentials Sim Identificação da aplicação que está realizando a consulta.
secretToken Credentials Sim Token de acesso da aplicação que está realizando a consulta.
softwareVersion String Sim Versão da aplicação que está solicitando a consulta.

Filtros

Nome Tipo Obrigatório Descrição
status ReversalStatus Não Filtra as devoluções não referenciadas cuja situação está na lista passada (aceita mais de um valor).
startDate Date Não Filtra as devoluções não referenciadas cuja data seja maior ou igual ao valor passado.
finishDate Date Não Filtra as devoluções não referenciadas cuja data seja menor ou igual ao valor passado.
lastUpdateQuery Boolean Não Indica se a consulta será feita com base na data e hora da devolução não referenciada (caso esse campo não seja preenchido ou receba 'false') ou na data e hora da última atualização da devolução não referenciada (caso esse campo receba 'true').
startValue BigDecimal Não Filtra as devoluções não referenciadas cujo valor seja maior ou igual ao valor passado.
finishValue BigDecimal Não Filtra as devoluções não referenciadas cujo valor seja menor ou igual ao valor passado.
refundId String Não Filtra as devoluções não referenciadas cujo identificador para a aplicação de pagamentos seja o valor passado.
lastDigits String Não Filtra as devoluções não referenciadas cujos últimos 4 dígitos do PAN do cartão usado na transação seja igual ao valor passado.
productShortName String Não Identificador de produto, retorna apenas as devoluções não referenciadas feitas com um produto específico.
ticketNumber String Não ticketNumber gerado pelo terminal para a devolução.
batchPend Boolean Não Filtra as devoluções não referenciadas que ainda estão estão no lote pendente (devoluções novas).
lastBatch Boolean Não Filtra as devoluções não referenciadas do último lote fechado.
batchNumber String Não Filtra as devoluções não referenciadas de um lote com número específico (fechado ou aberto).
acquirerResponseCode String Não Filtra as devoluções não referenciadas com base no código de resposta do host.
appTransactionId String Não Filtra as devoluções não referenciadas com um Identificador especifico, informado pelo app integrado em reversePaymentV2(), no campo appTransactionId.

Retorno

A consulta de devolução não referenciada, retorna as devoluções não referenciadas que obedecerem aos filtros informados.

Os filtros informados são aplicados apenas aos campos das devoluções não referenciadas.

A lista de devoluções não referenciadas retornadas deve estar ordenada de forma ascendente pelo campo date.

Nome Tipo Descrição
id String Identificador da transação para a aplicação de pagamentos.
value BigDecimal Valor da transação. Este é o valor que foi aprovado pela adquirente. Deve ser validado sempre na resposta, ainda que tenha sido passado como parâmetro, pois há adquirentes que, para algumas situações, aprovam valores diferentes dos solicitados.
paymentType PaymentType Tipo de pagamento (Débito, Crédito, Voucher, etc.).
acquirerName String Adquirente que autorizou o pagamento.
cardBrand String Bandeira do cartão.
cardBin String BIN do cartão.
cardPanLast4Digits String Últimos 4 dígitos do PAN do cartão.
captureType CaptureType Forma de captura do cartão.
status PaymentStatus Situação do pagamento.
date Date Data/hora do pagamento para a aplicação de pagamentos.
acquirerId String Identificador da transação para a adquirente. Este é o identificador que consta no arquivo que a adquirente fornece (EDI). Desta forma, é possível realizar a conciliação do pagamento com a transação integrada.
acquirerResponseCode String Código de resposta da adquirente.
acquirerResponseDate String Data/hora retornada pela adquirente.
acquirerAuthorizationNumber String Número da autorização fornecido pela adquirente (consta no comprovante do cliente Portador do Cartão).
clientVia String Conteúdo do comprovante - via do cliente.
merchantVia String Conteúdo do comprovante - via do estabelecimento.
accountTypeId String Presente apenas quando existe um tipo de conta no contexto da transação executada.
productShortName String Identificador de produto, retorna apenas transações de um produto.
batchNumber String Número de lote.
nsuTerminal String NSU gerado pelo terminal para a transação.
cardholderName String Nome do cliente no cartão.
lastTrx Boolean Indica 'true' se é a última transação aprovada, e 'false' caso contrário.
terminalId String Identificação do terminal.
appTransactionId String Identificador de transação para o aplicativo de pagamento. Esta é a informação que será usada para confirmar e desfazer o pagamento.
acquirerNsu String NSU Adquirente para consulta e identificação de transações.
ErrorData.paymentsResponseCode String Código de resposta para o erro que ocorreu. Vide Códigos de Resposta
ErrorData.responseMessage String Mensagem descritiva da causa da não autorização. Se a transação foi negada pela adquirente, conterá a mensagem retornada pela adquirente.
Exemplo de retorno

A estrutura "refund" é a mesma usada na consulta de última transação aprovada e confirmada;

  • Quando 2 devoluções obedecem aos critérios informados:
{
  [
     {
        "refund": { 
            ...
        }       
     },
     {
        "refund": { 
            ...
        }   
     }   
  ]
}

Info

Para facilitar o uso, são disponibilizadas classes de acesso ao provider:

  • RefundProviderRequest
  • PaymentProviderApi
Exemplo
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");

        //criando objeto de request para o payment content provider
        RefundProviderRequest request = createRequest(applicationInfo);

        try {
            //solicitando a lista de devolução não referenciada
            List<RefundProviderResponse> refundList = PaymentProviderApi.create(this).findAllRefunds(request);
            //********* Outra forma de realizar a consulta ******************************************
            // 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 pelo refundId
        refundRequest.setRefundId("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");
            refundRequest.setStartDate(dateStart);
            refundRequest.setFinishDate(dateFinish);
        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);

        }

        //filtrando por faixa de valores de pagamento
        refundRequest.setStartValue(new BigDecimal("0.00"));
        refundRequest.setFinishValue(new BigDecimal("1000.00"));

        //filtrando pelos 4 últimos dígitos do cartão
        refundRequest.setLastDigits("9636");

        //filtrando pelos 4 últimos dígitos do cartão
        List<ReversalStatus> status = Arrays.asList(new ReversalStatus[]{
                     ReversalStatus.PENDING,
                     ReversalStatus.PROCESSING,
                     ReversalStatus.CONFIRMED,
                     ReversalStatus.CANCELLED
             });

        return refundRequest;
    }


}