Ir para o conteúdo

Consult Payment V2 by API


This is a query via Content Provider that allows other applications to consult information about payments made, making it possible to carry out filters and obtain various payment data, including their status.

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

URI (Uniform Resource Identifier) for obtaining payment information.

To request the payment 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 PaymentStatus No Filters payments whose status is in the past list (accepts more than one value).
startDate Date No Filters for payments whose date is greater than or equal to the past amount.
finishDate Date No Filters for payments whose date is less than or equal to the past amount.
lastUpdateQuery Boolean No Indicates whether the query will be based on the transaction date and time (if this field is not filled in or receives 'false') or the date and time of its last update (if this field receives 'true').
startValue BigDecimal No Filters for payments whose amount is greater than or equal to the amount passed.
finishValue BigDecimal No Filters for payments whose amount is less than or equal to the amount passed.
paymentId String No Filters payments whose transaction identifier for the payment application is the value passed.
lastDigits String No Filters for payments whose last 4 digits of the PAN of the card used in the transaction are equal to the amount passed.
productShortName String No Product identifier, returns only transactions for a product.
ticketNumber String No ticketNumber generated by the terminal for the transaction.
batchPend Boolean No Filters for transactions that are still in the pending batch (new transactions).
lastBatch Boolean No Filters transactions from the last closed batch.
batchNumber String No Filters transactions in a batch.
acquirerResponseCode String No Filters transactions based on host response code.
lastTrx Boolean No Filters for the last approved transaction.
trxType String No Filters transactions by type ("1" - Sale, "2" - Unreferenced Return).
note String No Additional text that is entered as Note. (can be invoice number)
dni String No Document number.
qrId String No QrCode identifier generated by the capture terminal.
operationMethod Integer No Filters transactions according to the form of operation. Allow the following values: 0 - Only with physical card (read or typed); 1 - Only with QRCode.
appTransactionId String No Integrated transaction identifier for the software. The Identifier referred to is the one used in the application that originated the payment request.

Return

The payment query returns the payments that comply with the filters informed, and the reversals associated with them (including denied reversals).

The informed filters are applied only to payment 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
id String Transaction identifier for the payment application. This is the information to use for commit and undo.
value BigDecimal Payment amount. 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 acquirers that, for some situations, approve values ​​different from those requested.
paymentType PaymentType Type of payment (Debit, Credit, Voucher, etc.).
installments Integer Number of payment installments.
acquirerName String Purchaser who authorized the payment.
cardBrand String Card banner.
cardBin String card BIN.
cardPanLast4Digits String Last 4 digits of the card's PAN.
captureType CaptureType Card capture method.
status PaymentStatus Payment status.
date Date Payment date/time for the payment 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 the acquirer.
acquirerAuthorizationNumber String Authorization number provided by the acquirer (it appears on the Cardholder's customer receipt).
clientVia String Voucher content - customer's copy.
merchantVia String Content of the voucher - copy of the establishment.
additionalValueType AdditionalValueType Present only when there is an additional value in the context of the executed transaction.
additionalValue BigDecimal Present only when there is an additional value in the context of the executed transaction.
accountTypeId String Only present when an account type exists in the context of the executed transaction.
planId String Present only when a plan 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 ID.
originalValue BigDecimal Original sale price. Present in payments with QRCode, whose benefit was applied to the sale value.
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.
ticketNumber String ticketNumber generated by the terminal for the transaction.
acquirerAdditionalMessage String Additional message sent by the acquirer in the transaction response.
note String Additional text that is entered as Note. (can be invoice number)
dni String Document number.
qrId String QrCode identifier generated by the capture terminal.
aid String AID to identify the application to process the transaction. It's returned on EMV transactions.
cardAppName String APN, or card application name. It's returned on EMV 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 String Common transaction identifier between terminal, PhAST and PayStore. This identifier in UUID format is unique for each transaction
Return example when two payments meet the informed criteria

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

[
 {
    "payment": {
        ...
    },
    "reversals": [
      {
         ...
      },
      {
         ...
      },
      {
         ...
      }
    ]
 },
 {
    "payment": {
        ...
    },
    "reversals": [
      {
         ...
      },
      {
         ...
      },
      {
         ...
      }
    ]
 }
]

Info

You can customize what information will be present in the response. For this, an array of Strings with the desired columns must be passed to the query() method of the Content Resolver. If you use the provider access API, you can use the PaymentProviderRequest's setColumns() method.

Info

For ease of use, provider access classes are available:

  • PaymentProviderRequest
  • PaymentProviderApi
  • PaymentContract
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
        PaymentProviderRequest request = createRequest(applicationInfo);

        //selecting returned properties
        String[] columns = new String[]{
                PaymentContract.column.ID,
                PaymentContract.column.VALUE,
                PaymentContract.column.PAYMENT_STATUS,
                PaymentContract.column.PAYMENT_DATE,
                PaymentContract.column.CARD_BRAND,
        };

        try {
            //requesting payment list
            request.setColumns(columns);
            List<Payment> paymentsList = PaymentProviderApi.create(this).findAllTransactions(request);
            //********* Another way to query ******************************************
            // Cursor cursor = getApplicationContext().getContentResolver().query(request.getUriBuilder().build(), columns, null, null, null);
            // List<Payment> paymentsList = Payment.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 PaymentProviderRequest createRequest(ApplicationInfo appInfo) {


        PaymentProviderRequest paymentRequest = new PaymentProviderRequest();
        paymentRequest.setApplicationInfo(appInfo);


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

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

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

        return paymentRequest;
    }


}