Ir para o conteúdo

[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);
        }


    }


}