[DEPRECATED] Integração com Pagamentos V1¶
Uma das formas de se integrar com a aplicação de pagamentos da Phoebus é via IPC. Para isto, é fornecida uma biblioteca, a payments-api-x.x.x.x.aar, contendo todo o código necessário a ser usada para tais chamadas.
Usando esta API, é possível realizar todo o fluxo de pagamento, ou seja, a confirmação (ou o desfazimento) e o estorno. O pagamento pode ser realizado com um valor pré-definido ou com um valor em aberto, a ser digitado pelo operador do terminal. Além disso, pode-se informar uma lista de tipos de pagamentos (débito, crédito à vista, crédito parcelado, etc.) permitidos.
Ainda que esta integração se dê através de uma API, a aplicação de pagamentos pode exibir informações na interface do terminal, tais como mensagens (e.g., "Insira ou passe o cartão"), ou mesmo solicitar informações do operador (e.g., CVV). Assim sendo, durante a realização de qualquer operação, a aplicação que solicitou a operação não deve interagir com a interface do dispositivo até que a operação seja concluída.
A seguir, temos a especificação detalhada das operações disponíveis.
Para integração com a API de pagamentos, é fornecida a interface PaymentClient.
Warning
O método PaymentClient.Bind(_callback) deve ser chamado, obrigatoriamente, antes de chamar qualquer método da Integração de Pagamento. O bind é assíncrono, ou seja, a próxima linha após o bind() será executada antes de receber a sua resposta, por isso, garanta que, antes de chamar os métodos de integração, o bind esteja conectado.
Métodos¶
| Assinatura | Descrição |
|---|---|
void startPayment(PaymentRequest paymentRequest, PaymentCallback paymentCallback) |
Realiza o processo de autorização de pagamento. (DEPRECATED: Utilizar startPaymentV2) |
void confirmPayment(String paymentId, PaymentCallback paymentCallback) |
Confirma uma autorização de pagamento realizada anteriormente. |
void cancelPayment(String paymentId, PaymentCallback paymentCallback) |
Desfaz uma autorização de pagamento realizada anteriormente. |
startPayment() (DEPRECATED: Utilizar startPaymentV2)¶
Este método deve ser chamado quando se deseja fazer uma solicitação de autorização de pagamento. Durante sua execução, os dados do pagamento serão validados, informações adicionais serão solicitadas ao operador (e.g. senha e CVV), e a autorização junto à adquirente será feita.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
request |
PaymentRequest |
Sim | Objeto de transferência de dados que conterá as informações da requisição do pagamento. Note que nem todos os parâmetros são obrigatórios. |
callback |
PaymentCallback |
Sim | Interface que será executada para notificações de sucesso ou erro do processo de pagamento. |
Detalhe dos Parâmetros
request (PaymentRequest)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
value |
BigDecimal |
Não | Valor do pagamento solicitado. Caso não seja preenchido (null), a interface solicitará o valor ao operador. |
paymentTypes |
List<PaymentType> |
Não | Tipos de pagamentos (Débito, Crédito, Voucher, etc.) permitidos para este pagamento. Caso seja vazio, ou seja, null, significa que todos os tipos são permitidos. Caso contenha apenas um, este tipo será o utilizado (se possível) e não será perguntado nada ao operador. |
installments |
Integer |
Não | Quantidade de parcelas. Usado apenas para tipos de pagamentos que suportem parcelamento e neste caso é obrigatório. Valor deve ser entre 2 e 99. |
appTransactionId |
String |
Sim | Identificador da transação integrada. O Identificador referido é aquele utilizado na aplicação que originou a solicitação de pagamento. Não deve se repetir. |
ApplicationInfo.credentials |
Credentials |
Sim | Credenciais da aplicação que está solicitando a operação, conforme cadastro na PayStore. Basicamente, trata-se da identificação da aplicação e o token de acesso. |
ApplicationInfo.softwareVersion |
String |
Sim | Versão da aplicação que está solicitando o pagamento. |
showReceiptView (DEPRECATED) |
Boolean |
Não | A Solução sempre irá imprimir o comprovante depois que a confirmação for executada. |
callback (PaymentCallback)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
onSuccess |
Método para notificação em caso de sucesso | ||
Payment.value |
BigDecimal |
Sim | Valor do pagamento. Este é o valor que foi aprovado pela adquirente. Deve ser validado sempre na resposta, ainda que tenha sido passado como parâmetro, pois há adquirentes que, para algumas situações, aprovam valores diferentes dos solicitados. |
Payment.paymentType |
PaymentType |
Sim | Tipo de pagamento (Débito, Crédito, Voucher, etc.). |
Payment.installments |
Integer |
Não | Quantidade de parcelas do pagamento. |
Payment.acquirer |
String |
Sim | Adquirente que autorizou o pagamento. |
Payment.paymentId |
String |
Sim | Identificador da transação para a aplicação de pagamentos. Esta é a informação a ser usada para a confirmação e desfazimento. |
Payment.brand |
String |
Sim | Bandeira do cartão. |
Payment.bin |
String |
Sim | BIN do cartão. |
Payment.panLast4Digits |
String |
Sim | Últimos 4 dígitos do PAN do cartão. |
Payment.captureType |
CaptureType |
Sim | Forma de captura do cartão. |
Payment.paymentStatus |
PaymentStatus |
Sim | Situação do pagamento. No caso de solicitações retornadas com sucesso, esta informação sempre será PENDING, requerendo uma confirmação ou desfazimento para a sua conclusão definitiva. |
Payment.paymentDate |
Date |
Sim | Data/hora do pagamento para a aplicação de pagamentos. |
Payment.acquirerId |
String |
Sim | Identificador da transação para a adquirente. Este é o identificador que consta no arquivo que a adquirente fornece (EDI). Desta forma, é possível realizar a conciliação do pagamento com a transação integrada. |
Payment.acquirerResponseCode |
String |
Sim | Código de resposta da adquirente. |
Payment.acquirerResponseDate |
String |
Sim | Data/hora retornada pela adquirente. |
Payment.acquirerAuthorizationNumber |
String |
Sim | Número da autorização fornecido pela adquirente (consta no comprovante do Portador do Cartão). |
Payment.Receipt.clientVia |
String |
Não | Conteúdo do comprovante - via do cliente. |
Payment.Receipt.merchantVia |
String |
Não | Conteúdo do comprovante - via do estabelecimento. |
onError |
Método para notificação em caso de erro. | ||
ErrorData.paymentsResponseCode |
String |
Sim | Código de resposta para o erro ocorrido. Vide Códigos de Resposta |
ErrorData.acquirerResponseCode |
String |
Não | Código de resposta para o erro ocorrido retornado pela adquirente. Note que este erro só será retornado se a transação não for autorizada pela adquirente. |
ErrorData.responseMessage |
String |
Sim | Mensagem descritiva da causa da não autorização. Caso a transação tenha sido negada pela adquirente, conterá a mensagem retornada pela adquirente. |
confirmPayment()¶
Este método deve ser chamado para confirmar uma transação que o terminal conseguiu processar completamente a perna de autorização enviada pelo Autorizador.
Este método não deve ser chamado para uma transação já confirmada, ou seja, em que já se executou o método confirmPayment() anteriormente.
Este método não deve ser chamado para uma transação já desfeita, ou seja, em que já se executou o método cancelPayment() anteriormente.
Este método não deve ser chamado para uma transação que foi negada pelo Autorizador, ou seja, a transação precisa ter sido autorizada pelo Autorizador.
Após a execução desta confirmação, a transação só poderá ser cancelada através de uma operação de estorno. O estorno é a operação executada pelo menu CANCELAMENTO do terminal.
Caso o App consumidor desta API tenha finalizado o seu processo de negócio com êxito, porém não tenha chamado o método confirmPayment(), a transação permanecerá com o seguinte status: Situação PayStore = "Pendente". Resolução no Adquirente = "Pendente".
Como resultado, poderemos ter uma inconsistência transacional, visto que, na virada do dia, algumas redes adquirentes confirmam automaticamente as transações que não receberam a perna de confirmação. Outras redes adquirentes trabalham apenas com duas pernas, sem a necessidade de perna de confirmação. Neste caso, se houver algum problema na conclusão da transação no lado do terminal, é imperativo que a solução de captura execute o método cancelPayment(), a fim de desfazer a transação no adquirente e evitar cobrança para o cliente Portador do Cartão.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
paymentId |
String |
Sim | Identificador da transação que será confirmada. O Identificador referido é aquele utilizado na aplicação de pagamentos. |
callback |
PaymentCallback |
Sim | Interface que será executada para notificações de sucesso ou erro. |
Detalhe dos parâmetros
callback
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
onSuccess |
Método para notificação em caso de sucesso | ||
onError |
Método para notificação em caso de erro. | ||
ErrorData.paymentsResponseCode |
String |
Sim | Código de resposta para o erro ocorrido. Vide Códigos de Resposta |
ErrorData.acquirerResponseCode |
String |
Não | Código de resposta para o erro ocorrido retornado pela adquirente. Note que este erro só será retornado se a transação não for autorizada pela adquirente. |
ErrorData.responseMessage |
String |
Sim | Mensagem descritiva da causa da não autorização. Caso a transação tenha sido negada pela adquirente, conterá a mensagem retornada pela adquirente. |
cancelPayment()¶
Este método deve ser sempre chamado para desfazer uma transação que o terminal não conseguiu processar completamente a perna de autorização enviada pelo Autorizador.
Este método não deve ser chamado para uma transação já confirmada, ou seja, em que já se executou o método confirmPayment() anteriormente.
Este método não deve ser chamado para desfazer uma transação já desfeita, ou seja, em que já se executou o método cancelPayment() anteriormente.
Este método não deve ser chamado para uma transação que foi negada pelo Autorizador.
Este método não é um estorno. O estorno é a operação executada pelo menu CANCELAMENTO do terminal. O estorno é executado em transações que foram concluídas com êxito, ou seja, foram confirmadas.
Após a execução do desfazimento, cancelPayment(), a transação não poderá ser mais confirmada pela aplicação do terminal, ou seja, não se pode mais executar o método confirmPayment().
Caso o App consumidor desta API não tenha finalizado o seu processo de negócio com êxito, é imprescindível a chamada do método cancelPayment(). A consequência de não cancelar uma transação que não teve seu processo de negócio concluído é semelhante à consequência de não confirmar. Porém, nesse caso, com um agravante, pois provavelmente o cliente não levará o produto/serviço associado à transação financeira, ou uma nova tentativa de venda poderá ser feita, resultando em uma cobrança em duplicidade para o cliente Portador do Cartão.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
paymentId |
String |
Sim | Identificador da transação que será desfeita. O Identificador referido é aquele utilizado na aplicação de pagamentos. |
callback |
PaymentCallback |
Sim | Interface que será executada para notificações de sucesso ou erro. |
Detalhe dos parâmetros
callback
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
onSuccess |
Método para notificação em caso de sucesso | ||
onError |
Método para notificação em caso de erro. | ||
ErrorData.paymentsResponseCode |
String |
Sim | Código de resposta para o erro ocorrido. Vide Códigos de Resposta |
ErrorData.acquirerResponseCode |
String |
Não | Código de resposta para o erro ocorrido retornado pela adquirente. Note que este erro só será retornado se a transação não for autorizada pela adquirente. |
ErrorData.responseMessage |
String |
Sim | Mensagem descritiva da causa da não autorização. Caso a transação tenha sido negada pela adquirente, conterá a mensagem retornada pela adquirente. |
Exemplo do fluxo de Pagamento¶
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);
/*
Se, na sua regra de negócio, for preciso desfazer a transação por algum motivo,
chame o método doCancelPayment()
**/
}
@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, "Confirmação do pagamento realizado com sucesso!");
}
});
} 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 o) {
Log.i(TAG, "Desfazimento Realizado!");
}
});
} catch (ClientException e) {
Log.e(TAG, "Error cancelPayment", e);
}
}
}