Consult Payment by API¶
One of the ways to integrate with the Phoebus payment application is via IPC. A library is provided for this, payments-api-x.x.x.x.aar , containing all the code needed to make the integration calls.
Using this API, it is possible to carry out the entire payment flow, that is, confirmation (or undoing). In addition, you can inform a list of payment types (debit, cash credit, credit in installments, etc.) allowed.
Although this integration takes place through an API, the payment application can display information on the terminal interface, such as messages (e.g., "Insert or swipe the card"), or even request information from the operator (e.g., CVV). Therefore, while performing any operation, the application that requested the operation must not interact with the device's interface until the operation is completed.
The following is a detailed specification of available operations.
For payment API integration, the PaymentClient interface is provided.
Integration with Payment Application via Content Provider¶
Integration via Content Provider allows other applications to consult information about payments made, making it possible to perform filters and obtain various payment data, including their status.
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
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'
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. |
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. |
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¶
| 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). |
receiptClient |
String |
Voucher content - customer's copy. |
receiptMerchant |
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. |
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).findAll(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;
}
}