Ir para o conteúdo

Reversal query via API


This is a query via Content Provider that allows other applications to query information about reversals, making it possible to perform filters and obtain different data from reversals according to the return object.

Integration with Payment Application via Content Provider

It will only be allowed to list payments made by the application that is performing the query.

Declare this permission in your Application's AndroidManifest.xml to have access to the 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) for obtaining reversal information.

To request the query by period between dates, it is necessary to add this dependency.

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

Input parameters

Name Type Mandatory Description
applicationId Credentials Yes Identification of the application that is performing the query.
secretToken Credentials Yes Access token of the application performing the query.
softwareVersion String Yes Version of the application that is requesting the query.

Filters

Name Type Mantatory Description
status ReversalStatus No Filter reversals whose situation is in the last list (accepts more than one value).
startDate Date No Filters reversals whose date is greater than or equal to the passed value.
finishDate Date No Filters reversals whose date is less than or equal to the passed value.
lastUpdateQuery Boolean No Indicates whether the query will be based on the reversal date and time (if this field is not filled in or receives 'false') or the date and time of the last reversal update (if this field receives 'true').
startValue BigDecimal No Filters reversals whose value is greater than or equal to the passed value.
finishValue BigDecimal No Filters reversals whose amount is less than or equal to the passed amount.
paymentId String No Filters reversals whose payment identifier for the payment application is the amount passed.
lastDigits String No Filters reversals whose last 4 digits of the card's PAN are equal to the last value.
productShortName String No Product identifier, only returns reversals made with a specific product.
ticketNumber String No ticketNumber generated by the terminal for the reversal.
batchPend Boolean No Filters reversals that are still in the pending batch (new reversals).
lastBatch Boolean No Filters reversals from the last batch closed.
batchNumber String No Filter reversals of a batch with a specific number (closed or open).
acquirerResponseCode String No Filters reversals based on host response code.
appTransactionId String No Filters reversals with a specific Identifier, informed by the integrated app in reversePaymentV2(), in the appTransactionId field.

Return

The reversal query returns the referenced reversals that comply with the filters informed, and their associated payments.

Does not return reversals that do not comply with the informed filters.

The informed filters are applied only to reversal fields.

The list of returned payments must be sorted in ascending order by the date field of the payment.

In each payment, the list of reversals returned must be sorted in ascending order by the date field of the reversal. Does not return unreferenced returns.

Name Type Description
paymentId String Transaction identifier for the payment application. This is the information to be used for commit and undo.
cancelable Boolean Indicates 'true' if this transaction can be undone and 'false' otherwise.
acquirerResponseCode String Acquirer response code.
acquirerAuthorizationNumber String Authorization number provided by the acquirer (it appears on the Card Holder customer receipt).
Receipt.clientVia String Receipt content - customer copy.
Receipt.merchantVia String Receipt content - merchant copy.
acquirerAdditionalMessage String Additional message sent by the acquirer in the transaction response.
ticketNumber String ticketNumber generated by the terminal for the transaction.
batchNumber String Lot number.
nsuTerminal String NSU generated by the terminal for the transaction.
cardholderName String Customer name on card.
cardBin String Card BIN.
panLast4Digits String Last 4 digits of the card's PAN.
terminalId String Terminal identification.
value BigDecimal Transaction value. This is the value that was approved by the acquirer. It must always be validated in the response, even if it has been passed as a parameter, as there are buyers who, for some situations, approve values ​​different from those requested.
captureType CaptureType Card capture form.
status PaymentStatus Payment status.
date Date Payment date/time for the payments application.
additionalValueType AdditionalValueType Only present when there is an additional value in the context of the executed transaction.
additionalValue BigDecimal Only present when there is an additional value in the context of the executed transaction.
lastTrx Boolean Indicates 'true' if it is the last approved transaction, and 'false' otherwise.
appTransactionId String Transaction identifier for the payment application. This is the information that will be used to confirm and undo the payment.
acquirerNsu String NSU Acquirer for consultation and identification of transactions.
ErrorData.paymentsResponseCode String Response code for the error that occurred. See Response Codes
ErrorData.responseMessage String Descriptive message of the reason for the non-authorization. If the transaction was denied by the acquirer, it will contain the message returned by the acquirer.
correlationId Uuid Common transaction identifier between terminal, PhAST and PayStore. This identifier in UUID format is unique for each transaction
Return example

The "payment" and "reversals" structures are the same used in the last approved and confirmed transaction query;

  • When two reversals of a payment, and one reversal of another payment meet the informed criteria (for example, filter with status = CANCELLED):
[
 {
    "payment": {
        ...
    },
    "reversals": [
      {
         ...
      },
      {
         ...
      }
    ]
 },
 {
    "payment": {
        ...
    },
    "reversals": [
      {
         ...
      }
    ]
 }
]

Info

To facilitate the use, access classes to the provider are available:

  • ReversalProviderRequest
  • PaymentProviderApi
Example
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() {
        //setting the credentials
        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");

        //creating request object for payment content provider
        ReversalProviderRequest request = createRequest(applicationInfo);

        try {
            //requesting the list of reversals
            List<TransactionProviderResponse> transactionsList = PaymentProviderApi.create(this).findAllReversals(request);
            //********* Another way to query ******************************************
            // 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);

        //filtering by paymentId
        reversalRequest.setPaymentId("000000000");

        //filtering by period
        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);

        }

        //filtering by range of payment amounts
        reversalRequest.setStartValue(new BigDecimal("0.00"));
        reversalRequest.setFinishValue(new BigDecimal("1000.00"));

        //filtering by the last 4 digits of the card
        reversalRequest.setLastDigits("9636");

        //filtering by the last 4 digits of the card
        List<ReversalStatus> status = Arrays.asList(new ReversalStatus[]{
                ReversalStatus.PENDING,
                ReversalStatus.PROCESSING,
                ReversalStatus.CONFIRMED,
                ReversalStatus.CANCELLED
        });

        return reversalRequest;
    }


}