Consulta de Estornos via API¶
Esta é uma consulta via Content Provider que possibilita que outros aplicativos possam consultar informações sobre os estornos, sendo possível realizar filtros e obter diversos dados dos estornos 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/reversals
URI (Uniform Resource Identifier) para obtenção de informações de estornos.
Para realizar o request da consulta 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 os estornos cuja situação está na lista passada (aceita mais de um valor). |
startDate |
Date |
Não | Filtra os estornos cuja data seja maior ou igual ao valor passado. |
finishDate |
Date |
Não | Filtra os estornos 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 do estorno (caso esse campo não seja prenchido ou receba 'false') ou na data e hora da última atualização do estorno (caso esse campo receba 'true'). |
startValue |
BigDecimal |
Não | Filtra os estornos cujo valor seja maior ou igual ao valor passado. |
finishValue |
BigDecimal |
Não | Filtra os estornos cujo valor seja menor ou igual ao valor passado. |
paymentId |
String |
Não | Filtra os estornos cujo identificador do pagamento para a aplicação de pagamentos seja o valor passado. |
lastDigits |
String |
Não | Filtra os estornos cujos últimos 4 dígitos do PAN do cartão seja igual ao valor passado. |
productShortName |
String |
Não | Identificador de produto, retorna apenas estornos feitos com um produto específico. |
ticketNumber |
String |
Não | ticketNumber gerado pelo terminal para o estorno. |
batchPend |
Boolean |
Não | Filtra os estornos que ainda estão estão no lote pendente (estornos novos). |
lastBatch |
Boolean |
Não | Filtra os estornos do último lote fechado. |
batchNumber |
String |
Não | Filtra os estornos de um lote com número específico (fechado ou aberto). |
acquirerResponseCode |
String |
Não | Filtra estornos com base no código de resposta do host. |
appTransactionId |
String |
Não | Filtra estornos com um Identificador especifico, informado pelo app integrado em reversePaymentV2(), no campo appTransactionId. |
Retorno¶
A consulta de estornos retorna os estornos referenciados que obedecerem aos filtros informados e os seus pagamentos associados.
Não retorna estornos que não obedecem aos filtros informados.
Os filtros informados são aplicados apenas aos campos dos estornos.
A lista de pagamentos retornados deve estar ordenada de forma ascendente pelo campo date do pagamento.
Em cada pagamento, a lista de estornos retornados deve estar ordenada de forma ascendente pelo campo date do estorno. Não retorna devoluções não referenciadas.
| Nome | Tipo | Descrição |
|---|---|---|
paymentId |
String |
Identificador da transação para a aplicação de pagamentos. Esta é a informação a ser usada para a confirmação e desfazimento. |
cancelable |
Boolean |
Indica 'true', caso esta transação possa ser desfeita e 'false' caso contrário. |
acquirerResponseCode |
String |
Código de resposta da adquirente. |
acquirerAuthorizationNumber |
String |
Número da autorização fornecido pela adquirente (consta no comprovante do cliente Portador do Cartão). |
Receipt.clientVia |
String |
Conteúdo do comprovante - via do cliente. |
Receipt.merchantVia |
String |
Conteúdo do comprovante - via do estabelecimento. |
acquirerAdditionalMessage |
String |
Mensagem adicional enviada pela adquirente na resposta da transação. |
ticketNumber |
String |
ticketNumber gerado pelo terminal para a transação. |
batchNumber |
String |
Número de lote. |
nsuTerminal |
String |
NSU gerado pelo terminal para a transação. |
cardholderName |
String |
Nome do cliente no cartão. |
cardBin |
String |
BIN do cartão. |
panLast4Digits |
String |
Últimos 4 dígitos do PAN do cartão. |
terminalId |
String |
Identificação do terminal. |
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. |
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. |
additionalValueType |
AdditionalValueType |
Presente apenas quando existe um valor adicional no contexto da transação executada. |
additionalValue |
BigDecimal |
Presente apenas quando existe um valor adicional no contexto da transação executada. |
lastTrx |
Boolean |
Indica 'true' se é a última transação aprovada, e 'false' caso contrário. |
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. |
correlationId |
String |
Identificador comum da transação entre terminal, PhAST e PayStore. Esse identificador em formato UUID é único para cada transação |
Exemplo de retorno¶
As estruturas "payment" e "reversals" são as mesmas usadas na consulta de última transação aprovada e confirmada;
- Quando dois estornos de um pagamento, e um estorno de outro pagamento obedecem aos critérios informados (por exemplo, filtro com status = CANCELLED):
[
{
"payment": {
...
},
"reversals": [
{
...
},
{
...
}
]
},
{
"payment": {
...
},
"reversals": [
{
...
}
]
}
]
Info
Para facilitar o uso, são disponibilizadas classes de acesso ao provider:
ReversalProviderRequestPaymentProviderApi
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
ReversalProviderRequest request = createRequest(applicationInfo);
try {
//solicitando a lista de estornos
List<TransactionProviderResponse> transactionsList = PaymentProviderApi.create(this).findAllReversals(request);
//********* Outra forma de realizar a consulta ******************************************
// 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);
//filtrando pelo paymentId
reversalRequest.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");
reversalRequest.setStartDate(dateStart);
reversalRequest.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
reversalRequest.setStartValue(new BigDecimal("0.00"));
reversalRequest.setFinishValue(new BigDecimal("1000.00"));
//filtrando pelos 4 últimos dígitos do cartão
reversalRequest.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 reversalRequest;
}
}