Integration with V2 Payments¶

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 Phoebus 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 integration with the payments API, the PaymentClient interface present in the library is provided.

Payment flow¶

The payment is only finalized when there is a confirmation or a cancellation (undo). In case of confirmation, the receipt will be available for printing or sending by SMS/email, depending on the terminal's functionalities.

As of version 3.1.4.3

When a transaction is made and the app requests its confirmation (confirmPayment()) or undoing (cancelPayment()), the request response will be sent to the app as soon as the transaction is resolved locally by the terminal, eliminating the need for the app wait for the resolution with the authorizer to continue the flow.

After that, the terminal will try to resolve the transaction with the authorizer. This can occur immediately when finalizing the transaction, or later, in the resolution of pending issues.

Methods¶

startPaymentV2()¶

This method must be called when you want to make a payment authorization request. During its execution, payment data will be validated, additional information will be requested from the operator (e.g. password and CVV), and authorization will be made with the acquirer.

Parameters

Parameter Details

request (PaymentRequestV2)

callback (PaymentCallback)

This method must be called to confirm a transaction that the terminal was able to fully process the authorization leg sent by the Authorizer.

This method must not be called for a transaction that has already been confirmed, that is, in which the confirmPayment() method has already been executed.

This method should not be called for a transaction that has already been undone, that is, in which the cancelPayment() method has been executed previously.

This method must not be called for a transaction that was denied by the Authorizer, that is, the transaction must have been authorized by the Authorizer.

After executing this confirmation, the transaction can only be canceled through a reversal operation (the reversal is the operation performed by the terminal's CANCEL menu).

If the consumer App of this API has successfully completed its business process, but has not called the confirmPayment() method, the transaction will remain with the following status: PayStore Status = "Pending". Resolution on Acquirer = "Pending".

As a result, we may experience transactional inconsistency, as at the turn of the day some acquiring networks automatically confirm transactions that have not received the confirmation leg. Other acquirer networks only work with two legs, without the need for a confirmation leg. In this case, if there is any problem completing the transaction on the terminal side, it is imperative that the capture solution executes the cancelPayment() method, in order to undo the transaction on the acquirer and avoid charging the Cardholder customer. Card.

Parameters

Parameter details

callback

cancelPayment()¶

This method must always be called to undo a transaction that the terminal was unable to fully process the authorization leg sent by the Authorizer.

This method must not be called for a transaction that has already been confirmed, that is, in which the confirmPayment() method has already been executed.

This method must not be called to undo a transaction that has already been undone, that is, in which the cancelPayment() method has already been executed

This method should not be called for a transaction that was denied by the Authorizer.

This method is not a chargeback. The chargeback is the operation performed by the CANCEL menu of the terminal. The reversal is performed on transactions that have completed successfully, that is, have been committed.

After executing the undo, cancelPayment(), the transaction can no longer be confirmed by the terminal application, that is, the confirmPayment() method can no longer be executed.

If the consumer App of this API has not successfully completed its business process, it is essential to call the cancelPayment() method. The consequence of not canceling a transaction that has not had its business process completed is similar to the consequence of not confirming. However, in this case, with an aggravating factor, as the customer will probably not take the product/service associated with the financial transaction, or a new attempt to sell may be made, resulting in a duplicate charge for the Cardholder customer.

Parameters

Parameter details

callback

Additional field api_pending¶

In addition to the payment resolution methods (confirmPayment and cancelPayment), there is the possibility of configuring an additional field in the Paystore Portal to perform this resolution automatically, at a certain time. For this, an additional field must be created in the Paystore Portal with the type JSON and the key api_pending.

Field value

{
    "confirmationTime": "10",
    "transactionConfirmation": "CONFIRM"
}

Example of the payment 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.ApplicationInfo;
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.PaymentRequestV2;
import br.com.phoebus.android.payments.api.PaymentV2;
import br.com.phoebus.android.payments.api.exception.ClientException;

public class MainActivity extends AppCompatActivity implements View.OnClickListener, PaymentClient.PaymentCallback<PaymentV2> {

    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(){
        PaymentRequestV2 request = new PaymentRequestV2();
        BigDecimal value = BigDecimal.valueOf(5000).movePointLeft(2);
        request.setValue(value);
        request.setAppTransactionId("2d2f7dc7-88e5-467e-86a3-f173fb3c7792");

        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");

        request.setAppInfo(applicationInfo);

        try {
            paymentClient.startPaymentV2(request, this);
        } catch (ClientException e) {
            Log.e(TAG, "Error starting payment", e);
        }
    }


    @Override
    public void onSuccess(PaymentV2 paymentV2) {
        Log.i(TAG, paymentV2.toString());

        doConfirmPayment(paymentV2);
        /*
            If, in your business rule, you need to undo the transaction for some reason,
           call the method doCancelPayment(paymentV2)
        **/
    }

    @Override
    public void onError(ErrorData errorData) {
        Log.e(TAG, errorData.getResponseMessage());
        Toast.makeText(this, errorData.getResponseMessage(), Toast.LENGTH_LONG).show();
    }

    private void doConfirmPayment(PaymentV2 paymentV2) {
        try {
            paymentClient.confirmPayment(paymentV2.getPaymentId(),
                    new PaymentClient.PaymentCallback<PaymentV2>() {

                        @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, "Payment successfully completed confirmation!");
                        }


                    });
        } catch (ClientException e) {
            Log.e(TAG, "Error confirmPayment", e);
        }

    }

    private void doCancelPayment(PaymentV2 paymentV2) {
        try {
            paymentClient.cancelPayment(paymentV2.getPaymentId(),
                    new PaymentClient.PaymentCallback<PaymentV2>() {

                        @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 cancelPayment", e);
        }

    }


}