Ir para o conteúdo

[DEPRECATED] Payment Integration 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. bind is asynchronous, i.e. the next line after bind() will be executed before receiving your response, so make sure that before calling the integration methods, the bind is **connected* *.

Methods


Signature Description
void startPayment(PaymentRequest paymentRequest, PaymentCallback paymentCallback) Performs the payment authorization process. (DEPRECATED: Using startPaymentV2)
void confirmPayment(String paymentId, PaymentCallback paymentCallback) Confirms a previously performed payment authorization.
void cancelPayment(String paymentId, PaymentCallback paymentCallback) Undoes a previously performed payment authorization.

startPayment() (DEPRECATED: Use 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

Name Type Mandatory Description
request PaymentRequest Yes Data transfer object that will contain the payment request information. Note that not all parameters are required.
callback PaymentCallback Yes Interface que será executada para notificações de sucesso ou erro do processo de pagamento.

Parameter Details

request (PaymentRequest)

Name Type Mandatory Description
value BigDecimal No Requested payment amount. If it is not filled in (null), the interface will ask the operator for the value.
paymentTypes List<PaymentType> No Payment types (Debit, Credit, Voucher, etc.) allowed for this payment. If it is empty, that is, null, it means that all types are allowed. If it contains only one, this type will be used (if possible) and the operator will not be asked anything.
installments Integer No Number of installments. Used only for payment types that support installments and in this case it is mandatory. Value must be between 2 and 99.
appTransactionId String Yes Integrated transaction identifier. The Identifier referred to is the one used in the application that originated the payment request. It must not be repeated.
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 after confirmation is performed.

callback (PaymentCallback)

Name Type Mandatory Description
onSuccess Method for notification on success
Payment.value BigDecimal Yes 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.
Payment.paymentType PaymentType Yes Type of payment (Debit, Credit, Voucher, etc.).
Payment.installments Integer No Number of payment installments.
Payment.acquirer String Yes Purchaser who authorized the payment.
Payment.paymentId String Yes Transaction identifier for the payment application. This is the information to use for commit and undo.
Payment.brand String Yes Card banner.
Payment.bin String Yes card BIN.
Payment.panLast4Digits String Yes Last 4 digits of the card's PAN.
Payment.captureType CaptureType Yes Card capture method.
Payment.paymentStatus PaymentStatus Yes Payment status. In the case of successfully returned requests, this information will always be PENDING, requiring confirmation or undoing for its definitive conclusion.
Payment.paymentDate Date Yes Payment date/time for the payment application.
Payment.acquirerId String Yes 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.
Payment.acquirerResponseCode String Yes Acquirer response code.
Payment.acquirerResponseDate String Yes Date/time returned by the acquirer.
Payment.acquirerAuthorizationNumber String Yes Authorization number provided by the acquirer (it appears on the Cardholder's receipt).
Payment.Receipt.clientVia String No Voucher content - customer's copy.
Payment.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.

confirmPayment()

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 the execution of this confirmation, the transaction can only be canceled through a reversal operation. The chargeback is the operation performed by the CANCEL menu of the terminal.

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

Name Type Mandatory Description
paymentId String Yes Identifier of the transaction to be committed. The Identifier referred to is the one used in the payment application.
callback PaymentCallback Yes Interface that will be executed for success or error notifications.

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.

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 should 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

Name Type Mandatory Description
paymentId String Yes Identifier of the transaction to be rolled back. The Identifier referred to is the one used in the payment application.
callback PaymentCallback Yes Interface that will be executed for success or error notifications.

Detalhe dos parâmetros

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.

Payment flow example


package com.example.appmanoel;

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.Payment;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.PaymentRequest;
import br.com.phoebus.android.payments.api.exception.ClientException;

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

    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(){
        PaymentRequest request = new PaymentRequest();
        request.setValue(new BigDecimal(50));
        request.setAppTransactionId("123456");

        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.startPayment(request, this);
        } catch (ClientException e) {
            Log.e(TAG, "Error starting payment", e);
        }
    }


    @Override
    public void onSuccess(Payment payment) {
        Log.i(TAG, payment.toString());

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

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

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

                        @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(Payment payment) {
        try {
            paymentClient.cancelPayment(payment.getPaymentId(),
                    new PaymentClient.PaymentCallback<Payment>() {

                        @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 data) {
                            Log.i(TAG, "Undo Completed!");
                        }


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

    }


}