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:
PaymentProviderRequestPaymentProviderApiPaymentContract
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;
}
}