Unreferenced devolution Inquiry via API¶

This is a query via Content Provider that allows other applications to query information about unreferenced returns, making it possible to perform filters and obtain different data from unreferenced returns, 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/refunds

URI (Uniform Resource Identifier) for obtaining Unreferenced devolution 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	Mandatory	Description
`status`	`ReversalStatus`	No	Filters unreferenced devolution whose status is in the list passed (accepts more than one value).
`startDate`	`Date`	No	Filters unreferenced devolution whose date is greater than or equal to the passed value.
`finishDate`	`Date`	No	Filters unreferenced devolution whose date is less than or equal to the passed value.
`lastUpdateQuery`	`Boolean`	No	Indicates whether the query will be based on the date and time of the unreferenced devolution (if this field is not filled in or receive 'false') or on the date and time of the last update of the unreferenced return (if this field receives 'true')
`startValue`	`BigDecimal`	No	Filters unreferenced devolution whose value is greater than or equal to the passed value.
`finishValue`	`BigDecimal`	No	Filters unreferenced devolution whose value is less than or equal to the passed value.
`refundId`	`String`	No	Filters unreferenced devolution whose identifier for the payment application is the value passed.
`lastDigits`	`String`	No	Filters unreferenced devolution whose last 4 digits of the PAN of the card used in the transaction are equal to the value passed.
`productShortName`	`String`	No	Product identifier, returns only unreferenced devolution made with a specific product.
`ticketNumber`	`String`	No	ticketNumber generated by the terminal for the return.
`batchPend`	`Boolean`	No	Filters unreferenced devolution that are still in the pending batch (new returns).
`lastBatch`	`Boolean`	No	Filters unreferenced devolution from the last closed batch.
`batchNumber`	`String`	No	Filters unreferenced devolution from a batch with a specific number (closed or open).
`acquirerResponseCode`	`String`	No	Filters unreferenced devolution bounces based on host response code.
`appTransactionId`	`String`	No	Filters unreferenced devolution that are not referenced with a specific Identifier, informed by the integrated app in `reversePaymentV2()`, in the `appTransactionId` field.

Return¶

The unreferenced devolution query returns the non-referenced returns that comply with the informed filters.

The informed filters are applied only to the fields of unreferenced returns.

The list of returned unreferenced bounces must be sorted in ascending order by the date field.

Name	Type	Description
`id`	`String`	Transaction identifier for the payment application.
`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.
`paymentType`	`PaymentType`	Payment type (Debit, Credit, Voucher, etc.).
`acquirerName`	`String`	Purchaser who authorized the payment.
`cardBrand`	`String`	Card brand.
`cardBin`	`String`	Card BIN.
`cardPanLast4Digits`	`String`	Last 4 digits of the card's PAN.
`captureType`	`CaptureType`	Card capture form.
`status`	`PaymentStatus`	Payment status.
`date`	`Date`	Payment date/time for the payments application.
`acquirerId`	`String`	Transaction identifier for the acquirer. This is the identifier that appears in the file that the acquirer provides (EDI). In this way, it is possible to reconcile the payment with the integrated transaction.
`acquirerResponseCode`	`String`	Acquirer response code.
`acquirerResponseDate`	`String`	Date/time returned by acquirer.
`acquirerAuthorizationNumber`	`String`	Authorization number provided by the acquirer (it appears on the Card Holder customer receipt).
`clientVia`	`String`	Receipt content - customer copy.
`merchantVia`	`String`	Receipt content - merchant copy.
`accountTypeId`	`String`	Only present when an account type exists in the context of the executed transaction.
`productShortName`	`String`	Product identifier, returns only transactions for a product.
`batchNumber`	`String`	Lot number.
`nsuTerminal`	`String`	NSU generated by the terminal for the transaction.
`cardholderName`	`String`	Customer name on card.
`lastTrx`	`Boolean`	Indicates 'true' if it is the last approved transaction, and 'false' otherwise.
`terminalId`	`String`	Terminal identification.
`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.

Return example¶

The "refund" structure is the same used in the last approved and confirmed transaction query;

When 2 returns meet the informed criteria:

{
  [
     {
        "refund": { 
            ...
        }       
     },
     {
        "refund": { 
            ...
        }   
     }   
  ]
}

Info

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

RefundProviderRequest
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
        RefundProviderRequest request = createRequest(applicationInfo);

        try {
            //requesting refund list
            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);

        //filtering by refundId
        refundRequest.setRefundId("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");
            refundRequest.setStartDate(dateStart);
            refundRequest.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
        refundRequest.setStartValue(new BigDecimal("0.00"));
        refundRequest.setFinishValue(new BigDecimal("1000.00"));

        //filtering by the last 4 digits of the card
        refundRequest.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 refundRequest;
    }


}