[DEPRECATED] Integration with Chargeback V1¶
One of the ways to integrate with the Phoebus payments app is via IPC. A library is provided for this, payments-api-x.x.x.x.aar , containing all the code needed to be used for such calls.
Using this API, it is possible to carry out the entire payment flow, that is, confirmation (or undoing) and reversal. Payment can be made with a pre-defined amount or with an open amount, to be entered by the terminal operator. 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.
Warning
The PaymentClient.Bind(_callback) method must be called, before calling any Payment Integration method. The bind is asynchronous, that is, the next line after the bind() will be executed before receiving its response, so make sure that before calling the integration methods, the bind is connected.
Methods¶
| Signature | Description |
|---|---|
void reversePayment(ReversePaymentRequest paymentRequest, PaymentCallback paymentCallback) |
Performs the payment reversal process. (DEPRECATED: Use reversePaymentV2) |
void cancelReversePayment(String paymentId, PaymentCallback paymentCallback) |
Undo a chargeback request. |
reversePayment() (DEPRECATED: Use reversePaymentV2)¶
This method must be called when you want to make a payment reversal request. During its execution, the chargeback data will be validated, additional information will be requested from the operator (e.g. card) and authorization will be made with the acquirer.
Note that the reversal transaction does not have confirmation, but only undoing. Thus, confirmation will naturally occur when the undo is not sent, depending on the behavior of each acquirer.
Also depending on the behavior of each acquirer, it is possible that there is no undo for the reversal transaction. In this case, approved chargebacks will return the value false in the "ReversePayment.cancelable" field. Furthermore, if the cancelReversePayment() method is called, a specific error will be returned informing that it is not possible to execute such an operation (see Response Codes).
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
request |
ReversePaymentRequest |
Yes | Data transfer object that will contain the payment reversal request information. Note that not all parameters are required. |
callback |
ReversePaymentCallback |
Yes | Interface that will be executed for success or error notifications of the chargeback process. |
Parameter details
request (ReversePaymentRequest)
| Name | Type | Mandatory | Description |
|---|---|---|---|
value |
BigDecimal |
No | Transaction amount to be reversed. If it is not filled in (null), the interface will ask the operator for the value. This information is used to validate the integrity of the transaction being reversed. |
paymentId |
String |
Yes | Identifier of the transaction to be reversed. The Identifier referred to is the one used in the payment application. |
appTransactionId |
String |
Yes | Integrated transaction identifier. The Identifier referred to is that of the application that originated the chargeback request. It must be the same amount sent in the payment transaction. |
ApplicationInfo.credentials |
Credentials |
Yes | Credentials of the application that is requesting the operation, as registered at PayStore. Basically, it's about the application ID and the access token. |
ApplicationInfo.softwareVersion |
String |
Yes | Version of the application that is requesting payment. |
showReceiptView (DEPRECATED) |
Boolean |
No | The Solution will always print the receipt. |
callback (ReversePaymentCallback)
| Name | Type | Mandatory | Description |
|---|---|---|---|
onSuccess |
Method for notification on success | ||
ReversePayment.paymentId |
String |
Yes | Chargeback transaction identifier for the payments application. This is the information to use for commit and undo. |
ReversePayment.acquirerId |
String |
Yes | Chargeback 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 reversal with the integrated transaction. |
ReversePayment.cancelable |
Boolean |
Yes | True, if this transaction can be undone; False otherwise. |
ReversePayment.acquirerResponseCode |
String |
Yes | Acquirer response code. |
ReversePayment.acquirerResponseDate |
String |
Yes | Date/time returned by the acquirer. |
ReversePayment.acquirerAuthorizationNumber |
String |
Yes | Authorization number provided by the acquirer (it appears on the Cardholder's customer receipt). |
ReversePayment.Receipt.clientVia |
String |
No | Voucher content - customer's copy. |
ReversePayment.Receipt.merchantVia |
String |
No | Content of the voucher - copy of the establishment. |
onError |
Method for notification in case of error. | ||
ErrorData.paymentsResponseCode |
String |
Yes | Response code for the error that occurred. See Response Codes |
ErrorData.acquirerResponseCode |
String |
No | Response code for the occurred error returned by the acquirer. Note that this error will only be returned if the transaction is not authorized by the acquirer. |
ErrorData.responseMessage |
String |
Yes | 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. |
cancelReversePayment()¶
This method must be called to undo a previously authorized chargeback transaction. This transaction must not have been rolled back yet and must have been authorized (not denied) previously.
As stated in the description of reversePayment(), it is possible that there is no undo for the chargeback transaction for a given acquirer. Thus, the cancelReversePayment() method may return a specific error stating that such an operation cannot be performed (see Response Codes).
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
paymentId |
String |
Yes | Identificador da transação que será desfeita. O Identificador referido é aquele utilizado pela aplicação de pagamentos. |
callback |
PaymentCallback |
Yes | Interface que será executada para notificações de sucesso ou erro. |
Parameter details
callback
| Name | Type | Mandatory | Description |
|---|---|---|---|
onSuccess |
Method for notification on success | ||
onError |
Method for notification in case of error. | ||
ErrorData.paymentsResponseCode |
String |
Yes | Response code for the error that occurred. See Response Codes |
ErrorData.acquirerResponseCode |
String |
No | Response code for the occurred error returned by the acquirer. Note that this error will only be returned if the transaction is not authorized by the acquirer. |
ErrorData.responseMessage |
String |
Yes | 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. |
Example of the Chargeback flow¶
import androidx.appcompat.app.AppCompatActivity;
import android.content.Intent;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import android.widget.Toast;
import java.math.BigDecimal;
import br.com.phoebus.android.payments.api.Credentials;
import br.com.phoebus.android.payments.api.ErrorData;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.ReversePayment;
import br.com.phoebus.android.payments.api.ReversePaymentRequest;
import br.com.phoebus.android.payments.api.exception.ClientException;
public class MainActivity extends AppCompatActivity implements View.OnClickListener, PaymentClient.PaymentCallback<ReversePayment> {
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();
}
@Override
public void onClick(View view) {
doExecute();
}
@Override
protected void onResume() {
super.onResume();
paymentClient.bind(this);
}
@Override
protected void onDestroy() {
try {
paymentClient.unbind(this);
} catch (Exception e) {
Log.e(TAG, e.getMessage());
}
super.onDestroy();
}
public void doExecute(){
ReversePaymentRequest request = new ReversePaymentRequest();
request.setValue(new BigDecimal(50));
request.setAppTransactionId("123456");
request.setPaymentId("999999");
request.setShowReceiptView(true);
Credentials credentials = new Credentials();
credentials.setApplicationId(TEST_APPLICATION_ID);
credentials.setSecretToken(TEST_SECRET_TOKEN);
request.setCredentials(credentials);
try {
paymentClient.reversePayment(request, this);
} catch (ClientException e) {
Log.e(TAG, "Error reversePayment", e);
}
}
@Override
public void onSuccess(ReversePayment reversePayment) {
Log.i(TAG, reversePayment.toString());
/*
If, in your business rule, you need to undo the transaction for some reason,
call cancelReversePayment() method
**/
//doCancelReversePayment(reversePayment);
}
@Override
public void onError(ErrorData errorData) {
Log.e(TAG, errorData.getResponseMessage());
Toast.makeText(this, errorData.getResponseMessage(), Toast.LENGTH_LONG).show();
}
private void doCancelReversePayment(ReversePayment reversePayment) {
try {
paymentClient.cancelReversePayment(reversePayment.getPaymentId(),
new PaymentClient.PaymentCallback<ReversePayment>() {
@Override
public void onError(ErrorData errorData) {
Log.e(TAG, errorData.getResponseMessage());
Toast.makeText(MainActivity.this, errorData.getResponseMessage(), Toast.LENGTH_LONG).show();
}
@Override
public void onSuccess(Object o) {
Log.i(TAG, "Undo Completed!");
}
});
} catch (ClientException e) {
Log.e(TAG, "Error cancelReversePayment", e);
}
}
}