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