Documentação para Integração SDK A910/920

PayStore Android

Documentação da Integração Android da PayStore

Uma das formas de se integrar com a aplicação de pagamentos da Cielo é via IPC. Para isto, é fornecida uma biblioteca, a payments-api-x.x.x.x.aar, contendo todo o código necessário a ser usado 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 da Cielo 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 presente na biblioteca.

Material for MkDocs

Arquitetura

A Plataforma Android da PayStore é composta por várias aplicações Android com o propósito de prover uma Arquitetura modular que forneça as seguintes capacidades:

● Fácil adição de novos Adquirentes sem comprometer as funcionalidades e certificação dos restantes.

● Fácil customização da identidade visual e funcionalidades básicas de acordo com as necessidades de cada Cliente.

● Controle sobre o uso das funcionalidades de sistema para garantir uma maior segurança dos seus usuários.

● Plataforma de desenvolvimento de aplicações integradas com o sistema de pagamentos.

A figura abaixo ilustra de forma macro a arquitetura da plataforma PayStore em cima dos terminais SmartPOS com sistema operacional Android:

assets/images/Arquitetura

Apks PayStore

A seguir, temos uma visão geral mostrando os principais tipos de aplicações participantes da plataforma bem como a forma como elas interagem entre si. Em diagramas específicos de cada aplicação, poderá ser visto o que exatamente cada aplicação disponibiliza é responsável por fazer.

Payments App (Payments.apk)

Esta aplicação executa como serviço no Android e é a responsável por realizar todas as operações referentes a pagamentos (TEF), seja o pagamento em si, estornos (cancelamentos) ou mesmo consultas a pagamentos já realizados para, por exemplo, a geração de relatórios.

A seguir, temos uma lista com as principais funcionalidades da aplicação:

● Prover interface (API) para outras aplicações executarem operações de pagamento via IPC, Intent e ContentProvider;

● Prover interface gráfica com o usuário para a realização das operações;

● Prover acesso à “calculadora” para a realização de pagamentos;

● Disponibilização de relatórios;

● Interface para seleção de pagamento para realização de estorno;

● Visualização de transações pendentes com possibilidade de resolução manual (confirmação ou desfazimento);

● Re exibição de comprovantes do último pagamento ou de um pagamento selecionado;

● Visualização de informações do Pinpad;

● Visualização de bandeiras disponíveis para pagamento;

● Realização do processo de credenciamento, quando a aplicação é instalada pela primeira vez;

● Acessar o PayStore Server para obter configurações do terminal;

● Enviar ao PayStore Server as informações referentes aos pagamentos efetuados;

● Enviar ao PayStore Server as informações referentes aos pagamentos pendentes;

● Controlar os agendamentos para:

● Envio de informações dos pagamentos para o PayStore Server;

● Execução de processo de resolução de pendência;

● Execução de processo de expurgo de dados.

Módulos de Payments

O módulo payments-app é responsável pela geração da aplicação Payments APP, referenciando dependências e fazendo a montagem dos componentes. Os demais são libs utilizadas pela aplicação ou módulos que agrupam funcionalidades que podem ser usadas em outras aplicações.

payments-api: Lib disponibilizada para terceiros se integrarem com a plataforma para a realização de operações, tais como pagamento (débito/crédito/voucher), estorno, desfazimento, busca de informações de pagamentos realizados, etc.

Acquirer Specific App (.apk)

Esta aplicação executa como serviço no Android e é a responsável por realizar as integrações junto a uma adquirente específica. Assim, para cada adquirente habilitada para um terminal, deverá haver uma aplicação deste tipo executando.

A seguir, temos uma lista com as principais funcionalidades da aplicação:

● Prover interface via IPC para aplicativo de pagamento (Payments App) para as transações com a adquirente;

● Armazenar informações referentes aos pagamentos;

● Prover interface via ContentProvider para acesso às informações dos pagamentos.

Módulos de Acquirer

Platform App (platform.apk)

Esta é a aplicação principal da plataforma, uma vez que é a responsável por gerenciar o dispositivo (telefone) e exibir as principais telas de interação com o usuário (operador).

Este aplicativo só estará presente em terminais que sejam de propriedade da rede de captura, ou seja, terminais utilizados exclusivamente para serem meios de pagamento.

A seguir, temos uma lista com as principais funcionalidades da aplicação:

● Ser launcher do dispositivo, exibindo tela com aplicações instaladas;

● Gerenciamento de economia de energia do terminal, ativando e desativando dispositivos, como WiFi e Bluetooth quando o terminal estiver em modo ocioso;

● Implementação de barra de tarefas própria;

● Tela para visualização de notificações do terminal;

● Gerenciamento de meio de comunicação (automático ou manual), ativando/desativando WiFi e comunicação por operadora (GPRS, 3G, 4G, etc.);

● Manutenção de operadores do terminal;

● Interface para visualização de informações gerais do terminal;

Módulos do Plataform

Paystore Client App (paystore-client.apk)

Esta é a aplicação responsável pelo gerenciamento das instalações e atualizações de todas as aplicações da plataforma e de terceiros.

Este aplicativo só estará presente em terminais que sejam de propriedade da rede de captura, ou seja, terminais utilizados exclusivamente para serem meios de pagamento.

A seguir, temos uma lista com as principais funcionalidades da aplicação:

● Listar aplicativos disponíveis na PayStore para instalação;

● Listar aplicativos instalados no terminal;

● Gerenciar atualizações das aplicações, conforme informações da PayStore.

Módulos do PayStore Client

Esta aplicação possui um único módulo, ou seja, o paystore-client-app que contém todo o código dessa aplicação.

Acquirer Receipt Provider App (.apk)

Esta é a aplicação responsável pelo gerenciamento das impressões dos comprovantes de pagamento. Assim, para cada adquirente habilitada para um terminal, deverá haver uma aplicação deste tipo executando.

Cada adquirente tem o seu layout de impressão, esse aplicativo recebe a solicitação de impressão de uma determinada adquirente e realiza a impressão do comprovante com layout específico daquela adquirente.

A seguir, temos uma lista com as principais funcionalidades da aplicação:

● Gerenciar o layout do comprovante de cada adquirente;

● Gerenciar a impressão da via do Cliente;

● Gerenciar a reimpressão do comprovante.

Terminais Homologados

Modelo	Sistema Operacional	Fabricante
A920/A910	PayDroid based on Android 5.1	PAX

Publicar Aplicativo

Para publicar um aplicativo, é necessário logar no Portal da PayStore como desenvolvedor. Para exemplificar usaremos o ambiente de desenvolvimento. Após realizar o login, acesse o menu Aplicativos -> Rascunhos.

Nova versão

Se for a primeira vez que o aplicativo é publicado, clique no botão Novo Aplicativo. Após isso, será exibida uma tela, conforme mostrado abaixo:

Forneça as informações sobre o aplicativo. Ao preencher as palavras chaves, pressione Enter ao final, e clique em Salvar rascunho. Se tudo estiver certo, clique em Publicar Aplicação.

Será exibida uma tela para selecionar qual Facilitador deverá aprovar sua aplicação. Observe que, a cada nova etapa do fluxo de publicação da aplicação, será necessária uma aprovação do Facilitador indicado. A cada mudança de etapa, o desenvolvedor será notificado por email

Para o Facilitador, o aplicativo estará no menu Aplicativos -> Candidatos. O Facilitador deve aprovar ou reprovar o aplicativo. Em caso de aprovação, o aplicativo segue para a etapa de Homologação.

Uma vez homologado, o aplicativo estará apto para ser publicado. Dessa forma, estará disponível para ser baixado pela rede de terminais do Facilitador. Para publicar a aplicação, selecione-a e clique no botão Publicar.

Após publicar a aplicação, será exibida uma tela com os filtros de publicação. São esses filtros que vão definir que terminais irão receber a sua aplicação. Veja imagem abaixo:

Parabéns, sua aplicação está publicada!

Atualizar Versão

Se você possui uma aplicação já publicada e deseja atualizar sua versão, siga as etapas abaixo:

1 - No projeto de sua aplicação, abra o arquivo build.gradle (Modulo App). Em defaultConfig, incremente o VersionCode e o versionName, dessa forma sua aplicação será aceita pelo Portal para substituir a versão já publicada.

2 - Gere o apk da nova versão. Acesse o Portal da PayStore como descrito em Plubicar Aplicativo

3 - Selecione a opção Nova versão do aplicativo, conforme imagem abaixo:

4 - Faça o upload do novo apk que se deseja publicar e clique em Publicar Aplicativo

Os próximos passos são semelhantes ao de publicar uma nova aplicação.

Parabéns, sua versão foi atualizada!

Temas

Customização de Temas

Através do Portal da PayStore, é possível customizar o tema da aplicação de Pagamento, contudo isso também é possível via programação.

Métodos

Assinatura	Descrição
void setTheme(String theme, PaymentCallback paymentCallback)	Define um tema para a aplicação de pagamentos.

setTheme() Este método deve ser chamado para definir um tema com padrões de cores para as telas de captura na aplicação de Pagamentos.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
theme	String	Sim	Nome do tema que será definido (case-sensitive).
callback	PaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro.

Detalhe dos parâmetros:

theme

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.responseMessage	String	Sim	Mensagem descritiva da causa do erro.

Exemplo

public class MyActivity extends Activity implements PaymentClient.PaymentCallback {

    private PaymentClient paymentClient;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment);
        paymentClient = new PaymentClientImpl();
    }

    @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() {
        ApplicationInfo appInfo = new ApplicationInfo();
        appInfo.setCredentials(new Credentials("demo-app", "TOKEN-KEY-DEMO"));
        appInfo.setSoftwareVersion("1.0.0.0");
        try {
            paymentClient.setTheme("GreyTheme", this);
        } catch (ClientException e) {
            Log.e(TAG, "Error setting theme", e);
        }
    }

    @Override
    public void onError(Object data) {
        Log.e(TAG, "Error: " + ((ErrorData) data).getResponseMessage());
    }

    @Override
    public void onSuccess(Object data) {
        Log.i(TAG, "Success!");
    }
}

Pré-requisitos

IDE

Android Studio

Recomendamos a utilização do Android Studio

Terminal físico

Chaves (Desenvolvimento/Produção)

Para iniciar o desenvolvimento, é necessário um terminal físico com chaves válidas de desenvolvimento ou produção. As chaves utilizadas devem ser de DEV, se o objetivo for o desenvolvimento de aplicativos. As chaves utilizadas devem ser de PROD, se o objetivo for capturar transações com as aplicações já existentes. As chaves devem ser adquiridas junto aos fabricantes dos terminais.

Veja quais terminais estão homologados

Warning: Atualmente não é possível utilizar a integração de pagamento em emuladores Android ou SmartPhones. Essa solução foi desenvolvida para terminais POS (Point Off Service)

Portal da PayStore

Cadastros (Facilitador, Estabelecimento, Terminal)

É necessário acessar o Portal da PayStore ambiente de desenvolvimento para esse primeiro contato e realizar os cadastros necessários para inicializar o terminal pela primeira vez. Nesse processo entre em contato com a equipe de suporte.

APKs PayStore necessários

Sequência de Instalação

Os aplicativos PayStore devem estar instalados no terminal. A instalação deve ser feita na seguinte ordem:

Aplicativos	Descrição
1.payments (Pagamentos)	Operações de pagamento.
2.platform (Terminal)	Gerenciar terminal
3.receipt (Comprovante)	Impressão
4.acquirer (Adquirente)	Integração com as adquirentes
5.client (Loja)	Loja PayStore

Para mais informações sobre as aplicações da PayStore, veja Apks PayStore

Com o ADB devidamente instalado e configurado na sua máquina, abra o prompt dentro do diretório com os arquivos, e execute o comando conforme ordem acima:

adb install -r [arquivo]

Se preferir utilize o programa PayDroid

Inicializar o terminal

Inicialização PayStore

Warning: Para continuar é importante que, nesse ponto, seu terminal já esteja inicializado com a PayStore. Caso tenha dúvidas sobre esse procedimento, entre em contato com a equipe de suporte

Tour pela documentação

Ler a documentação

Antes de iniciar de fato, é importante conhecer quais ferramentas estão disponíveis para o desenvolvimento. Por isso deve-se entender a arquitetura, os aplicativos envolvidos e como eles se comunicam. Veja as Referências API e explore todo o poder dessa integração.

App Demo Android

Para facilitar sua integração, criamos um projeto demo desenvolvido em Android já integrado com app Pagamentos. Explore esse projeto para visualizar a integração em ação.

App Demo React-Native

Criamos esse projeto demo para você ter liberdade de escolher qual tecnologia usar no desenvolvimento de sua aplicação. É possível integrar suas aplicações que não foram desenvolvidas, necessariamente em Android com nossas soluções de pagamento.

Iniciar Integração

Parabéns!

Se você chegou até aqui, é porque já possui todas as informações necessárias de para iniciar o desenvolvimento do seu aplicativo integrado à nossa solução de pagamento. Caso tenha dúvidas, entre em contato com a equipe de suporte.

Configurando Projeto

Adicionando lib de Integração ao Projeto

Entre em \app do seu projeto e crie uma pasta chamada libs. Baixe a última versão da lib payments-api-x.x.x.x.aar e copie para a pasta criada no seu projeto.

Após isso, abra o arquivo build.gradle (Module app) e adicione as seguintes dependências em destaque:

implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
implementation 'org.parceler:parceler-api:1.1.12'
annotationProcessor 'org.parceler:parceler:1.1.12'
implementation 'com.google.code.gson:gson:2.8.5'

Pronto! Seu projeto já está configurado e terá acesso às classes disponíveis na lib. Vide Referências API.

Apontamento 3 - esse link aponta pra o fornecedor

Configurando projeto para debug

Se o seu aplicativo está sendo desenvolvido para rodar em terminais POS (Point Of Service), é importante que seu aplicativo seja publicado na Paystore o quanto antes, mesmo que ainda esteja no começo.

Isso é necessário para que o terminal não remova o seu aplicativo automaticamente ao identificar que o app não está presente na loja da Paystore. Por isso não perca tempo e faça a publicação do seu app assim que possível. Veja como é simples aqui, caso necessário entre em contato com nosso suporte.

Telas do Fluxo de Pagamento

Ao realizar a integração do seu app com a aplicação de pagamento da PayStore e invocar o método que inicia o fluxo de pagamento startPaymentV2(), por exemplo, o fluxo da aplicação passa a ser controlado por payments. Neste processo, algumas telas serão apresentadas para o usuário, conforme a seguir:

Tela de captura de valor

Caso o aplicativo que chamou a integração de pagamento não informe o valor, este será solicitado ao usuário. Essa tela também possui uma calculadora integrada para outras operações.

Tela de seleção de tipo de pagamento

Essas opções também podem ser configuradas na integração.

Tela de seleção de operação de crédito

Essas opções também podem ser configuradas na integração.

Tela de solicitação de leitura do cartão

O cliente ou o operador deve inserir ou passar o cartão.

Tela de solicitação de digitação da senha do cartão

Tela de solicitação para retirar o cartão inserido, se for este o caso

Tela de impressão da Via do Cliente

Ao final, o fluxo de pagamento será retornado para a aplicação que o chamou através do

onSuccess() ou onError().

App Demo

repositório: App Demo Android

Aplicativo desenvolvido em Android integrado com a API de Pagamento da PayStore. Através desse aplicativo é possível realizar: Pagamento -> Confirmação ou Desfazimento -> Impressão do comprovante, desfazimento de pagamento ou estorno, Estorno de Pagamento e consultar Pagamento. Seguem algumas observações:

Tela principal com as opções possíveis do App Demo

No menu no canto superior direito, é possível definir a adquirente corrente. Os tipos de pagamento serão definidos de acordo com a adquirente selecionada.

Tela com opções para realizar o pagamento, onde é possível informar as seguintes informações:

● Digitar o valor do pagamento. Caso o valor não seja digitado será solicitado pela integração;

● Digitar número de parcelas (opcional) para pagamentos parcelados;

● Digitar e-mail para criar token do cartão. Isso é usado para pagamentos recorrentes;

● Selecionar os tipos de pagamento. É possível escolher quais opções serão exibidas pelo App de pagamentos.

Após realizar o pagamento através da opção Fazer Pagamento, é necessário fazer a confirmação ou o desfazimento.

A opção Fazer Pagamento de ponta a ponta realiza o fluxo de pagamento completo ou seja pagamento, confirmação e impressão.

Tela de seleção de operação de crédito

E essas opções também podem ser configuradas na integração.

Tela de confirmação e desfazimento do pagamento

Lista o pagamento com o status de pendente para ser confirmado.

Tela de estorno do pagamento

Lista todos os pagamentos confirmados. O usuário deve selecionar o pagamento que deseja estornar.

Tela de desfazimento do estorno

Lista todos os estornos. O usuário deve selecionar o estorno que deseja realizar o desfazimento.

Warning: A depender do comportamento de cada adquirente, é possível que não haja desfazimento para a transação de estorno.

Listar Pagamentos

Realiza uma consulta dos pagamentos de acordo com os filtros escolhidos.

Resolver Pendências

Realiza a confirmação de todos os pagamentos que estão pendentes.

Definir Tema da Aplicação

Define o Tema da aplicação de pagamentos. Dessa maneira, é possível mudar a cor da aplicação. As opções disponíveis são:

Definir Aplicação Principal

Através dessa opção, o Facilitador pode definir o apk desenvolvido por ele como o principal. Dessa forma, quando o terminal for ligado, a aplicação do Facilitador será chamada ao invés da aplicação padrão de pagamento da PayStore.

Referências API

Credenciais para Integração

Para realizar a integração entre aplicativos e a solução de pagamento da PayStore, é necessário adquirir algumas credenciais. As credenciais são geradas ao realizar a publicação do aplicativo no Portal da PayStore, através da opção Aplicativos -> Publicados -> Detalhes da aplicação. Serão exibidos o APLICATION_ID e o SECRET_TOKEN. Estas informações devem ser adicionadas ao aplicativo em desenvolvimento que deseja realizar a integração de pagamento.

Warning
As credenciais para o ambiente de desenvolvimento são
public static final String TEST_APPLICATION_ID = “0”; public static final String TEST_SECRET_TOKEN = “000000000000000000000000”;

A classe CredentialsUtils.java presente no projeto demo mostra uma forma de implementar as credenciais que serão usadas no request do pagamento através da classe PaymentRequestV2.java que está presente na lib de integração payments-api-x.x.x.x.aar. Para mais detalhes, veja o projeto demo.

Pagamento

[DEPRECATED] Integração com Pagamentos V1**

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

Aqui está a tabela transformada em Markdown:

markdown Copiar código | 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	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) {
CLASSIFICAÇÃO: PÚBLICA 56 / 236
 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(Payment payment) {
 Log.i(TAG, payment.toString());
 }
 });
 } 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(Payment payment) {
 Log.i(TAG, payment.toString());
 }
 });
 } catch (ClientException e) {
 Log.e(TAG, "Error cancelPayment", e);
 }
 }
}

Integração com Pagamentos V2

A seguir, temos a especificação detalhada das operações disponíveis.

Para integração com a API de pagamentos, é fornecida a interface PaymentClient presente na biblioteca.

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.

Fluxo de Pagamento

Passos	Sucesso	Erro
1.Solicitação de pagamento	O pagamento foi realizado e seu status é Pendente	O pagamento não foi realizado. A resposta contém informações do erro.
2.Resposta solicitação de pagamento	A resposta contém informações do pagamento realizado.	A resposta contém informações do erro da solicitação.
3.Solicitação de confirmação	Confirmação realizada, seu status é Confirmada, não pode ser desfeita.	Confirmação não realizada. A resposta contém informações do erro.
4.Resposta da confirmação	A resposta contém informações da confirmação realizada. Impressão do Comprovante	A resposta contém informações do erro da solicitação. Nesse ponto pode ser enviado o desfazimento.
5.Solicitação de desfazimento	Desfazimento realizado, seu status é Desfeita. Não pode ser confirmada.	A resposta contém informações do erro da solicitação. O status continua Pendente.
6.Resposta do desfazimento	A resposta contém informações do desfazimento realizado.	A resposta contém informações do erro da solicitação.

O pagamento só é finalizado quando existe uma confirmação ou um cancelamento (desfazimento). Em caso de confirmação, o comprovante estará disponível para impressão ou envio por SMS/e-mail, dependendo das funcionalidades do terminal.

A partir da versão 3.1.4.3

Quando uma transação é feita e o app solicita sua confirmação (confirmPayment()) ou desfazimento (cancelPayment()), a resposta solicitação será enviada ao app assim que a transação for resolvida localmente pelo terminal, eliminando a necessidade de o app esperar a resolução com o autorizador para dar continuidade ao fluxo.

Após isto, o terminal tentará resolver a transação com o autorizador. Isto pode ocorrer imediatamente ao finalizar a transação, ou posteriormente, na resolução de pendências.

Métodos

Assinatura	Descrição
void startPaymentV2(PaymentRequestV2 paymentRequest, PaymentCallback paymentCallback)	Realiza o processo de autorização de pagamento.
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.
void getPayment(String paymentId, PaymentCallback paymentCallback)	Realiza consulta dos dados de uma transação diretamente no servidor connecta.

startPaymentV2()

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	PaymentRequestV2	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 (PaymentRequestV2)

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. O valor deverá ser formatado com duas casas decimais.
additionalValueType	AdditionalValueType	Não	Tipo de valor adicional (Cashback, TIP, etc.). Se não estiver preenchido (nulo), deve-se ignorar o campo “additionalValue”. Para FastTrack, apenas o valor CASHBACK é permitido.
additionalValue	BigDecimal	Não	Valor adicionado ao valor da transação. Se “additionalValueType” for relatado e “additionalValue” não foi preenchido (nulo) ou é igual a 0 (zero), a interface irá pedir ao operador o valor adicional.
paymentTypes	List	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.
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.
accountTypeId	String	Não	Tipo de conta. Se não for preenchido (nulo), a interface pode perguntar ao operador o tipo de conta.
planId	String	Não	Identificação do plano de pagamento. Pode ter um ou dois caracteres, a depender da regra da adquirente selecionada.
appTransactionId	String	Sim	Identificador da transação integrada para o software. 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.
ApplicationInfo.softwareVersion	String	Sim	Versão da aplicação que está solicitando o pagamento.
showReceiptView (DEPRECATED)	Boolean	Não	A Solução irá utilizar o valor dos parâmetros printMerchantReceipt e printCustomerReceipt para executar a impressão depois que a confirmação for executada.
printMerchantReceipt	Boolean	Não	Indica se o comprovante do estabelecimento deve ser impresso ou não depois da confirmação da transação. O valor padrão é true, isto é, o comprovante é impresso.
printCustomerReceipt	Boolean	Não	Indica se o comprovante do cliente deve ser impresso ou não depois da confirmação da transação. O valor padrão é true, isto é, o comprovante é impresso.
tokenizeCard	Boolean	Não	Indica se deve ser feita ou não a tokenização do cartão após a aprovação do pagamento. O valor padrão é false, isto é, não será feita a tokenização.
tokenizeEmail	String	Se tokenizeCard for true, caso contrário, não.	E-mail do portador do cartão. Se “tokenizeCard” for false, este parâmetro é ignorado.
tokenizeNationalDocument	String	Não	CPF ou CNPJ do portador do cartão. Se “tokenizeCard” for false, este parâmetro é ignorado.
productShortName	String	Não	Identificação resumida do produto de bandeira do cartão.
note	String	Não	Texto adicional que é inserido como Nota. (pode ser o número da fatura)
dni	String	Não	Número do Documento.
operationMethodAllowed	Integer	Sim	Indica o método de operação de pagamento, anulação e devolução. Admita os seguintes valores: 0 - Apenas com cartão físico (lido ou digitado); 1 - Somente com QRCode.
allowBenefit (OBSOLETO)	Boolean	Não	Indica se o QRCode deve ser gerado com as opções do produto associadas aos benefícios. O valor padrão é ‘verdadeiro’, ou seja, os benefícios serão adicionados.
previewMerchantReceipt	Boolean	Não	Indica se a tela de pré-visualização do comprovante do estabelecimento deve ser exibida após a confirmação da transação. O valor padrão é true, o que significa que o comprovante será exibido.
previewCustomerReceipt	Boolean	Não	Indica se a tela de pré-visualização do comprovante do cliente deve ser exibida após a confirmação da transação. O valor padrão é true, o que significa que o comprovante será exibido.

callback (PaymentCallback)

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).

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	-	Método para notificação em caso de sucesso.
onError	Método	-	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.

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	-	Método para notificação em caso de sucesso.
onError	Método	-	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.

Campo adicional api_pending

Além dos métodos para resolução de pagamentos (confirmPayment e cancelPayment), há a possibilidade de se configurar um campo adicional no Portal Paystore para realizar esta resolução automaticamente, em determinado tempo. Para isto, deve ser criado um campo adicional no Portal Paystore com o tipo JSON e a chave api_pending.

Valor do campo

Nome	Tipo	Obrigatório	Descrição
confirmationTime	String	Sim	Intervalo, em minutos, para resolução das pendências.
transactionConfirmation	String	Sim	Ação a ser tomada. Permite os valores CONFIRM (Confirma a transação) ou UNDO (Desfaz a transação).

Exemplo JSON:

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

EXEMPLO DO FLUXO DE PAGAMENTO

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("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.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);
 /*
 Se, na sua regra de negócio, for preciso desfazer a transação por algum motivo,
 chame o método 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(PaymentV2 payment) {
 Log.i(TAG, payment.toString());
 }
 });
 } 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(PaymentV2 payment) {
 Log.i(TAG, payment.toString());
 }
 });
 } catch (ClientException e) {
 Log.e(TAG, "Error cancelPayment", e);
CLASSIFICAÇÃO: PÚBLICA 80 / 236
 }
 }
}

getPayment()

Este método é usado para obter as informações de uma transação. Durante sua execução, os dados serão solicitados via API do connecta, sendo obrigatório a conexão com a internet.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
paymentId	String	Sim	Identificador da transação que será localizada. 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	Sim	Método para notificação em caso de sucesso.
onError	Método	Sim	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.responseMessage	String	Sim	Mensagem descritiva da causa da não localizado.

Exemplo de chamada de

private fun doGetPayment(payment: Payment, callback: (Boolean) -> Unit) {
try {
paymentClient.getPayment(payment.paymentId, object : PaymentCallback<Any?> {
override fun onSuccess(data: Any?) {
val toast: Toast = Toast.makeText(
this@MainActivity,
"Dados retornardo com sucesso",
Toast.LENGTH_SHORT
)
toast.show()
callback(true)
}
 override fun onError(errorData: ErrorData) {
 val toast: Toast = Toast.makeText(
 this@MainActivity,
 R.string.payment_not_get,
 Toast.LENGTH_SHORT
 )
 toast.show()
 callback(true)
 }
 })
} catch (e: Exception) {
 Toast.makeText(
 this@MainActivity,
 e.message,
 Toast.LENGTH_LONG
 ).show()
 callback(true)
}
}

Exemplo do retorno de dados getPayment()

{
"MerchantOrderId": "20180204",
"Customer": {
"Name": "[Guest]"
},
"Payment": {
"Installments": 1,
"Interest": "ByMerchant",
"CreditCard": {
"ExpirationDate": "12/2020",
"BrandId": 1,
"IssuerId": 2,
"TruncateCardNumberWhenPrinting": true,
"InputMode": "Emv",
"AuthenticationMethod": "OnlineAuthentication",
"EmvData": "112233445566778899011AABBC012D3456789E0123FF45678AB901234C5D112233445566778800",
"PinBlock": {
"EncryptedPinBlock": "2280F6BDFD0C038D",
"EncryptionType": "Dukpt3Des",
"KsnIdentification": "1231vg31fv231313123"
}
},
"PaymentDateTime": "2019-04-15T12:00:00Z",
"ServiceTaxAmount": 0,
"SoftDescriptor": "Description",
"ProductId": 1,
"PinPadInformation": {
"TerminalId": "10000001",
"SerialNumber": "ABC123",
"PhysicalCharacteristics": "PinPadWithChipReaderWithSamModule",
"ReturnDataInfo": "00"
},
"Amount": 15798,
"ReceivedDate": "2019-04-15T12:00:00Z",
"CapturedAmount": 15798,
"Provider": "Cielo",
"ConfirmationStatus": 0,
"InitializationVersion": 1558708320029,
"EmvResponseData": "123456789ABCD1345DEA",
"Status": 2,
"IsSplitted": false,
"ReturnCode": 0,
"ReturnMessage": "Successful",
CLASSIFICAÇÃO: PÚBLICA 83 / 236
"PaymentId": "f15889ea-5719-4e1a-a2da-f4e50d5bd702",
"Type": "PhysicalDebitCard",
"Currency": "BRL",
"Country": "BRA",
"Links": [
 {
 "Method": "GET",
 "Rel": "self",
 "Href": "<https://api.cieloecommerce.cielo.com.br/1/physicalSales/f15889ea-5719-4e1a-a2daf4e50d5bd702>"
 },
 {
 "Method": "DELETE",
 "Rel": "self",
 "Href": "<https://api.cieloecommerce.cielo.com.br/1/physicalSales/f15889ea-5719-4e1a-a2daf4e50d5bd702>"
 },
 {
 "Method": "PUT",
 "Rel": "self",
 "Href": "<https://api.cieloecommerce.cielo.com.br/1/physicalSales/f15889ea-5719-4e1a-a2daf4e50d5bd702/confirmation>"
 }
],
"PrintMessage": [
 {
 "Position": "Top",
 "Message": "Transação autorizada"
 },
 {
 "Position": "Bottom",
 "Message": "Obrigado e volte sempre!"
 }
],
"ReceiptInformation": [
 {
 "Field": "MERCHANT_NAME",
 "Label": "NOME DO ESTABELECIMENTO",
 "Content": "Estabelecimento"
 },
 {
 "Field": "MERCHANT_ADDRESS",
 "Label": "ENDEREÇO DO ESTABELECIMENTO",
 "Content": "Rua Sem Saida, 0"
 },
 {
 "Field": "MERCHANT_CITY",
 "Label": "CIDADE DO ESTABELECIMENTO",
 "Content": "Cidade"
 },
 {
 "Field": "MERCHANT_STATE",
 "Label": "ESTADO DO ESTABELECIMENTO",
 "Content": "WA"
 },
 {
 "Field": "MERCHANT_CODE",
 "Label": "COD.ESTAB.",
 "Content": 1234567890123456
 },
 {
 "Field": "TERMINAL",
 "Label": "POS",
 "Content": 12345678
 },
 {
 "Field": "NSU",
CLASSIFICAÇÃO: PÚBLICA 85 / 236
 "Label": "DOC",
 "Content": 123456
 },
 {
 "Field": "DATE",
 "Label": "DATA",
 "Content": "01/01/20"
 },
 {
 "Field": "HOUR",
 "Label": "HORA",
 "Content": "01:01"
 },
 {
 "Field": "ISSUER_NAME",
 "Label": "EMISSOR",
 "Content": "NOME DO EMISSOR"
 },
 {
 "Field": "CARD_NUMBER",
 "Label": "CARTÃO",
 "Content": 5432123454321234
 },
 {
 "Field": "TRANSACTION_TYPE",
 "Label": "TIPO DE TRANSAÇÃO",
 "Content": "VENDA A CREDITO"
 },
 {
 "Field": "AUTHORIZATION_CODE",
 "Label": "AUTORIZAÇÃO",
 "Content": 123456
 },
 {
 "Field": "TRANSACTION_MODE",
 "Label": "MODO DA TRANSAÇÃO",
 "Content": "ONL"
 },
 {
 "Field": "INPUT_METHOD",
 "Label": "MODO DE ENTRADA",
 "Content": "X"
 },
 {
 "Field": "VALUE",
 "Label": "VALOR",
 "Content": "1,23"
 },
 {
 "Field": "SOFT_DESCRIPTOR",
 "Label": "SOFT DESCRIPTOR",
 "Content": "Simulado"
 }
],
"Receipt": {
 "MerchantName": "Estabelecimento",
 "MerchantAddress": "Rua Sem Saida, 0",
 "MerchantCity": "Cidade",
 "MerchantState": "WA",
 "MerchantCode": 1234567890123456,
 "Terminal": 12345678,
 "Nsu": 123456,
 "Date": "01/01/20",
 "Hour": "01:01",
 "IssuerName": "NOME DO EMISSOR",
 "CardNumber": 5432123454321234,
 "TransactionType": "VENDA A CREDITO",
 "AuthorizationCode": 123456,
 "TransactionMode": "ONL",
CLASSIFICAÇÃO: PÚBLICA 87 / 236
 "InputMethod": "X",
 "Value": "1,23",
 "SoftDescriptor": "Simulado"
}
}
}

getPaymentByMerchantOrderId()

Este método é usado para obter as informações de uma transação. Durante sua execução, os dados serão solicitados via API do Connecta, sendo obrigatório a conexão com a internet.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
merchantOrderId	String	Sim	ID Externo do pagamento gerado pelo usuário no formato string de 15 posições.
callback	PaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro.

Detalhe dos parâmetros

Call-back *

Nome	Tipo	Obrigatório	Descrição
onSuccess	Método	Sim	Método para notificação em caso de sucesso.
onError	Método	Sim	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.responseMessage	String	Sim	Mensagem descritiva da causa da não autorização ou localização.

Exemplo de chamada de getPaymentByMerchantOrderId()

paymentClient.getPaymentByMerchantOrderId("123456", new PaymentCallback<Any?>() {
@Override
public void onSuccess(Any? data) {
Toast toast = Toast.makeText(this@MainActivity, "Dados retornados com sucesso",
Toast.LENGTH_SHORT);
toast.show();
callback(true);
}
@Override
public void onError(ErrorData errorData) {
Toast toast = Toast.makeText(this@MainActivity, R.string.payment_not_get, Toast.LENGTH_SHORT);
toast.show();
callback(false);
}
});

Exemplo do retorno de dados getPaymentMerchantOrderId()

{
"MerchantOrderId": "20180204",
"Customer": {
"Name": "[Guest]"
},
"Payment": {
"Installments": 1,
"Interest": "ByMerchant",
"CreditCard": {
"ExpirationDate": "12/2020",
"BrandId": 1,
"IssuerId": 2,
"TruncateCardNumberWhenPrinting": true,
"InputMode": "Emv",
"AuthenticationMethod": "OnlineAuthentication",
"EmvData": "112233445566778899011AABBC012D3456789E0123FF45678AB901234C5D112233445566778800",
"PinBlock": {
"EncryptedPinBlock": "2280F6BDFD0C038D",
"EncryptionType": "Dukpt3Des",
"KsnIdentification": "1231vg31fv231313123"
}
},
"PaymentDateTime": "2019-04-15T12:00:00Z",
"ServiceTaxAmount": 0,
"SoftDescriptor": "Description",
"ProductId": 1,
"PinPadInformation": {
"TerminalId": "10000001",
"SerialNumber": "ABC123",
"PhysicalCharacteristics": "PinPadWithChipReaderWithSamModule",
"ReturnDataInfo": "00"
},
"Amount": 15798,
"ReceivedDate": "2019-04-15T12:00:00Z",
"CapturedAmount": 15798,
"Provider": "Cielo",
"ConfirmationStatus": 0,
"InitializationVersion": 1558708320029,
"EmvResponseData": "123456789ABCD1345DEA",
"Status": 2,
"IsSplitted": false,
"ReturnCode": 0,
"ReturnMessage": "Successful",
"PaymentId": "f15889ea-5719-4e1a-a2da-f4e50d5bd702",
"Type": "PhysicalDebitCard",
"Currency": "BRL",
"Country": "BRA",
"Links": [
 {
 "Method": "GET",
 "Rel": "self",
 "Href": "<https://api.cieloecommerce.cielo.com.br/1/physicalSales/f15889ea-5719-4e1a-a2daf4e50d5bd702>"
 },
 {
 "Method": "DELETE",
 "Rel": "self",
 "Href": "<https://api.cieloecommerce.cielo.com.br/1/physicalSales/f15889ea-5719-4e1a-a2daf4e50d5bd702>"
 },
 {
 "Method": "PUT",
 "Rel": "self",
 "Href": "<https://api.cieloecommerce.cielo.com.br/1/physicalSales/f15889ea-5719-4e1a-a2daf4e50d5bd702/confirmation>"
 }
],
"PrintMessage": [
 {
 "Position": "Top",
 "Message": "Transação autorizada"
 },
 {
 "Position": "Bottom",
 "Message": "Obrigado e volte sempre!"
 }
],
"ReceiptInformation": [
 {
 "Field": "MERCHANT_NAME",
 "Label": "NOME DO ESTABELECIMENTO",
 "Content": "Estabelecimento"
 },
 {
 "Field": "MERCHANT_ADDRESS",
 "Label": "ENDEREÇO DO ESTABELECIMENTO",
 "Content": "Rua Sem Saida, 0"
 },
 {
 "Field": "MERCHANT_CITY",
 "Label": "CIDADE DO ESTABELECIMENTO",
 "Content": "Cidade"
 },
 {
 "Field": "MERCHANT_STATE",
 "Label": "ESTADO DO ESTABELECIMENTO",
 "Content": "WA"
 },
 {
 "Field": "MERCHANT_CODE",
 "Label": "COD.ESTAB.",
 "Content": 1234567890123456
 },
 {
 "Field": "TERMINAL",
 "Label": "POS",
 "Content": 12345678
 },
 {
 "Field": "NSU",
 "Label": "DOC",
 "Content": 123456
 },
 {
 "Field": "DATE",
 "Label": "DATA",
CLASSIFICAÇÃO: PÚBLICA 92 / 236
 "Content": "01/01/20"
 },
 {
 "Field": "HOUR",
 "Label": "HORA",
 "Content": "01:01"
 },
 {
 "Field": "ISSUER_NAME",
 "Label": "EMISSOR",
 "Content": "NOME DO EMISSOR"
 },
 {
 "Field": "CARD_NUMBER",
 "Label": "CARTÃO",
 "Content": 5432123454321234
 },
 {
 "Field": "TRANSACTION_TYPE",
 "Label": "TIPO DE TRANSAÇÃO",
 "Content": "VENDA A CREDITO"
 },
 {
 "Field": "AUTHORIZATION_CODE",
 "Label": "AUTORIZAÇÃO",
 "Content": 123456
 },
 {
 "Field": "TRANSACTION_MODE",
 "Label": "MODO DA TRANSAÇÃO",
 "Content": "ONL"
 },
 {
 "Field": "INPUT_METHOD",
 "Label": "MODO DE ENTRADA",
 "Content": "X"
 },
 {
 "Field": "VALUE",
 "Label": "VALOR",
 "Content": "1,23"
 },
 {
 "Field": "SOFT_DESCRIPTOR",
 "Label": "SOFT DESCRIPTOR",
 "Content": "Simulado"
 }
],
"Receipt": {
 "MerchantName": "Estabelecimento",
 "MerchantAddress": "Rua Sem Saida, 0",
 "MerchantCity": "Cidade",
 "MerchantState": "WA",
 "MerchantCode": 1234567890123456,
 "Terminal": 12345678,
 "Nsu": 123456,
 "Date": "01/01/20",
 "Hour": "01:01",
 "IssuerName": "NOME DO EMISSOR",
 "CardNumber": 5432123454321234,
 "TransactionType": "VENDA A CREDITO",
 "AuthorizationCode": 123456,
 "TransactionMode": "ONL",
 "InputMethod": "X",
 "Value": "1,23",
 "SoftDescriptor": "Simulado"
}
}
}

Estorno

[DEPRECATED] Integração com Estorno V1

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 reversePayment(ReversePaymentRequest paymentRequest, PaymentCallback paymentCallback)`	Realiza o processo de estorno de pagamento. (DEPRECATED: Utilizar `reversePaymentV2`)
`void cancelReversePayment(String paymentId, PaymentCallback paymentCallback)`	Desfaz uma solicitação de estorno de pagamento.

reversePayment() (DEPRECATED: Utilizar reversePaymentV2)

Este método deve ser chamado quando se deseja fazer uma solicitação de estorno de pagamento. Durante sua execução, os dados do estorno serão validados, informações adicionais serão solicitadas ao operador (e.g. cartão) e a autorização junto à adquirente será feita.

Note que a transação de estorno não possui confirmação, mas apenas desfazimento. Assim, a confirmação ocorrerá naturalmente com o não envio do desfazimento, a depender do comportamento de cada adquirente.

Também a depender do comportamento de cada adquirente, é possível que não haja desfazimento para a transação de estorno. Neste caso, estornos aprovados retornarão o valor false no campo “ReversePayment.cancelable”. Além disto, caso seja chamado o método cancelReversePayment(), um erro específico será retornado informando que não é possível executar tal operação (vide Códigos de Resposta).

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	ReversePaymentRequest	Sim	Objeto de transferência de dados que conterá as informações da requisição do estorno do pagamento. Note que nem todos os parâmetros são obrigatórios.
callback	ReversePaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro do processo de estorno.

Detalhe dos parâmetros

request (ReversePaymentRequest)

Nome	Tipo	Obrigatório	Descrição
value	`BigDecimal`	Não	Valor da transação a ser estornada. Caso não seja preenchido (null), a interface solicitará o valor ao operador. Esta informação é utilizada para validar a integridade da transação que está sendo estornada.
paymentId	`String`	Sim	Identificador da transação que será estornada. O Identificador referido é aquele utilizado na aplicação de pagamentos.
appTransactionId	`String`	Sim	Identificador da transação integrada. O Identificador referido é o da aplicação que originou a solicitação de estorno. Deve ser o mesmo valor enviado na transação de pagamento.
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.

callback (ReversePaymentCallback)

Parâmetros

Nome	Tipo	Obrigatório	Descrição
onSuccess	Método	Sim	Método para notificação em caso de sucesso.
ReversePayment.paymentId	`String`	Sim	Identificador da transação de estorno para a aplicação de pagamentos. Esta é a informação a ser usada para a confirmação e desfazimento.
ReversePayment.acquirerId	`String`	Sim	Identificador da transação de estorno para a adquirente. Este é o identificador que consta no arquivo que a adquirente fornece (EDI). Desta forma, é possível realizar a conciliação do estorno com a transação integrada.
ReversePayment.cancelable	`Boolean`	Sim	True, caso esta transação possa ser desfeita; False, caso contrário.
ReversePayment.acquirerResponseCode	`String`	Sim	Código de resposta da adquirente.
ReversePayment.acquirerResponseDate	`String`	Sim	Data/hora retornada pela adquirente.
ReversePayment.acquirerAuthorizationNumber	`String`	Sim	Número da autorização fornecido pela adquirente (consta no comprovante do cliente Portador do Cartão).
ReversePayment.Receipt.clientVia	`String`	Não	Conteúdo do comprovante - via do cliente.
ReversePayment.Receipt.merchantVia	`String`	Não	Conteúdo do comprovante - via do estabelecimento.
onError	Método	Sim	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.

cancelReversePayment()

Este método deve ser chamado para desfazer uma transação de estorno anteriormente autorizada. Esta transação deve não ter sido desfeita ainda e deve ter sido autorizada (não negada) previamente.

Como dito na descrição dereversePayment(), é possível que não haja desfazimento para a transação de estorno para uma determinada adquirente. Assim, o método cancelReversePayment() pode retornar um erro específico informando que não é possível executar tal operação (vide Códigos de Resposta).

Parâmetros

Nome	Tipo	Obrigatório	Descrição
paymentId	String	Sim	Identificador da transação que será desfeita. O Identificador referido é aquele utilizado pela aplicação de pagamentos.
callback	PaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro.

Detalhe dos parâmetros

callback

Exemplo do fluxo de Estorno

|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 {    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());
        /*
         Se, na sua regra de negócio, for preciso desfazer a transação por algum motivo,
          chame o método cancelReversePayment()
        **/
        //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() {                        @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(ReversePayment reversePayment) {
                            Log.i(TAG, reversePayment.toString());
                        }
                    });
        } catch (ClientException e) {
            Log.e(TAG, “Error cancelReversePayment”, e);
        }
    }
}| | :- | —–

Integração com Estorno V2

Apontamento 5 - links payments-api-xxx aponta para repositório do fornecedor.

A seguir, temos a especificação detalhada das operações disponíveis.

Para integração com a API de pagamentos, é fornecida a interface PaymentClient.

Fluxo de Estorno

Passos	Sucesso	Erro
1.Solicitação de estorno do pagamento	O estorno do pagamento foi realizado e seu status é Estornado	O estorno do pagamento não foi realizado. A resposta contém informações do erro.
2.Resposta solicitação de estorno do pagamento	A resposta contém informações do estorno do pagamento realizado.	A resposta contém informações do erro da solicitação.
3.Solicitação de desfazimento do estorno	Desfazimento realizado, seu status é Desfeita.	A resposta contém informações do erro da solicitação.
4.Resposta do desfazimento do estorno	A resposta contém informações do desfazimento realizado.	A resposta contém informações do erro da solicitação.

O estorno só é finalizado quando existe uma confirmação ou um desfazimento. Em caso de confirmação, o comprovante será impresso.

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

A partir da versão 3.1.5.0

Quando uma transação é feita, anteriormente, poderia ser confirmado realizando sua impressão (ou via printReceipt), ou ao realizar uma nova transação. Agora, o estorno também pode ser confirmado ao usar o novo parâmetro autoconfiram - indicando se deve ou não confirmar independente da impressão - ou utilizando o novo método confirmReversePayment().

Métodos

|Assinatura|Descrição| | :- | :- | |void reversePaymentV2(ReversePaymentRequestV2 paymentRequest, PaymentCallback paymentCallback)|Realiza o processo de estorno de pagamento.| |void confirmReversePayment(String paymentId, PaymentCallback paymentCallback)|Confirma uma autorização de estorno de pagamento realizada anteriormente.| |void cancelReversePayment(String paymentId, PaymentCallback paymentCallback)|Desfaz uma solicitação de estorno de pagamento.|

reversePaymentV2()

Note que a transação de estorno não possui confirmação, mas apenas desfazimento. Assim, a confirmação ocorrerá naturalmente com o não envio do desfazimento, a depender do comportamento de cada adquirente. Caso haja impressão do comprovante do estorno, quando for passado algum dos parâmetros printMerchantReceipt ou printCustomerReceipt com valor true, o estorno será confirmado automaticamente. Neste caso, o desfazimento não será permitido.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	ReversePaymentRequestV2	Sim	Objeto de transferência de dados que conterá as informações da requisição do estorno do pagamento. Note que nem todos os parâmetros são obrigatórios.
callback	ReversePaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro do processo de estorno.

Detalhe dos parâmetros

request (ReversePaymentRequestV2)

Nome	Tipo	Obrigatório	Descrição
value	BigDecimal	Não	Valor da transação a ser estornada. Caso não seja preenchido (null), a interface solicitará o valor ao operador. Esta informação é utilizada para validar a integridade da transação que está sendo estornada.O valor deverá ser formatado com duas casas decimais.
paymentId	String	Sim	Identificador da transação que será estornada. O identificador referido é aquele utilizado na aplicação de pagamentos.
appTransactionId	String	Sim	Identificador da transação integrada. O identificador referidoé o da aplicação que originou a solicitação de estorno. Deve ser o mesmo valor enviado na transação de pagamento.
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 irá utilizar o valor dos parâmetros printMerchantReceipt e printCustomerReceipt para executar a impressão.
printMerchantReceipt	Boolean	Não	Indica se o comprovante do estabelecimento deve ser impresso ou não. O valor padrão é false, isto é, o comprovante não é impresso.
printCustomerReceipt	Boolean	Não	Indica se o comprovante do cliente deve ser impresso ou não. O valor padrão é false, isto é, o comprovante não é impresso.
previewMerchantReceipt	Boolean	Não	Indica se a tela de pré-visualização do comprovante do estabelecimento deve ser exibida após a confirmação da transação. O valor padrão é true, o que significa que o comprovante será exibido.
previewCustomerReceipt	Boolean	Não	Indica se a tela de pré-visualização do comprovante do cliente deve ser exibida após a confirmação da transação. O valor padrão é true, o que significa que o comprovante será exibido.
autoConfirm (v3.1.5.0)	Boolean	Não	Indica se a transação deve ser confirmada automaticamente.Valores possíveis:1. null (padrão) : confirma automaticamente caso ocorra a impressão do comprovante.2. true : confirma automaticamente independente da regra de impressão.3. false : não confirma automaticamente, ficando pendente aguardando confirmação.

callback (ReversePaymentCallback)

confirmReversePayment()

Este método deve ser chamado para confirmar um estorno que o terminal conseguiu processar completamente a perna de autorização enviada pelo Autorizador.

Este método não deve ser chamado para um estorno já confirmado, ou seja, em que já se executou o método confirmReversePayment() anteriormente.

Este método não deve ser chamado para um estorno já desfeito, ou seja, em que já se executou o método cancelReversePayment() anteriormente.

Este método não deve ser chamado para um estorno que foi negada pelo Autorizador, ou seja, a transação precisa ter sido autorizada pelo Autorizador.

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

cancelReversePayment()

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

Exemplo do fluxo de Estorno

|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.ReversePaymentRequestV2;
import br.com.phoebus.android.payments.api.exception.ClientException;public class MainActivity extends AppCompatActivity implements View.OnClickListener, PaymentClient.PaymentCallback {    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(){
        ReversePaymentRequestV2 request = new ReversePaymentRequestV2();
        BigDecimal value = BigDecimal.valueOf(5000).movePointLeft(2);
        request.setValue(value);
        request.setAppTransactionId(“123456”);        request.setPaymentId(“999999”);
        request.setPrintCustomerReceipt(true);
        request.setPrintMerchantReceipt(true);        Credentials credentials = new Credentials();
        credentials.setApplicationId(TEST_APPLICATION_ID);
        credentials.setSecretToken(TEST_SECRET_TOKEN);

        request.setCredentials(credentials);        try {
            paymentClient.reversePaymentV2(request, this);
        } catch (ClientException e) {
            Log.e(TAG, “Error reversePaymentV2”, e);
        }
    }    @Override
   public void onSuccess(ReversePayment reversePayment) {
        Log.i(TAG, reversePayment.toString());
        /*
          Se, na sua regra de negócio, for preciso desfazer a
          transação por algum motivo, chame o método
          cancelReversePayment()
        **/
        //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() {

                        @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(ReversePayment reversePayment) {
                            Log.i(TAG, reversePayment.toString());
                        }
                    });
        } catch (ClientException e) {
            Log.e(TAG, “Error cancelReversePayment”, e);
        }
    }
}| | :- |

Enums

Status de Pagamento

Código	Nome	Descrição
1	PENDING	Pagamento pendente
2	CONFIRMED	Pagamento confirmado
3	CANCELLED	Desfeita/Cancelada
4	REVERSED	Pagamento estornado
5	PROCESSING	Pagamento em processamento
6	DENIED	Pagamento negado
7	UNREACHABLE	Transação substituída (pré-autorização)
8	WAITING_VALIDATION	Aguardando validação
9	WAITING_CAPTURE	Aguardando captura
10	REFUNDED_DEVOLUTION	Devolução não referenciada
11	REFUNDED	Devolvida
12	APPROVED	Pagamento aprovado

Status de Estorno

Código	Nome	Descrição
1	PROCESSING	Estorno em processamento
2	PENDING	Estorno pendente, pode não ter havido resposta, ou ter a resposta aprovada, mas sem impressão de comprovante, inibida da chamada de reversePaymentV2
3	CONFIRMED	Estorno aprovado
4	CANCELLED	Estorno negado

Tipos de Pagamento

Código	Nome	Descrição
1	CREDIT	Crédito à vista
2	DEBIT	Débito
3	CREDIT_STORE	Crédito parcelado sem juros
4	CREDIT_ADMIN	Crédito parcelado com juros
5	PRE_AUTHORIZATION	Pré-autorização
6	PRE_AUTHORIZATION_CONFIRMATION	Confirmação de pré-autorização
7	PRE_AUTHORIZATION_CREDIT_STORE	Pré autorização sem Juros
8	PRE_AUTHORIZATION_CREDIT_ADMIN	Pré autorização com Juros
9	PRE_AUTHORIZATION_SUBSTITUTIVE	Pré autorização substitutiva
10	DEBIT_POSTDATED	Débito pré datado
11	VOUCHER	Vale
12	VOUCHER_MEAL	Vale refeição
13	VOUCHER_FEED	Vale alimentação
14	VOUCHER_FLEET	Vale Frota
15	PRIVATE_LABEL	Bandeira privada
16	PRIVATE_LABEL_QUERY	Bandeira privada
17	PARCELED_CREDIT	Crédito parcelado

Tipos de Captura

Código	Nome	Descrição
1	MANUAL	Manual
2	MAGNETIC_STRIP	Tarja
3	CHIP	Chip
4	FALLBACK_MANUAL	Fallback digitado
5	FALLBACK_MAGNETIC_STRIP	Fallback de tarja
6	CHIP_CONTACTLESS	Chip sem contato
7	MAGNETIC_STRIP_CONTACTLESS	Tira magnética sem contato
8	QR_CODE	QR Code

Consultas

Estruturas de dados retornada

Payments

Reversal

Refund

Nome	Tipo	Descrição
id	String	Identificador da transação para a aplicação de pagamentos.
value	BigDecimal	Valor da transação. 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.
paymentType	PaymentType	Tipo de pagamento (Débito, Crédito, Voucher, etc.).
acquirerName	String	Adquirente que autorizou o pagamento.
cardBrand	String	Bandeira do cartão.
cardBin	String	BIN do cartão.
cardPanLast4Digits	String	Últimos 4 dígitos do PAN do cartão.
captureType	CaptureType	Forma de captura do cartão.
status	PaymentStatus	Situação do pagamento.
date	Date	Data/hora do pagamento para a aplicação de pagamentos.
acquirerId	String	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.
acquirerResponseCode	String	Código de resposta da adquirente.
acquirerResponseDate	String	Data/hora retornada pela adquirente.
acquirerAuthorizationNumber	String	Número da autorização fornecido pela adquirente (consta no comprovante do cliente Portador do Cartão).
clientVia	String	Conteúdo do comprovante - via do cliente.
merchantVia	String	Conteúdo do comprovante - via do estabelecimento.
accountTypeId	String	Presente apenas quando existe um tipo de conta no contexto da transação executada.
productShortName	String	Identificador de produto, retorna apenas transações de um produto.
batchNumber	String	Número de lote.
nsuTerminal	String	NSU gerado pelo terminal para a transação.
cardholderName	String	Nome do cliente no cartão.
lastTrx	Boolean	Indica ‘true’ se é a última transação aprovada, e ‘false’ caso contrário.
terminalId	String	Identificação do terminal.
appTransactionId	String	Identificador de transação para o aplicativo de pagamento. Esta é a informação que será usada para confirmar e desfazer o pagamento.
acquirerNsu	String	NSU Adquirente para consulta e identificação de transações.
ErrorData.paymentsResponseCode	String	Código de resposta para o erro que ocorreu. Vide Códigos de Resposta
ErrorData.responseMessage	String	Mensagem descritiva da causa da não autorização. Se a transação foi negada pela adquirente, conterá a mensagem retornada pela adquirente.

Consulta de Devolução não referenciada via API

Esta é uma consulta via Content Provider que possibilita que outros aplicativos possam consultar informações sobre devoluções não referenciadas, sendo possível realizar filtros e obter diversos dados das devoluções não referenciadas, conforme objeto de retorno.

Integração com Aplicação de Pagamentos via Content Provider

Só será permitido listar pagamentos feitos pela própria aplicação que está realizando a consulta.

Declare essa permissão no AndroidManifest.xml do seu Aplicativo para ter acesso ao Content Provider.

**

content://br.com.phoebus.android.payments.provider/payments/refunds

URI (Uniform Resource Identifier) para obtenção de informações de devoluções não referenciadas.

Para realizar o request da consulta de pagamento por período entre datas é necessário adicionar essa dependência.

implementation ‘com.jakewharton.threetenabp:threetenabp:1.0.3’

Parâmetros de entrada

Filtros

Retorno

A consulta de devolução não referenciada, retorna as devoluções não referenciadas que obedecerem aos filtros informados.

Os filtros informados são aplicados apenas aos campos das devoluções não referenciadas.

A lista de devoluções não referenciadas retornadas deve estar ordenada de forma ascendente pelo campo date.

EXEMPLO DE RETORNO

A estrutura “refund” é a mesma usada na consulta de última transação aprovada e confirmada;

● Quando 2 devoluções obedecem aos critérios informados:

|{
[
     {
        “refund”: {
            …
        }
     },
     {
        “refund”: {
            …
        }
     }
]
}| | :- |

| (informação) Info| | :-: |

Para facilitar o uso, são disponibilizadas classes de acesso ao provider:

● RefundProviderRequest

● PaymentProviderApi

EXEMPLO

|import androidx.appcompat.app.AppCompatActivity;import android.content.Intent;
import android.database.Cursor;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import android.widget.Toast;import com.jakewharton.threetenabp.AndroidThreeTen;import java.math.BigDecimal;import java.text.SimpleDateFormat;
import java.util.Arrays;import java.util.Date;
import java.util.List;
import java.util.TimeZone;import br.com.phoebus.android.payments.api.ApplicationInfo;
import br.com.phoebus.android.payments.api.Credentials;import br.com.phoebus.android.payments.api.Payment;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.PaymentStatus;
import br.com.phoebus.android.payments.api.provider.PaymentContract;
import br.com.phoebus.android.payments.api.provider.PaymentProviderApi;
import br.com.phoebus.android.payments.api.provider.PaymentProviderRequest;public class MainActivity extends AppCompatActivity implements View.OnClickListener {    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();
        AndroidThreeTen.init(getApplication());
    }    @Override
    public void onClick(View view) {
        doExecute();
    }    public void doExecute() {
        //definindo as credenciais
        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”);

       //criando objeto de request para o payment content provider
        RefundProviderRequest request = createRequest(applicationInfo);        try {
            //solicitando a lista de devolução não referenciada
            List refundList = PaymentProviderApi.create(this).findAllRefunds(request);
            //********* Outra forma de realizar a consulta ******************************************
            // Cursor cursor = getApplicationContext().getContentResolver().query(request.getUriBuilder().build(), null, null, null, null);
            // List refundList = RefundProviderResponse.fromCursor(cursor);
            //***************************************************************************************            Toast.makeText(this, paymentsList.size()+””, Toast.LENGTH_LONG).show();        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }
    }    private RefundProviderRequest createRequest(ApplicationInfo appInfo) {        RefundProviderRequest refundRequest = new RefundProviderRequest();
        refundRequest.setApplicationInfo(appInfo);

       //filtrando pelo refundId
        refundRequest.setRefundId(“000000000”);        //filtrando por período
        SimpleDateFormat isoFormat = new SimpleDateFormat(“yyyy-MM-dd’T’HH:mm:ss.SSS”);
        isoFormat.setTimeZone(TimeZone.getTimeZone(“UTC”));        try {
            Date dateStart = isoFormat.parse(“2020-04-06T00:00:00.000”);
            Date dateFinish =isoFormat.parse(“2020-04-06T23:59:59.000”);
            refundRequest.setStartDate(dateStart);
            refundRequest.setFinishDate(dateFinish);
        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }        //filtrando por faixa de valores de pagamento
        refundRequest.setStartValue(new BigDecimal(“0.00”));
        refundRequest.setFinishValue(new BigDecimal(“1000.00”));        //filtrando pelos 4 últimos dígitos do cartão
        refundRequest.setLastDigits(“9636”);        //filtrando pelos 4 últimos dígitos do cartão
        List status = Arrays.asList(new ReversalStatus[]{
                     ReversalStatus.PENDING,
                     ReversalStatus.PROCESSING,
                     ReversalStatus.CONFIRMED,
                     ReversalStatus.CANCELLED
             });
        return refundRequest;
    }
}| | :- | —–

Consulta de Estornos via API

Esta é uma consulta via Content Provider que possibilita que outros aplicativos possam consultar informações sobre os estornos, sendo possível realizar filtros e obter diversos dados dos estornos conforme objeto de retorno.

Integração com Aplicação de Pagamentos via Content Provider

Só será permitido listar pagamentos feitos pela própria aplicação que está realizando a consulta.

Declare essa permissão no AndroidManifest.xml do seu Aplicativo para ter acesso ao Content Provider.

**

content://br.com.phoebus.android.payments.provider/payments/reversals

URI (Uniform Resource Identifier) para obtenção de informações de estornos.

Para realizar o request da consulta por período entre datas é necessário adicionar essa dependência.

implementation ‘com.jakewharton.threetenabp:threetenabp:1.0.3’

Parâmetros de entrada

Filtros

Retorno

A consulta de estornos, retorna os estornos referenciados que obedecerem aos filtros informados, e os seus pagamentos associados.

Não retorna estornos que não obedecem aos filtros informados.

Os filtros informados são aplicados apenas aos campos dos estornos.

A lista de pagamentos retornados deve estar ordenada de forma ascendente pelo campo date do pagamento.

Em cada pagamento, a lista de estornos retornados deve estar ordenada de forma ascendente pelo campo date do estorno. Não retorna devoluções não referenciadas.

EXEMPLO DE RETORNO

As estruturas “payment” e “reversals” são as mesmas usadas na consulta de última transação aprovada e confirmada;

● Quando dois estornos de um pagamento, e um estorno de outro pagamento obedecem aos critérios informados (por exemplo, filtro com status = CANCELLED):

|[
{
    “payment”: {
        …
    },
    “reversals”: [
      {
         …
      },
      {
         …
      }
    ]
},
{
    “payment”: {
        …
    },
    “reversals”: [
      {
         …
      }
    ]
}
]| | :- |

| (informação) Info| | :-: |

Para facilitar o uso, são disponibilizadas classes de acesso ao provider:

● ReversalProviderRequest

● PaymentProviderApi

EXEMPLO

|import androidx.appcompat.app.AppCompatActivity;import android.content.Intent;
import android.database.Cursor;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import android.widget.Toast;import com.jakewharton.threetenabp.AndroidThreeTen;

import java.math.BigDecimal;import java.text.SimpleDateFormat;
import java.util.Arrays;import java.util.Date;
import java.util.List;
import java.util.TimeZone;import br.com.phoebus.android.payments.api.ApplicationInfo;
import br.com.phoebus.android.payments.api.Credentials;import br.com.phoebus.android.payments.api.Payment;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.PaymentStatus;
import br.com.phoebus.android.payments.api.provider.PaymentContract;
import br.com.phoebus.android.payments.api.provider.PaymentProviderApi;
import br.com.phoebus.android.payments.api.provider.PaymentProviderRequest;public class MainActivity extends AppCompatActivity implements View.OnClickListener {    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();
        AndroidThreeTen.init(getApplication());
    }    @Override
    public void onClick(View view) {
        doExecute();
    }    public void doExecute() {
        //definindo as credenciais
        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”);

        //criando objeto de request para o payment content provider
        ReversalProviderRequest request = createRequest(applicationInfo);               try {
            //solicitando a lista de estornos
            List transactionsList = PaymentProviderApi.create(this).findAllReversals(request);
            //********* Outra forma de realizar a consulta ******************************************
            // Cursor cursor = getApplicationContext().getContentResolver().query(request.getUriBuilder().build(), null, null, null, null);
            // List transactionsList = TransactionProviderResponse.fromCursor(cursor);
            //***************************************************************************************            Toast.makeText(this, transactionsList.size()+””, Toast.LENGTH_LONG).show();        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }
    }    private ReversalProviderRequest createRequest(ApplicationInfo appInfo) {

        ReversalProviderRequest reversalRequest = new ReversalProviderRequest();
        reversalRequest.setApplicationInfo(appInfo);        //filtrando pelo paymentId
        reversalRequest.setPaymentId(“000000000”);        //filtrando por período
        SimpleDateFormat isoFormat = new SimpleDateFormat(“yyyy-MM-dd’T’HH:mm:ss.SSS”);
        isoFormat.setTimeZone(TimeZone.getTimeZone(“UTC”));        try {
            Date dateStart = isoFormat.parse(“2020-04-06T00:00:00.000”);
            Date dateFinish =isoFormat.parse(“2020-04-06T23:59:59.000”);
            reversalRequest.setStartDate(dateStart);
            reversalRequest.setFinishDate(dateFinish);
        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }

        //filtrando por faixa de valores de pagamento
        reversalRequest.setStartValue(new BigDecimal(“0.00”));
        reversalRequest.setFinishValue(new BigDecimal(“1000.00”));        //filtrando pelos 4 últimos dígitos do cartão
        reversalRequest.setLastDigits(“9636”);        //filtrando pelos 4 últimos dígitos do cartão
        List status = Arrays.asList(new ReversalStatus[]{
                ReversalStatus.PENDING,
                ReversalStatus.PROCESSING,
                ReversalStatus.CONFIRMED,
                ReversalStatus.CANCELLED
        });
        return reversalRequest;
    }
}| | :- |

Consulta de Lotes via API

Esta é uma consulta via Content Provider que possibilita que outros aplicativos possam consultar informações sobre os lotes, sendo possível realizar filtros exclusivos e obter diversos dados dos lotes conforme objeto de retorno (vide Fechamento de lote).

Integração com Aplicação de Pagamentos via Content Provider

Só será permitido listar pagamentos feitos pela própria aplicação que está realizando a consulta.

Declare essa permissão no AndroidManifest.xml do seu Aplicativo para ter acesso ao Content Provider.

**

content://br.com.phoebus.android.payments.provider/periodBatch content://br.com.phoebus.android.payments.provider/batchNumber content://br.com.phoebus.android.payments.provider/currentBatch

URI (Uniform Resource Identifier) para obtenção de informações de lote.

Para realizar o request da consulta por período entre datas é necessário adicionar essa dependência.

implementation ‘com.jakewharton.threetenabp:threetenabp:1.0.3’

Filtros

BatchFilter

Retorno

O objeto de resposta é o List (vide Fechamento de lote).

| (informação) Info| | :-: |

Para facilitar o uso, são disponibilizadas classes de acesso ao provider:

● BatchProviderRequest

● BatchProviderApi

● BatchContract

EXEMPLO

|import androidx.appcompat.app.AppCompatActivity;import android.content.Intent;
import android.database.Cursor;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import android.widget.Toast;import com.jakewharton.threetenabp.AndroidThreeTen;import java.math.BigDecimal;import java.text.SimpleDateFormat;
import java.util.Arrays;

import java.util.Date;
import java.util.List;
import java.util.TimeZone;import br.com.phoebus.android.payments.api.ApplicationInfo;
import br.com.phoebus.android.payments.api.Credentials;import br.com.phoebus.android.payments.api.Payment;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.PaymentStatus;
import br.com.phoebus.android.payments.api.provider.PaymentContract;
import br.com.phoebus.android.payments.api.provider.PaymentProviderApi;
import br.com.phoebus.android.payments.api.provider.PaymentProviderRequest;public class MainActivity extends AppCompatActivity implements View.OnClickListener {    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();
        AndroidThreeTen.init(getApplication());
    }    @Override
    public void onClick(View view) {
        doExecute();
    }    public void doExecute() {
        //definindo as credenciais
        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”);        //criando objeto de request para o batch content provider
        BatchProviderRequest request = createRequest(applicationInfo);        //selecionando propriedades retornadas
        String[] columns = new String[]{
               BatchContract.column.batchData
        };        try {
            //solicitando a lista de lotes
            request.setColumns(columns);            List batchList = BatchProviderApi.create(this).findAll(request);            //********* Outra forma de realizar a consulta ******************************************
            // Cursor cursor = getApplicationContext().getContentResolver().query(request.getUriBuilder().build(), columns, null, null, null);
            // List batchList = SettleRequestResponseV2.fromCursor(cursor);
            //***************************************************************************************            Toast.makeText(this, batchList.size()+””, Toast.LENGTH_LONG).show();        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }
    }    private BatchProviderRequest createRequest(ApplicationInfo appInfo) {

        BatchProviderRequest batchRequest = new BatchProviderRequest();
        batchRequest.setApplicationInfo(appInfo);        //filtrando por período
        SimpleDateFormat isoFormat = new SimpleDateFormat(“yyyy-MM-dd’T’HH:mm:ss.SSS”);
        isoFormat.setTimeZone(TimeZone.getTimeZone(“UTC”));        try {
            batchRequest.setBatchFilter(BatchFilter.PERIOD_BATCH);
            Date dateStart = isoFormat.parse(“2020-04-06T00:00:00.000”);
            Date dateFinish =isoFormat.parse(“2020-04-06T23:59:59.000”);
            batchRequest.setStartDate(dateStart);
            batchRequest.setFinishDate(dateFinish);
        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }
        return batchRequest;
    }
}| | :- | —–

Consulta de Pagamentos via API

Usando esta API, é possível realizar todo o fluxo de pagamento, ou seja, a confirmação (ou o desfazimento). Além disso, pode-se informar uma lista de tipos de pagamentos (débito, crédito à vista, crédito parcelado, etc.) permitidos.

A seguir, temos a especificação detalhada das operações disponíveis.

Para integração com a API de pagamentos, é fornecida a interface PaymentClient.

Integração com Aplicação de Pagamentos via Content Provider

A integração via Content Provider possibilita que outros aplicativos possam consultar informações a respeito de pagamentos efetuados, sendo possível realizar filtros e obter diversos dados dos pagamentos, inclusive sua situação.

Só será permitido listar pagamentos feitos pela própria aplicação que está realizando a consulta.

Declare essa permissão no AndroidManifest.xml do seu Aplicativo para ter acesso ao Content Provider.

**

content://br.com.phoebus.android.payments.provider/payments

URI (Uniform Resource Identifier) para obtenção de informações de pagamentos.

Para realizar o request da consulta de pagamento por período entre datas é necessário adicionar essa dependência.

implementation ‘com.jakewharton.threetenabp:threetenabp:1.0.3’

Filtros

Retorno

Nome	Tipo	Descrição
id	String	Identificador da transação para a aplicação de pagamentos. Esta é a informação a ser usada para a confirmação e desfazimento.
value	BigDecimal	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.
paymentType	PaymentType	Tipo de pagamento (Débito, Crédito, Voucher, etc.).
installments	Integer	Quantidade de parcelas do pagamento.
acquirerName	String	Adquirente que autorizou o pagamento.
cardBrand	String	Bandeira do cartão.
cardBin	String	BIN do cartão.
cardPanLast4Digits	String	Últimos 4 dígitos do PAN do cartão.
captureType	CaptureType	Forma de captura do cartão.
status	PaymentStatus	Situação do pagamento.
date	Date	Data/hora do pagamento para a aplicação de pagamentos.
acquirerId	String	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.
acquirerResponseCode	String	Código de resposta da adquirente.
acquirerResponseDate	String	Data/hora retornada pela adquirente.
acquirerAuthorizationNumber	String	Número da autorização fornecido pela adquirente (consta no comprovante do cliente Portador do Cartão).
receiptClient	String	Conteúdo do comprovante - via do cliente.
receiptMerchant	String	Conteúdo do comprovante - via do estabelecimento.
additionalValueType	AdditionalValueType	Presente apenas quando existe um valor adicional no contexto da transação executada.
additionalValue	BigDecimal	Presente apenas quando existe um valor adicional no contexto da transação executada.
accountTypeId	String	Presente apenas quando existe um tipo de conta no contexto da transação executada.
planId	String	Presente apenas quando existe um plano no contexto da transação executada.
productShortName	String	Identificador de produto, retorna apenas transações de um produto.
batchNumber	String	Número de lote.
nsuTerminal	String	NSU gerado pelo terminal para a transação.
cardholderName	String	Nome do cliente no cartão.
lastTrx	Boolean	Indica ‘true’ se é a última transação aprovada, e ‘falso’ caso contrário.
terminalId	String	Identificação do terminal.
originalValue	BigDecimal	Valor orginal da venda. Presente em pagamentos com QRCode, cujo beneficio foi aplicado ao valor da venda.
appTransactionId	String	Identificador de transação para o aplicativo de pagamento. Esta é a informação que será usada para confirmar e desfazer o pagamento.
acquirerNsu	String	NSU Adquirente para consulta e identificação de transações.

| (informação) Info| | :-: |

É possível customizar quais informações estarão presentes na resposta. Para isso, deve ser passado um array de Strings com as colunas desejadas para o método query() do Content Resolver. Caso use a API de acesso ao provider, pode utilizar o método setColumns() do PaymentProviderRequest.

| (informação) Info| | :-: |

Para facilitar o uso, são disponibilizadas classes de acesso ao provider:

● PaymentProviderRequest

● PaymentProviderApi

● PaymentContract

EXEMPLO

|import androidx.appcompat.app.AppCompatActivity;import android.content.Intent;
import android.database.Cursor;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import android.widget.Toast;import com.jakewharton.threetenabp.AndroidThreeTen;import java.math.BigDecimal;import java.text.SimpleDateFormat;
import java.util.Arrays;import java.util.Date;
import java.util.List;
import java.util.TimeZone;import br.com.phoebus.android.payments.api.ApplicationInfo;
import br.com.phoebus.android.payments.api.Credentials;import br.com.phoebus.android.payments.api.Payment;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.PaymentStatus;
import br.com.phoebus.android.payments.api.provider.PaymentContract;
import br.com.phoebus.android.payments.api.provider.PaymentProviderApi;
import br.com.phoebus.android.payments.api.provider.PaymentProviderRequest;public class MainActivity extends AppCompatActivity implements View.OnClickListener {    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();
        AndroidThreeTen.init(getApplication());
    }    @Override
    public void onClick(View view) {
        doExecute();
    }    public void doExecute() {
        //definindo as credenciais
        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”);        //criando objeto de request para o payment content provider
        PaymentProviderRequest request = createRequest(applicationInfo);        //selecionando propriedades retornadas
        String[] columns = new String[]{
                PaymentContract.column.ID,
                PaymentContract.column.VALUE,
                PaymentContract.column.PAYMENT_STATUS,
                PaymentContract.column.PAYMENT_DATE,
                PaymentContract.column.CARD_BRAND,
        };

        try {
            //solicitando a lista de pagamentos
            request.setColumns(columns);
            List paymentsList = PaymentProviderApi.create(this).findAll(request);
            //********* Outra forma de realizar a consulta ******************************************
            // Cursor cursor = getApplicationContext().getContentResolver().query(request.getUriBuilder().build(), columns, null, null, null);
            // List paymentsList = Payment.fromCursor(cursor);
            //***************************************************************************************            Toast.makeText(this, paymentsList.size()+””, Toast.LENGTH_LONG).show();        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }
    }    private PaymentProviderRequest createRequest(ApplicationInfo appInfo) {        PaymentProviderRequest paymentRequest = new PaymentProviderRequest();
        paymentRequest.setApplicationInfo(appInfo);        //filtrando pelo paymentId
        paymentRequest.setPaymentId(“000000000”);        //filtrando por período
        SimpleDateFormat isoFormat = new SimpleDateFormat(“yyyy-MM-dd’T’HH:mm:ss.SSS”);
        isoFormat.setTimeZone(TimeZone.getTimeZone(“UTC”));        try {
            Date dateStart = isoFormat.parse(“2020-04-06T00:00:00.000”);
           Date dateFinish =isoFormat.parse(“2020-04-06T23:59:59.000”);
            paymentRequest.setStartDate(dateStart);
            paymentRequest.setFinishDate(dateFinish);
        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }        //filtrando por faixa de valores de pagamento
        paymentRequest.setStartValue(new BigDecimal(“0.00”));
        paymentRequest.setFinishValue(new BigDecimal(“1000.00”));        //filtrando pelos 4 últimos dígitos do cartão
        paymentRequest.setLastDigits(“9636”);        //filtrando pelos 4 últimos dígitos do cartão
        List status = Arrays.asList(new PaymentStatus[]{
                PaymentStatus.PENDING,
                PaymentStatus.CONFIRMED,
                PaymentStatus.CANCELLED,
                PaymentStatus.REVERSED
        });
        return paymentRequest;
    }
}| | :- | —–

Consulta de Pagamentos V2 via API

Esta é uma consulta via Content Provider que possibilita que outros aplicativos possam consultar informações sobre os pagamentos efetuados, sendo possível realizar filtros e obter diversos dados dos pagamentos, inclusive sua situação.

Integração com Aplicação de Pagamentos via Content Provider

Só será permitido listar pagamentos feitos pela própria aplicação que está realizando a consulta.

Declare essa permissão no AndroidManifest.xml do seu Aplicativo para ter acesso ao Content Provider.

**

content://br.com.phoebus.android.payments.provider/payments/transactions

URI (Uniform Resource Identifier) para obtenção de informações de pagamentos.

Para realizar o request da consulta de pagamento por período entre datas é necessário adicionar essa dependência.

implementation ‘com.jakewharton.threetenabp:threetenabp:1.0.3’

Parâmetros de entrada

Filtros

Retorno

A consulta de pagamentos, retorna os pagamentos que obedecerem aos filtros informados, e os estornos associados a eles (inclusive estornos negados).

Os filtros informados são aplicados apenas aos campos dos pagamentos.

A lista de pagamentos retornados deve estar ordenada de forma ascendente pelo campo date do pagamento.

Em cada pagamento, a lista de estornos retornados deve estar ordenada de forma ascendente pelo campo date do estorno. Não retorna devoluções não referenciadas.

EXEMPLO DE RETORNO QUANDO DOIS PAGAMENTOS OBEDECEM AOS CRÍTERIOS INFORMADOS

As estruturas “payment” e “reversals” são as mesmas usadas na consulta de última transação aprovada e confirmada;

|[
{
    “payment”: {
       …
    },
    “reversals”: [
      {
         …
      },
      {
         …
      },
      {
         …
      }
    ]
},
{
    “payment”: {
        …
    },
    “reversals”: [
      {
         …
      },
      {
         …
      },
      {
         …
      }
    ]
}
]| | :- |

| (informação) Info| | :-: |

Para facilitar o uso, são disponibilizadas classes de acesso ao provider:

● PaymentProviderRequest

● PaymentProviderApi

● PaymentContract

EXEMPLO

|import androidx.appcompat.app.AppCompatActivity;import android.content.Intent;
import android.database.Cursor;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import android.widget.Toast;import com.jakewharton.threetenabp.AndroidThreeTen;import java.math.BigDecimal;import java.text.SimpleDateFormat;
import java.util.Arrays;

import java.util.Date;
import java.util.List;
import java.util.TimeZone;import br.com.phoebus.android.payments.api.ApplicationInfo;
import br.com.phoebus.android.payments.api.Credentials;import br.com.phoebus.android.payments.api.Payment;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.PaymentStatus;
import br.com.phoebus.android.payments.api.provider.PaymentContract;
import br.com.phoebus.android.payments.api.provider.PaymentProviderApi;
import br.com.phoebus.android.payments.api.provider.PaymentProviderRequest;public class MainActivity extends AppCompatActivity implements View.OnClickListener {

    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();
        AndroidThreeTen.init(getApplication());
    }    @Override
    public void onClick(View view) {
        doExecute();
    }
    public void doExecute() {
        //definindo as credenciais
        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”);

       //criando objeto de request para o payment content provider
        PaymentProviderRequest request = createRequest(applicationInfo);        //selecionando propriedades retornadas
        String[] columns = new String[]{
                PaymentContract.column.ID,
                PaymentContract.column.VALUE,
                PaymentContract.column.PAYMENT_STATUS,
                PaymentContract.column.PAYMENT_DATE,
                PaymentContract.column.CARD_BRAND,
        };        try {
            //solicitando a lista de pagamentos
            request.setColumns(columns);
            List paymentsList = PaymentProviderApi.create(this).findAllTransactions(request);
            //********* Outra forma de realizar a consulta ******************************************
            // Cursor cursor = getApplicationContext().getContentResolver().query(request.getUriBuilder().build(), columns, null, null, null);
            // List paymentsList = Payment.fromCursor(cursor);
            //***************************************************************************************            Toast.makeText(this, paymentsList.size()+””, Toast.LENGTH_LONG).show();
        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }
    }    private PaymentProviderRequest createRequest(ApplicationInfo appInfo) {
        PaymentProviderRequest paymentRequest = new PaymentProviderRequest();
        paymentRequest.setApplicationInfo(appInfo);

        //filtrando pelo paymentId
        paymentRequest.setPaymentId(“000000000”);        //filtrando por período
        SimpleDateFormat isoFormat = new SimpleDateFormat(“yyyy-MM-dd’T’HH:mm:ss.SSS”);
        isoFormat.setTimeZone(TimeZone.getTimeZone(“UTC”));        try {
            Date dateStart = isoFormat.parse(“2020-04-06T00:00:00.000”);
            Date dateFinish =isoFormat.parse(“2020-04-06T23:59:59.000”);
            paymentRequest.setStartDate(dateStart);
            paymentRequest.setFinishDate(dateFinish);
        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }

        //filtrando por faixa de valores de pagamento
       paymentRequest.setStartValue(new BigDecimal(“0.00”));
        paymentRequest.setFinishValue(new BigDecimal(“1000.00”));        //filtrando pelos 4 últimos dígitos do cartão
        paymentRequest.setLastDigits(“9636”);        //filtrando pelos 4 últimos dígitos do cartão
        List status = Arrays.asList(new PaymentStatus[]{
                PaymentStatus.PENDING,
                PaymentStatus.CONFIRMED,
                PaymentStatus.CANCELLED,
                PaymentStatus.REVERSED
        });
        return paymentRequest;
    }
}| | :- | —–

Consulta da Última transação aprovada via API

Esta é uma consulta via Content Provider que possibilita que outros aplicativos possam consultar informações sobre a última transação aprovada.

A última transação confirmada pode ser um pagamento, um estorno ou uma devolução não referenciada. Não possui filtros. Retorna a estrutura completa de pagamentos + estornos (aprovados ou negados). Pode retornar vazia se não houver transações aprovadas no terminal.

Integração com Aplicação de Pagamentos via Content Provider

Só será permitido listar pagamentos feitos pela própria aplicação que está realizando a consulta.

Declare essa permissão no AndroidManifest.xml do seu Aplicativo para ter acesso ao Content Provider.

content://br.com.phoebus.android.payments.provider/payments/lastTransactions

URI (Uniform Resource Identifier) para obtenção de informações da última transação aprovada.

Para realizar o request da consulta por período entre datas é necessário adicionar essa dependência.

implementation ‘com.jakewharton.threetenabp:threetenabp:1.0.3’

Parâmetros de entrada

Estrutura Retornada

● Quando a Última transação aprovada é um pagamento, é retornado o objeto de pagamento e a lista de todos os estornos associados a ele;

● Quando a Última transação aprovada é um estorno, é retornado o objeto de estorno, o pagamento associado a esse estorno, e, caso existam, outros estornos associados ao mesmo pagamento;

● Quando a Última transação aprovada é uma devolução não referenciada, é retornado o objeto Refund.

A estrutura retornada segue conforme os exemplos abaixo:

Exemplo quando a última transação é um pagamento

Todos Campos de retorno dos objetos estão disponíveis na estrutura retornada. O último pagamento confirmado será identificado através do campo “lastTrx”: true.

|{
   “payment”:{
      “id”:””,
      “value”:50,
      “captureType”:”MANUAL”,
      “status”:”CONFIRMED”,
      “date”:”01/06/2023 10:45”,
      “nsuTerminal”:123,
      “lastTrx”:true
        …
   },
   “reversals”:[
      {
         …
      }
   ]
}| | :- |

Exemplo quando a última transação é um estorno

Todos Campos de retorno dos objetos estão disponíveis na estrutura retornada.

O último estorno confirmado será identificado através do campo “lastTrx”: true.

|{
   “payment”:{
      …
   },
   “reversals”:[
      {
         “paymentId”:””,
         “value”:50,
         “captureType”:”MANUAL”,
         “status”:”CONFIRMED”,
         “date”:”01/06/2023 10:45”,
         “lastTrx”:true
         …
      }
   ]
}| | :- |

Exemplo quando a última transação é uma devolução não referenciada

Todos Campos de retorno dos objetos estão disponíveis na estrutura retornada.

A último Devolução não referenciada confirmado será identificado através do campo “lastTrx”: true.

|{
   “refund”:{
      “id”:””,
      “value”:50,
      “captureType”:”MANUAL”,
      “status”:”CONFIRMED”,
      “date”:”01/06/2023 10:45”,
      “nsuTerminal”:123,
      “lastTrx”:true,
       …
   }
}| | :- |

| (informação) Info| | :-: |

Para facilitar o uso, são disponibilizadas classes de acesso ao provider:

● PaymentProviderApi

EXEMPLO

Consultar Informações do Terminal

A PayStore também disponibiliza um recurso para consultar as informações de um determinado ponto de venda (POS), como id do terminal, id do lojista, entre outros.

A classe TerminalInfoContract é responsável por prover essas informações.

Retorno

Segue, abaixo, um exemplo de sua implementação:

|package com.myapplication.controller;import android.content.ContentResolver;
import android.content.Context;
import android.database.Cursor;
import android.net.Uri;import br.com.phoebus.android.payments.api.provider.TerminalInfoContract;public class TerminalInfoController {
    private Context context;
   public TerminalInfoController(Context context) {
        this.context = context;
    }    public TerminalInfo getTerminalInfo() {
        Uri.Builder uriBuilder = TerminalInfoContract.getUriBuilder();
        ContentResolver resolver = context.getContentResolver();        try {
            Cursor query = resolver.query(uriBuilder.build(), null, null, null, null);
            if (query != null && query.moveToFirst()) {
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MERCHANT_ID)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MERCHANT_NAME)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MERCHANT_COMMERCIAL_NAME)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.NATIONAL_ID)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.TERMINAL_ID)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MC_POSTAL_CODE)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MC_STREET)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MC_CITY)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MC_STATE)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MC_STATE_ABBREVIATION)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MC_COUNTRY)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MC_COMPLEMENT)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MC_NEIGHBOURHOOD)));
              Log.d(query.getString(query.getColumnIndex(TerminalInfoContract.column.MC_ADDRESS_NUMBER)));
              query.close();
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        return terminalInfo;
    }
}| | :- | —–

Consultar Campos Adicionais da PayStore

A PayStore utiliza um poderoso recurso de passagem de parâmetros cadastrados no Servidor para serem utilizados pelos terminais, sem que seja necessário alterar a mensageria de Inicialização. Isso traz uma enorme flexibilidade para criação de novas funcionalidades nos apps.

Os Campos Adicionais (também chamados de Parâmetros) são informações que podem ser cadastradas no Portal da PayStore, podendo ser configurados para todos os lojistas e terminais do Facilitador, para um grupo de lojistas específico, para um lojista (afeta todos os terminais daquele lojista) ou para um terminal específico. Essas informações podem ser lidas por um aplicativo através de Providers.

A classe ConfigurationStoreContract é responsável por prover essas informações. Segue, abaixo, um exemplo de sua implementação:

|import android.content.ContentResolver;
import android.content.Context;
import android.database.Cursor;
import android.net.Uri;import br.com.phoebus.android.payments.api.provider.ConfigurationStoreContract;public class ConfigController { private Context context;
public ConfigController(Context context) {
    this.context = context;
} public String getProperty(String key) {    Uri.Builder uriBuilder = ConfigurationStoreContract.getUriBuilder();
    uriBuilder.appendQueryParameter(ConfigurationStoreContract.column.KEY, key);
    ContentResolver resolver = this.context.getContentResolver();    String value = null;
    try (Cursor query = resolver.query(uriBuilder.build(), null, null, null, null)) {      if (query != null && query.moveToFirst()) {
        value = query.getString(query.getColumnIndex(ConfigurationStoreContract.column.VALUE));
      }
    }
    return value;
}
}| | :- |

Para utilizar essa classe, basta usar a chave definida previamente nos Campos Adicionais como parâmetro, conforme abaixo:

|ConfigController config = new ConfigController(mContext);
String conteudoCampoAdicional = config.getProperty(“sua_chave”);| | :-: | —–

Broadcast

Integração com Aplicação de Pagamentos via Broadcast

Diferente das outras integrações, na integração via broadcast, outras aplicações podem receber notificações de que um pagamento ou um estorno foi efetuado. Esta informação é enviada pela aplicação de pagamentos via Broadcasts que podem ser recebidos por quaisquer aplicações que tenham interesse em saber da ocorrência de pagamentos ou estornos.

Actions

|Action|Extra| | :- | :- | |Intents.action.ACTION_AFTER_PAYMENT (br.com.phoebus.android.payments.AFTER_PAYMENT_FINISHED)|Intents.extra.EXTRA_PAYMENT_RETURN: Payment (vide startPaymentV2() ou documentação da classe.)| |Intents.action.ACTION_AFTER_REVERSAL (br.com.phoebus.android.payments.AFTER_PAYMENT_REVERSAL_FINISHED)|Intents.extra.EXTRA_PAYMENT_RETURN: ReversePayment (vide reversePaymentV2() ou documentação da classe.)| |Intents.action.ACTION_AFTER_SETTLEMENT (br.com.phoebus.android.payments.ACTION_AFTER_SETTLEMENT)|Intents.extra.EXTRA_SETTLEMENT_RETURN : SettlementBroadcastResponse, EXTRA_SETTLEMENT_RETURN_V2 : SettlementBroadcastResponse (ou vide documentação da classe.)|

Exemplo

|public class MyBroadcastReceiver extends BroadcastReceiver {    @Override
    public void onReceive(Context context, Intent intent) {
        if (intent.getAction().equals(Intents.action.ACTION_AFTER_PAYMENT)) {
            Payment payment = DataUtils.fromBundle(Payment.class, intent.getExtras(), Intents.extra.EXTRA_PAYMENT_RETURN);            // Do something!        } else if (intent.getAction().equals(Intents.action.ACTION_AFTER_REVERSAL)) {
            ReversePayment reversePayment = DataUtils.fromBundle(ReversePayment.class, intent.getExtras(), Intents.extra.EXTRA_PAYMENT_RETURN);

            // Do something!        } else if (intent.getAction().equals(Intents.action.ACTION_AFTER_SETTLEMENT)) {
            SettlementBroadcastResponse settlementBroadcastResponse = DataUtils.fromBundle(SettlementBroadcastResponse.class, intent.getExtras(), Intents.extra.EXTRA_SETTLEMENT_RETURN);
            SettlementBroadcastResponseV2 settlementBroadcastResponseV2 = SettlementBroadcastResponseV2.fromBundle(intent.getBundleExtra(Intents.extra.EXTRA_SETTLEMENT_RETURN_V2));

            // Do something!
        }
    }
}| | :- | —–

Resposta Broadcast Fechamento de Lote

Nome	Tipo	Obrigatório	Descrição
succeeded	Boolean	Sim	Indica se houve êxito no fechamento de lote. Onde retorna false se houve erro no fechamento de lote e true se obteve sucesso no mesmo.
response	SettleRequestResponse (DEPRECATED)	Não	Objeto de resposta para casos de sucesso no fechamento de lote. Note que em casos de erro, o mesmo não será retornado. (vide closeBatch() ou documentação da classe.)
responseV2	SettleRequestResponseV2	Não	Objeto de resposta para casos de sucesso no fechamento de lote. Note que em casos de erro, o mesmo não será retornado. (vide closeBatch() ou documentação da classe.)
error	ErrorData	Não	Objeto de resposta para casos de erro no fechamento de lote. Note que em casos de sucesso, o mesmo não será retornado. (vide closeBatch() ou documentação da classe.)

Resposta Broadcast de Erros

Toda vez que ocorrer um erro no terminal o SDK Android envia um broadcast com as informações, o APP Diagnóstico processa e envia para o backend. O acesso a esses dados será realizado pelo servico de mensagens kafka pelo Tópico terminal-errors. Os endereços de brokers pode variar entre os ambientes, solicitar url para setor de operações.

Parâmetros

Nome	Tipo	Obrigatório	Descrição	Tamanho máximo dos campos
paymentsAppVersion	String	Sim	Versão do app suite de pagamentos.	10 Caracteres
timestamp	Date	Sim	Data e hora do erro.
errorType	ErrorType	Sim	Tipo de erro (ErrorType).
serial	string	Sim	Número de serie do terminal.
errorCode	String	Não	Código de erro (prefixo + identificador).	6 Caracteres
errorMessage	String	Não	Mensagem do erro.	255 Caracteres
breadcrumbs	String	Não	Caminho de ações acionadas pelo usuário da tela inicial até o momento do erro.	4096 Caracteres
subAcquirerId	String	Não	Código do facilitador Paystore ao qual o terminal está associado.	32 Caracteres
merchantPaystore	String	Não	Lojista na PayStore.	32 Caracteres
terminalID	String	Não	Número lógico do terminal.	8 Caracteres
bCReturnCode	String	Não	Código de erro da BC.	4 Caracteres
stackTrace	String	Não	Lista as chamadas de método que levam ao lançamento da exceção, junto com os nomes de arquivo e números de linha em que as chamadas ocorreram.	255 Caracteres
bcCommands	List	Não	Lista os Comandos da BC.
bin	String	Não	BIN do cartão.	6 Caracteres
aid	String	Não	Identificador da Aplicação do Cartão.	32 Caracteres
value	BigDecimal	Não	Valor da transação.
installments	Integer	Não	Quantidade de parcelas do pagamento.
captureType	CaptureType	Não	Forma de captura do cartão.
cardServiceCode	String	Não	Código de Serviço do Cartão.
productId	Integer	Não	Identificador do produto.
paymentType	PaymentType	Não	Tipo de pagamento (Débito, Crédito, Voucher, etc.).
ticketNumber	String	Não	Número do cupom gerado pelo terminal para a transação.	4 Caracteres
batchNumber	String	Não	Número do lote.	3 Caracteres
endpoint	String	Não	Último endpoint utilizado pelo terminal antes do erro ocorrer.	2048 Caracteres
sdkMethod	String	Não	Método do SDK utilizado quando o erro ocorreu.	255 Caracteres
applicationName	String	Não	Nome da aplicação que usou o SDK.	255 Caracteres
httpStatusCode	String	Não	Código de erro HTTP.	3 Caracteres
transactionUuid	String	Não	UUID da transação.	36 Caracteres
devicdeName	String	Não	Modelo terminal.
lastBootDate	String	Não	Hora (timestamp) em que o terminal foi ligado.
batteryLevel	String	Não	Nível atual da bateria.
connectionType	String	Não	Tipo de conexão com a internet.
wifiLevel	String	Não	Intensidade do sinal Wi-fi.
isCharging	boolean	Não	Informa se o disponsitivo esta conectado e carregando.
osVersion	String	Não	Versão do sistema operacional.
kernelVersion	String	Não	Versão do kernel.

ErrorType

Código	Nome	Descrição
1	SCREEN_ERROR	Erros de tela
2	FATAL_EXCEPTION	FatalException
3	COMM_SERVER_ERROR	Falhas de comunicação ou servidor

BCCommandType

Código	Nome	Descrição
1	GET_CARD	Retorno do método getCard da BC
2	GO_ON_CHIP	Retorno do método getOnChip da BC
3	FINISH_CHIP	Retorno do método finishChip da BC

BCCommand

Nome	Tipo	Obrigatório	Descrição	Tamanho Máximo dos campos
type	BCCommandType	Não	Tipo de comando (getCard, goOnChip ou finishChip) da BC.
input	String	Não	Entrada do comando (getCard, goOnChip ou finishChip) da BC.	2048 Caracteres
output	String	Não	Saída do comando (getCard, goOnChip ou finishChip) da BC.	-

Realizar Inicialização

Inicia o processo de inicialização com a PayStore e com a Adquirente

Esse método deve ser chamado para fazer a inicialização do terminal com a Paystore e com a(s) adquirente(s) instalada(s).

Métodos

Assinatura	Descrição
void startInitialization(String activityAction, PaymentCallback paymentCallback)	Inicia o processo de inicialização com a Paystore e com a Adquirente.
void startInitialization(InitializationRequest initializationRequest, PaymentCallback paymentCallback)	Inicia o processo de inicialização com a Paystore e com a Adquirente, utilizando InitializationRequest.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
activityAction	String	Sim	Action da activity da aplicação externa que deve ser chamada após a inicialização ser concluída.
callback	PaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro.
initializationRequest	InitializationRequest	Sim	Objeto de transferência de dados que conterá as informações da requisição da inicialização.
paymentCallback	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.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.

request (InitializationRequest)

Exemplo

|public class MyActivity extends Activity implements PaymentClient.PaymentCallback {    private PaymentClient paymentClient;
    private String action = “br.com.phoebus.payments.demo.ACTION_INITIALIZE”;    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment);
        paymentClient = new PaymentClientImpl();
    }    @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(){
        InitializationRequest request = new InitializationRequest();
        request.setInstallToken(“1a2b3cdef”);
        request.setActivityAction(“123456abcde”);

        ApplicationInfo appInfo = new ApplicationInfo();
        appInfo.setCredentials(new Credentials(“demo-app”, “TOKEN-KEY-DEMO”));
        appInfo.setSoftwareVersion(“1.0.0.0”);

        try {
            paymentClient.startInitialization(request, this);
        } catch (ClientException e) {
            Log.e(TAG, “Error while initialization.”, e);
        }
    }    @Override
    public void onError(ErrorData errorData) {
        Log.e(TAG, “Error: “ + errorData.getResponseMessage());
    }    @Override
    public void onSuccess(Object data) {
        Log.i(TAG, “Success!”);
    }
}| | :- | —–

Enviar Pagamentos

Faz o envio dos pagamentos para a Paystore

Esse método deve ser chamado para enviar os pagamentos do terminal para a Paystore.

Métodos

Assinatura	Descrição
void startPushPayments(PaymentCallback paymentCallback)	Faz o envio dos pagamentos para a Paystore.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
callback	PaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro.

Detalhe dos parâmetros

callback

Exemplo

|public class MyActivity extends Activity implements PaymentClient.PaymentCallback {    private PaymentClient paymentClient;    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment);
        paymentClient = new PaymentClientImpl();
    }    @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(){
        ApplicationInfo appInfo = new ApplicationInfo();
        appInfo.setCredentials(new Credentials(“demo-app”, “TOKEN-KEY-DEMO”));
        appInfo.setSoftwareVersion(“1.0.0.0”);

       try {
            paymentClient.startPushPayments(this);
        } catch (ClientException e) {
            Log.e(TAG, “Error while sending payments to Paystore.”, e);
        }
    }    @Override
    public void onError(ErrorData errorData) {
        Log.e(TAG, “Error: “ + errorData.getResponseMessage());
    }    @Override
    public void onSuccess(Object data) {
        Log.i(TAG, “Success!”);
    }
}| | :- | —– **Checagem de Notificações

Verifica se há notificações na Paystore.**

Esse método deve ser chamado para checar se há alguma notificação pendente da Paystore para o terminal.

Métodos

Assinatura	Descrição
void getNotifications(PaymentCallback paymentCallback)	Verifica se há notificações na Paystore.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
callback	PaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro.

Detalhe dos parâmetros

callback

Exemplo

|public class MyActivity extends Activity implements PaymentClient.PaymentCallback {    private PaymentClient paymentClient;    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment);
        paymentClient = new PaymentClientImpl();
    }    @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(){
        ApplicationInfo appInfo = new ApplicationInfo();
        appInfo.setCredentials(new Credentials(“demo-app”, “TOKEN-KEY-DEMO”));
        appInfo.setSoftwareVersion(“1.0.0.0”);        try {
            paymentClient.getNotifications(this);
        } catch (ClientException e) {
            Log.e(TAG, “Error while checking notifications.”, e);
        }
    }    @Override
    public void onError(Object data) {
        Log.e(TAG, “Error: “ + errorData.getResponseMessage());
    }    @Override
    public void onSuccess(Object data) {
        Log.i(TAG, “Success!”);
    }
}| | :- | —– **Fechamento de Lote

[DEPRECATED] Sincroniza as transações e fecha o lote atual.**

Esse método deve ser chamado para executar o fechamento de lote e envio do mesmo.

Métodos

Assinatura	Descrição
void closeBatch(SettlementRequest settlementRequest, PaymentCallback paymentCallback)	Sincroniza as transações e fecha o lote atual.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	SettlementRequest	Sim	Objeto de transferência de dados que conterá as informações da requisição do fechamento de lote. 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 fechamento de lote.

Detalhe dos parâmetros request (SettlementRequest)

Nome	Tipo	Obrigatório	Descrição
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.
printMerchantReceipt	Boolean	Não	Indica se o comprovante do estabelecimento deve ser impresso ou não.

(DEPRECATED: Utilizar SettlementCallbackV2)

callback (SettlementCallback)

Exemplo

|public class MyActivity extends Activity implements PaymentClient.PaymentCallback {    private PaymentClient paymentClient;    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment);
        paymentClient = new PaymentClientImpl();
    }    @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(){
        ApplicationInfo appInfo = new ApplicationInfo();
        appInfo.setCredentials(new Credentials(“demo-app”, “TOKEN-KEY-DEMO”));
        appInfo.setSoftwareVersion(“1.0.0.0”);        SettlementRequest settlementRequest = new SettlementRequest();
        settlementRequest.setApplicationInfo(appInfo);
        settlementRequest.setPrintMerchantReceipt(true);        try {
            paymentClient.closeBatch(settlementRequest, this);
        } catch (ClientException e) {
            Log.e(TAG, “Error while closing batch.”, e);
        }
    }    @Override
    public void onError(ErrorData errorData) {
       Log.e(TAG, “Error: “ + errorData.getResponseMessage());
    }    @Override
    public void onSuccess(Settlement settlement) {
        Log.i(TAG, “Success!”);
    }
}| | :- | —–

Sincroniza as transações e fecha o lote atual.

Esse método deve ser chamado para executar o fechamento de lote e envio do mesmo.

Métodos

Assinatura	Descrição
void closeBatchV2(SettlementRequest settlementRequest, PaymentCallbackV2 paymentCallbackV2)	Sincroniza as transações e fecha o lote atual.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	SettlementRequest	Sim	Objeto de transferência de dados que conterá as informações da requisição do fechamento de lote. Note que nem todos os parâmetros são obrigatórios.
callback	PaymentCallbackV2	Sim	Interface que será executada para notificações de sucesso ou erro do processo de fechamento de lote.

Detalhe dos parâmetros request (SettlementRequest)

Nome	Tipo	Obrigatório	Descrição
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.
printMerchantReceipt	Boolean	Não	Indica se o comprovante do estabelecimento deve ser impresso ou não.

(Disponível a partir da versão(.aar) v3.1.4.0)

callback (SettlementCallbackV2)

BatchReport

BatchReportInfo

Exemplo

|public class MyActivity extends Activity implements PaymentClient.PaymentCallback {    private PaymentClient paymentClient;    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment);
        paymentClient = new PaymentClientImpl();
    }    @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(){
        ApplicationInfo appInfo = new ApplicationInfo();
        appInfo.setCredentials(new Credentials(“demo-app”, “TOKEN-KEY-DEMO”));
        appInfo.setSoftwareVersion(“1.0.0.0”);        SettlementRequest settlementRequest = new SettlementRequest();
        settlementRequest.setApplicationInfo(appInfo);
        settlementRequest.setPrintMerchantReceipt(true);        try {
            paymentClient.closeBatchV2(settlementRequest, this);
        } catch (ClientException e) {
            Log.e(TAG, “Error while closing batch.”, e);
        }
   }    @Override
    public void onError(ErrorDataV2 errorDataV2) {
        Log.e(TAG, “Error: “ + errorDataV2.getResponseMessage());
    }    @Override
    public void onSuccess(Settlement settlement) {
        Log.i(TAG, “Success!”);
    }
}| | :- | —–

Devolução não Referenciada

[DEPRECATED] Realiza o processo de devolução não referenciada.

Esse método deve ser chamado para executar a devolução não referenciada.

Métodos

Assinatura	Descrição
void refundPayment(RefundRequest settlementRequest, PaymentCallback paymentCallback)	Realiza o processo de devolução não referenciada. (DEPRECATED: Utilizar refundPaymentV2)

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	RefundRequest	Sim	Objeto de transferência de dados que conterá as informações da requisição da devolução não referenciada. 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 devolução.

Detalhe dos parâmetros request (RefundRequest) (DEPRECATED: Utilizar RefundRequestV2)

Nome	Tipo	Obrigatório	Descrição
value	BigDecimal	Não	Valor da devolução não referenciada. Caso não seja preenchido (null), ou seja preenchido com 0 (zero), o App de Pagamento deve solicitar o valor ao operador.
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	Não	Versão da aplicação que está solicitando o pagamento.
printMerchantReceipt	Boolean	Não	Indica se o comprovante do estabelecimento deve ser impresso ou não. O valor padrão é false, isto é, o comprovante não é impresso.
printCustomerReceipt	Boolean	Não	Indica se o comprovante do cliente deve ser impresso ou não. O valor padrão é false, isto é, o comprovante não é impresso.
productShortName	String	Não	Quando preenchido, após a leitura do cartão e identificação do produto de bandeira, caso não corresponda a productShortName do produto em questão, o terminal deve exibir um erro em tela e encerrar a transação. Exemplos: VI=VISA, MC=MASTERCARD, AX=AMEX
appTransactionId	String	Não	Identificador da transação integrada para o software. O Identificador referido é aquele utilizado na aplicação que originou a solicitação de devolução. Não deve se repetir.

callback (RefundCallback)

Exemplo

|public class MyActivity extends Activity implements PaymentClient.PaymentCallback {
    private PaymentClient paymentClient;    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment);
        paymentClient = new PaymentClientImpl();
    }    @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(){
        ApplicationInfo appInfo = new ApplicationInfo();
        appInfo.setCredentials(new Credentials(“demo-app”, “TOKEN-KEY-DEMO”));
        appInfo.setSoftwareVersion(“1.0.0.0”);

        RefundRequest refundRequest = new RefundRequest();
        refundRequest.setApplicationInfo(appInfo);
        refundRequest.setPrintMerchantReceipt(true);        try {
            paymentClient.refundPayment(refundRequest, this);
        } catch (ClientException e) {
            Log.e(TAG, “Error starting devolution”, e);
        }
    }    @Override
    public void onError(ErrorData errorData) {
        Log.e(TAG, “Error: “ + errorData.getResponseMessage());
   }    @Override
    public void onSuccess(Refund refund) {
        Log.i(TAG, “Success!”);
    }
}| | :- | —–

Realiza o processo de devolução não referenciada

Esse método deve ser chamado para executar a devolução não referenciada.

A partir da versão 3.1.5.0

Quando uma transação é feita, anteriormente, poderia ser confirmado realizando sua impressão (ou via printReceipt), ou ao realizar uma nova transação. Agora, o estorno também pode ser confirmado ao usar o novo parâmetro autoConfirm - indicando se deve ou não confirmar independente da impressão - ou utilizando o novo método confirmReversePayment().

Métodos

|Assinatura|Descrição| | :- | :- | |void refundPaymentV2(RefundRequestV2 settlementRequest, PaymentCallback paymentCallback)|Realiza o processo de devolução não referenciada.| |void confirmReversePayment(String paymentId, PaymentCallback paymentCallback)|Confirma uma autorização de devolução não autorizada realizada anteriormente.| |void cancelReversePayment(String paymentId, PaymentCallback paymentCallback)|Desfaz uma solicitação devolução não referenciada.|

refundPaymentV2()

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	RefundRequestV2	Sim	Objeto de transferência de dados que conterá as informações da requisição da devolução não referenciada. 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 devolução.

Detalhe dos parâmetros request (RefundRequestV2)

Nome	Tipo	Obrigatório	Descrição
value	BigDecimal	Não	Valor da devolução não referenciada. Caso não seja preenchido (null), ou seja preenchido com 0 (zero), o App de Pagamento deve solicitar o valor ao operador.O valor deverá ser formatado com duas casas decimais.
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	Não	Versão da aplicação que está solicitando o pagamento.
printMerchantReceipt	Boolean	Não	Indica se o comprovante do estabelecimento deve ser impresso ou não. O valor padrão é false, isto é, o comprovante não é impresso.
printCustomerReceipt	Boolean	Não	Indica se o comprovante do cliente deve ser impresso ou não. O valor padrão é false, isto é, o comprovante não é impresso.
productShortName	String	Não	Quando preenchido, após a leitura do cartão e identificação do produto de bandeira, caso não corresponda a productShortName do produto em questão, o terminal deve exibir um erro em tela e encerrar a transação. Exemplos: VI=VISA, MC=MASTERCARD, AX=AMEX
appTransactionId	String	Não	Identificador da transação integrada para o software. O Identificador referido é aquele utilizado na aplicação que originou a solicitação de devolução. Não deve se repetir.
previewMerchantReceipt	Boolean	Não	Indica se a tela de pré-visualização do comprovante do estabelecimento deve ser exibida após a confirmação da transação. O valor padrão é true, o que significa que o comprovante será exibido.
previewCustomerReceipt	Boolean	Não	Indica se a tela de pré-visualização do comprovante do cliente deve ser exibida após a confirmação da transação. O valor padrão é true, o que significa que o comprovante será exibido.
autoConfirm (v3.1.5.0)	Boolean	Não	Indica se a transação deve ser confirmada automaticamente.Valores possíveis:1. null (padrão) : confirma automaticamente caso ocorra a impressão do comprovante.2. true : confirma automaticamente independente da regra de impressão.3. false : não confirma automaticamente, ficando pendente aguardando confirmação.

callback (RefundCallback)

confirmReversePayment()

Este método deve ser chamado para confirmar uma devolução não referenciada que o terminal conseguiu processar completamente a perna de autorização enviada pelo Autorizador.

Este método não deve ser chamado para uma devolução não referenciada já confirmado, ou seja, em que já se executou o método confirmReversePayment() anteriormente.

Este método não deve ser chamado para uma devolução não referenciada já desfeito, ou seja, em que já se executou o método cancelReversePayment() anteriormente.

Este método não deve ser chamado para uma devolução não referenciada que foi negada pelo Autorizador, ou seja, a transação precisa ter sido autorizada pelo Autorizador.

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

cancelReversePayment()

Este método deve ser chamado para desfazer uma devolução não referenciada anteriormente autorizada. Esta transação deve não ter sido desfeita ainda e deve ter sido autorizada (não negada) previamente.

Como dito na descrição de reversePayment(), é possível que não haja desfazimento para uma devolução não referenciada para uma determinada adquirente. Assim, o método cancelReversePayment() pode retornar um erro específico informando que não é possível executar tal operação (vide Códigos de Resposta).

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

Exemplo

|public class MyActivity extends Activity implements PaymentClient.PaymentCallback {    private PaymentClient paymentClient;    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment);
        paymentClient = new PaymentClientImpl();
    }    @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(){
        ApplicationInfo appInfo = new ApplicationInfo();
        appInfo.setCredentials(new Credentials(“demo-app”, “TOKEN-KEY-DEMO”));
        appInfo.setSoftwareVersion(“1.0.0.0”);

        RefundRequestV2 refundRequestV2 = new RefundRequestV2();
       refundRequestV2.setApplicationInfo(appInfo);
        refundRequestV2.setPrintMerchantReceipt(true);        try {
           paymentClient.refundPaymentV2(refundRequestV2, this);
        } catch (ClientException e) {
            Log.e(TAG, “Error starting devolution”, e);
        }
    }    @Override
    public void onError(ErrorData errorData) {
        Log.e(TAG, “Error: “ + errorData.getResponseMessage());
    }    @Override
    public void onSuccess(Refund refund) {
        Log.i(TAG, “Success!”);
    }
}| | :- | —– **Devolução Referência sem Payment

Realiza o processo de anulação/devolução referenciada sem paymentId**

Esse método deve ser chamado para executar a anulação/devolução referenciada sem paymentId.

A partir da versão 3.1.5.0

Quando uma transação é feita, anteriormente, poderia ser confirmado realizando sua impressão (ou via printReceipt), ou ao realizar uma nova transação. Agora, o estorno também pode ser confirmado ao usar o novo parâmetro autoConfirm - indicando se deve ou não confirmar independente da impressão - ou utilizando o novo método confirmReversePayment().

Métodos

|Assinatura|Descrição| | :- | :- | |void reversePaymentWithFilter(ReversePaymentFilterRequest settlementRequest, PaymentCallback paymentCallback)|Realiza o processo de anulação/devolução referenciada sem paymentId.| |void confirmReversePayment(String paymentId, PaymentCallback paymentCallback)|Confirma uma autorização de estorno de pagamento realizada anteriormente.| |void cancelReversePayment(String paymentId, PaymentCallback paymentCallback)|Desfaz uma solicitação de estorno de pagamento.|

reversePaymentWithFilter()

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	ReversePaymentFilterRequest	Sim	Objeto de transferência de dados que conterá as informações da requisição da anulação/devolução referenciada sem paymentId. 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 anulação/devolução.

Detalhe dos parâmetros request (ReversePaymentFilterRequest)

Nome	Tipo	Obrigatório	Descrição
value	BigDecimal	Não	Valor da transação a ser devolvida. Caso não seja preenchido (null), ou seja preenchido com 0 (zero), o App de Pagamento deve solicitar o valor ao operador.
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.
printMerchantReceipt	Boolean	Não	Indica se o comprovante do estabelecimento deve ser impresso ou não. O valor padrão é false, isto é, o comprovante não é impresso.
printCustomerReceipt	Boolean	Não	Indica se o comprovante do cliente deve ser impresso ou não. O valor padrão é false, isto é, o comprovante não é impresso.
operationMethod	Integer	Não	Indica o método de operação (QR ou Card) usado para o pagamento original. Admita o seguintes valores: 0 - Apenas com cartão físico (ler ou datilografado); 1 - Somente com QRCode; Se não for relatado, modos de disponível no terminal capturar.
productShortName	String	Não	Quando preenchido, após a leitura do cartão e identificação do produto de bandeira, caso não corresponda a productShortName do produto em questão, o terminal deve exibir um erro em tela e encerrar a transação. Exemplos: VI=VISA, MC=MASTERCARD, AX=AMEX
ticketNumber	String	Não	Indica o número do cupom, após a transação de pagamento realizada com um cartão físico.
originalQRId	String	Não	Identificador QrCode gerado pelo terminal de captura. Quando a transação de pagamento é realizada através de Código QR
Payment.paymentDate	Date	Não	Indica a data/hora de pagamento para o App de Pagamentos. Quando a transação de pagamento não é conhecido pelo terminal de captura, ou seja, foi feito em outro terminal.
previewMerchantReceipt	Boolean	Não	Indica se a tela de pré-visualização do comprovante do estabelecimento deve ser exibida após a confirmação da transação. O valor padrão é true, o que significa que o comprovante será exibido.
previewCustomerReceipt	Boolean	Não	Indica se a tela de pré-visualização do comprovante do cliente deve ser exibida após a confirmação da transação. O valor padrão é true, o que significa que o comprovante será exibido.
autoConfirm (v3.1.5.0)	Boolean	Não	Indica se a transação deve ser confirmada automaticamente.Valores possíveis:1. null (padrão) : confirma automaticamente caso ocorra a impressão do comprovante.2. true : confirma automaticamente independente da regra de impressão.3. false : não confirma automaticamente, ficando pendente aguardando confirmação.

callback

confirmReversePayment()

Este método deve ser chamado para confirmar um estorno que o terminal conseguiu processar completamente a perna de autorização enviada pelo Autorizador.

Este método não deve ser chamado para um estorno já confirmado, ou seja, em que já se executou o método confirmReversePayment() anteriormente.

Este método não deve ser chamado para um estorno já desfeito, ou seja, em que já se executou o método cancelReversePayment() anteriormente.

Este método não deve ser chamado para um estorno que foi negada pelo Autorizador, ou seja, a transação precisa ter sido autorizada pelo Autorizador.

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

cancelReversePayment()

Como dito na descrição de reversePayment(), é possível que não haja desfazimento para a transação de estorno para uma determinada adquirente. Assim, o método cancelReversePayment() pode retornar um erro específico informando que não é possível executar tal operação (vide Códigos de Resposta).

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

Exemplo

|public class MyActivity extends Activity implements PaymentClient.PaymentCallback {
    private PaymentClient paymentClient;    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment);
        paymentClient = new PaymentClientImpl();
    }    @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(){
        ApplicationInfo appInfo = new ApplicationInfo();
        appInfo.setCredentials(new Credentials(“demo-app”, “TOKEN-KEY-DEMO”));
        appInfo.setSoftwareVersion(“1.0.0.0”);

        ReversePaymentFilterRequest request = new ReversePaymentFilterRequest();
        request.setApplicationInfo(appInfo);
        request.setPrintMerchantReceipt(true);        try {
            paymentClient.reversePaymentWithFilter(request, this);
        } catch (ClientException e) {
            Log.e(TAG, “Error starting devolution”, e);
        }
    }   @Override
    public void onError(ErrorData errorData) {
        Log.e(TAG, “Error: “ + errorData.getResponseMessage());
    }    @Override
    public void onSuccess(Refund refund) {
        Log.i(TAG, “Success!”);
    }
}| | :- | —–

Reimpressão

reprint()

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	ReprintRequest	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.

Detalle de los Parámetros

request (ReprintRequest)

Nome	Tipo	Obrigatório	Descrição
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.
ticketNumber	String	Não	Número do cupom. Se não for informado, será considerado o comprovante do último pagamento autorizado.
Payment.paymentDate	Date	Não	Data/hora do pagamento para a aplicação de pagamentos.Se não for informado, será considerado o comprovante do último pagamento autorizado.

callback (PaymentCallback)

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.

Impressão de comprovante

printReceipt()

Esse método deve ser chamado para realizar impressão do comprovante quando a transação for confirmada. Uma vez solicitado a impressão do comprovante com sucesso, só é permitido reimpressão.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	PrintReceiptRequest	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 (PrintReceiptRequest)

Nome	Tipo	Obrigatório	Descrição
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.
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.
printMerchantReceipt	Boolean	Não	Indica se o comprovante do estabelecimento deve ser impresso ou não.
printCustomerReceipt	Boolean	Não	Indica se o comprovante do cliente deve ser impresso ou não.
previewMerchantReceipt	Boolean	Não	Indica se a tela de pré-visualização do comprovante do estabelecimento deve ser exibida após a confirmação da transação. O valor padrão é true, o que significa que o comprovante será exibido.
previewCustomerReceipt	Boolean	Não	Indica se a tela de pré-visualização do comprovante do cliente deve ser exibida após a confirmação da transação. O valor padrão é true, o que significa que o comprovante será exibido.

callback (PaymentCallback)

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.
ErrorData.acquirerAdditionalMessage	String	Não	Mensagem adicional enviada pela adquirente na resposta da transação.

Códigos de Resposta da Integração

Extração de Dados

Esse método deve ser chamado para fazer a extração dos dados do Payments e das adquirentes sendo utilizadas e enviá-los para a AWS (Amazon Web Services).

Parâmetros

Nome	Tipo	Obrigatório	Descrição
callback	PaymentCallBack	Sim	Interface que será executada para notificações de sucesso ou erro.

Detalhe dos parâmetros

callback

Exemplo

|public class MyActivity extends Activity implements PaymentClient.PaymentCallback {    private PaymentClient paymentClient;    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment);
        paymentClient = new PaymentClientImpl();
    }    @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(){
        ApplicationInfo appInfo = new ApplciationInfo();
        appInfo.setCredentials(new Credentials(“demo-app”, “TOKEN-KEY-DEMO”));
        appInfo.setSoftwareVersion(“1.0.0.0”);

        try {
            paymentClient.startExtraction(this);
        } catch (ClientException e) {
            Log.e(TAG, “Error while uploading data.”, e);
        }
    }    @Override
    public void onError(Object data) {
        Log.e(TAG, “Error: “ + errorData.getResponseMessage());
    }    @Override
    public void onSuccess(Object data) {
        Log.i(TAG, “Success!”);
    }
}| | :- | —–

Echo Test

Inicia o processo para realizar os testes de comunicação

Esse método deve ser chamado quando se deseja realizar testes de comunicação com os servidores que o terminal se comunica. Ao fim da execução será retornado o objeto EchoTestResults, contendo informações de cada teste executado.

Métodos

Assinatura	Descrição
void startEchoTest(PaymentCallback paymentCallback)	Inicia o processo para realizar os testes de comunicação.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
callback	PaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro.

Detalhe dos parâmetros

callback

Exemplo

|public class MyActivity extends Activity implements PaymentClient.PaymentCallback {
    private PaymentClient paymentClient;    @Override
    protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_payment);
        paymentClient = new PaymentClientImpl();
    }    @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(){
        ApplicationInfo appInfo = new ApplicationInfo();
        appInfo.setCredentials(new Credentials(“demo-app”, “TOKEN-KEY-DEMO”));
        appInfo.setSoftwareVersion(“1.0.0.0”);

        try {
            paymentClient.startEchoTest(this);
        } catch (ClientException e) {
            Log.e(TAG, “Error while doing the test”, e);
        }
    }    @Override
    public void onError(Object data) {
        Log.e(TAG, “Error: “ + errorData.getResponseMessage());
    }    @Override
    public void onSuccess(Object data) {
        CommTestResults results = (CommTestResults) data;
        Log.i(TAG, results.toString());
    }
}| | :- |

Retorno

ACQUIRERCOMMTESTRESULTS

COMMTESTSTATUS

Nome	Descrição
NONE	Não há comunicação.
ONLINE	Comunicação está Online.
OFFLINE	Comunicação está Offline

Customizar a aplicação principal

Através dessa opção o Facilitador pode definir seu apk como principal. Assim que o terminal for ligado a aplicação configurada será chamada ao invés da aplicação padrão de pagamento PayStore.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
packageName	String	Sim	Nome do pacote da aplicação
callback	PaymentCallBack	Sim	Interface que será executada para notificações de sucesso ou erro.

Detalhe dos parâmetros

callback

Exemplo

|import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;
import android.view.View;
import android.widget.EditText;
import android.widget.Toast;import br.com.phoebus.android.payments.api.ErrorData;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.exception.ClientException;public class SetMainAppActivity extends AppCompatActivity {
    private PaymentClient paymentClient;
    private EditText packageNameEdt;    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        this.setTitle(R.string.setMainApp);
        setContentView(R.layout.activity_set_main_app);        this.packageNameEdt = ((EditText) this.findViewById(R.id.packageNameEdt));
        this.packageNameEdt.setText(“br.com.phoebus.payments.demo”);
      this.paymentClient = new PaymentClient();
        this.paymentClient.bind(this.getApplicationContext());
    }    public void doSetMainApp(View view) {
        if (!isDataValid()) return;        try {
            this.paymentClient.setMainApp(packageNameEdt.getText().toString(), new PaymentClient.PaymentCallback() {                @Override
                public void onSuccess(Object data) {
                    Toast.makeText(SetMainAppActivity.this, “App principal definido!”, Toast.LENGTH_SHORT).show();
                }                @Override
                public void onError(ErrorData errorData) {
                    Toast.makeText(SetMainAppActivity.this, “Erro ao definir app principal: “ + errorData.getPaymentsResponseCode() +
                            ” = “ + errorData.getResponseMessage(), Toast.LENGTH_LONG).show();
                }
            });
        } catch (ClientException e) {
            e.printStackTrace();
            Toast.makeText(SetMainAppActivity.this, “Falha na chamada do serviço: “ + e.getMessage(), Toast.LENGTH_LONG).show();
        }
    }

    private boolean isDataValid() {
        boolean ret = true;
        if (““.equals(this.packageNameEdt.getText().toString())) {
            this.packageNameEdt.setError(getString(R.string.requieredFieldError));
            ret = false;
       }
        return ret;
    }
}| | :- | —–

Resolução de Pendências QRCode (Pagamento Específico)

[DEPRECATED] Realiza o processo de resolução de pendências QR Code - Pagamento Específico

Esse método deve ser chamado para executar a resolução de pendências QR Code - Pagamento específico.

Métodos

Assinatura	Descrição
void resolveQRCodePendencies(QRCodePendencyRequest settlementRequest, PaymentCallback paymentCallback)	Realiza o processo de resolução de pendência QR Code para pagamento específico.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	QRCodePendencyRequest	Sim	Objeto de transferência de dados que conterá as informações da requisição da resolução de pendências para pagamento específico QR Code.
callback	PaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro do processo de resolução de pendências para pagamento específico QR Code.

Detalhe dos parâmetros request (QRCodePendencyRequest)

Nome	Tipo	Obrigatório	Descrição
applicationId	Credentials	Sim	Identificação do aplicativo que está solicitando a consulta.
secretToken	Credentials	Sim	Token de acesso do aplicativo que está solicitando a consulta.
softwareVersion	String	Sim	Versão da aplicação que está solicitando a consulta.
date	Date	Sim	Data / hora do pagamento.
qrId	String	Sim	Identificador QRCode gerado pelo terminal de captura.

response (QRCodePendencyResponse)

QRCODEINTENTSTATUS

QRCODEINTENTTYPE

|Nome|Id|Descrição| | :- | :- | :- | |PAYMENT|0|Indica que o tipo de QR é um pagamento.| |REVERSAL|1|Indica que o tipo de QR é um estorno.| |DEVOLUTION|2|Indica que o tipo de QR é uma devolução.|

EXEMPLO

Realiza o processo de resolução de pendências QR Code - Pagamento Específico

Esse método deve ser chamado para executar a resolução de pendências QR Code - Pagamento específico. Para utilizá-lo, ao menos um identificador do pagamento deve ser fornecido, seja o qrId ou o appTransactionId.

Métodos

Assinatura	Descrição
void resolveQRCodePendencyV2(QRCodePendencyRequestV2 request, PaymentCallback paymentCallback)	Realiza o processo de resolução de pendência QR Code para pagamento específico.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	QRCodePendencyRequestV2	Sim	Objeto de transferência de dados que conterá as informações da requisição da resolução de pendências para pagamento específico QR Code.
callback	PaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro do processo de resolução de pendências para pagamento específico QR Code.

Detalhe dos parâmetros - request (QRCodePendencyRequestV2)

Nome	Tipo	Obrigatório	Descrição
applicationId	Credentials	Sim	Identificação do aplicativo que está solicitando a consulta.
secretToken	Credentials	Sim	Token de acesso do aplicativo que está solicitando a consulta.
softwareVersion	String	Sim	Versão da aplicação que está solicitando a consulta.
date	Date	Sim	Data / hora do pagamento.
qrId	String	Não	Identificador QrCode gerado pelo terminal de captura.
appTransactionId	String	Não	Identificador da transação integrada.

response (QRCodePendencyResponse)

QRCODEINTENTSTATUS

QRCODEINTENTTYPE

EXEMPLO

|import androidx.appcompat.app.AppCompatActivity;import android.content.Intent;
import android.database.Cursor;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import android.widget.Toast;import com.jakewharton.threetenabp.AndroidThreeTen;
import java.math.BigDecimal;import java.text.SimpleDateFormat;
import java.util.Arrays;import java.util.Date;
import java.util.List;
import java.util.TimeZone;import br.com.phoebus.android.payments.api.ApplicationInfo;
import br.com.phoebus.android.payments.api.Credentials;import br.com.phoebus.android.payments.api.Payment;
import br.com.phoebus.android.payments.api.PaymentClient;
import br.com.phoebus.android.payments.api.PaymentStatus;
import br.com.phoebus.android.payments.api.provider.PaymentContract;
import br.com.phoebus.android.payments.api.provider.PaymentProviderApi;
import br.com.phoebus.android.payments.api.provider.PaymentProviderRequest;public class MainActivity extends AppCompatActivity implements View.OnClickListener {
    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();
        AndroidThreeTen.init(getApplication());
        paymentClient.bind(this);
    }    @Override
    public void onClick(View view) {
        doExecute();
    }
    public void doExecute() {
        //definindo as credenciais
        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”);        //criando objeto de request para o payment
        QRCodePendencyRequestV2 request = createRequest(applicationInfo);
        paymentClient.resolveQRCodePendencyV2(request, new PaymentClient.PaymentCallback() {            @Override
            public void onSuccess(QRCodePendencyResponse response) {
                Log.d(“Pendencia resolvida”);
            }            @Override
            public void onError(ErrorData errorData) {
                Log.d(“Algo deu errado!”);
            }
        }
    }
    private QRCodePendencyRequestV2 createRequest(ApplicationInfo appInfo) {
        QRCodePendencyRequestV2 request = new QRCodePendencyRequestV2();
        request.setApplicationInfo(appInfo);       request.setSecretToken(appInfo.getCredentials());
        request.setApplicationId(appInfo.getCredentials());
        request.setSoftwareVersion(appInfo.getSoftwareVersion());
        request.setAppTransactionId(“123456”);        SimpleDateFormat isoFormat = new SimpleDateFormat(“yyyy-MM-dd’T’HH:mm:ss.SSS”);
        isoFormat.setTimeZone(TimeZone.getTimeZone(“UTC”));        try {
            Date date = isoFormat.parse(“2021-07-27T00:00:00.000”);
           request.setDate(date);
        } catch (Exception e) {
            Toast.makeText(this, e.getMessage(), Toast.LENGTH_LONG).show();
            Log.e(TAG, e.getMessage(), e);
        }
        return request;
    }
}| | :- | —–

Realiza o processo de resolução de pendências QR Code - Lista de pagamentos

Esse método deve ser chamado para executar a resolução de pendências QR Code - Lista de pagamentos.

Métodos

Assinatura	Descrição
void resolveQRCodePendencies(QRCodePendenciesRequest request, PaymentCallback paymentCallback)	Realiza o processo de resolução de pendência QR Code para lista de pagamentos.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
request	QRCodePendenciesRequest	Sim	Objeto de transferência de dados que conterá as informações da requisição da resolução de pendências para lista de pagamentos QR Code.
callback	PaymentCallback	Sim	Interface que será executada para notificações de sucesso ou erro do processo de resolução de pendências para lista de pagamentos QR Code.

Detalhe dos parâmetros request (QRCodePendenciesRequest)

Nome	Tipo	Obrigatório	Descrição
applicationId	Credentials	Sim	Identificação do aplicativo que está solicitando a consulta.
secretToken	Credentials	Sim	Token de acesso do aplicativo que está solicitando a consulta.
softwareVersion	String	Sim	Versão da aplicação que está solicitando a consulta.

response

EXEMPLO

Algoritmo recomendado para Aplicações integradas

A aplicação de Pagamentos registra o status da transação que pode ser consultado posteriormente, para que o app que se integra via SDK tenha conhecimento do estado atual da transação e tome alguma ação, caso necessário.

Durante o fluxo transacional podem ocorrer falhas inesperadas, como o desligamento do terminal ou fechamento repentino da aplicação devido a algum erro não tratado. Isto pode gerar inconsistências na resolução da transação, sendo preciso que em alguns momentos o app que se integra via SDK realize algumas ações para resolver essa inconsistência.

O diagrama abaixo descreve o fluxo dos status da aplicação e em seguida são apresentadas sugestões de como corrigir possíveis erros.

Em situações de falha inesperada (fechamento da aplicação pelo operador do terminal, por exemplo, ou Fatal Exception), tanto na aplicação de Pagamentos quanto na aplicação que se integra via SDK, recomendamos adotar algumas estratégias para garantir que as pendências sejam resolvidas e as transações sejam processadas de forma consistente:

1. Imediatamente antes de chamar startPaymentV2() (ou outras funções do SDK), a aplicação deve registrar de forma persistente o horário atual e os dados que possui da transação a ser iniciada,

appTransactionId, bem como um status que indique que irá chamar startPaymentV2();

1. Imediatamente ao receber o callback (onSuccess ou onError), a aplicação deve registrar de forma persistente o horário atual, os dados retornados, e um status que indique que recebeu o callback;

2. Caso ocorra interrupção do fluxo em um pagamento, os métodos de callbacks (onSuccess ou onError) não serão chamados. a. A aplicação que chamou startPaymentV2() pode identificar este caso de duas formas: i. Quando a Aplicação iniciar sua execução, deve verificar se existir registro de chamada de startPaymentV2(), sem que tenha havido registro do callback correspondente. Nesse caso pode ter havido interrupção inesperada da própria aplicação, podendo ou não ter havido também interrupção inesperada de Payments;ii. Ao detectar um longo tempo (por exemplo, 10 minutos) após a chamada de startPaymentV2(), sem que tenha havido o callback. Nesse caso pode ter havido interrupção inesperada de Payments; b. Nesses casos,

para transações de pagamento com cartão o comportamento recomendado é o seguinte: i. Realizar uma consulta (Vide Consulta), passando o appTransactionId da transação; ii. Caso o paymentStatus seja igual a CANCELLED, a transação foi desfeita por Payments e já está finalizada. A aplicação deve considerar que a transação não foi realizada. Não é necessária nenhuma ação para resolver pendências com Payments; iii. Caso o paymentStatus seja igual a PENDING, a Aplicação deve solicitar desfazimento através do método cancelPayment(). Se a identificação da situação ocorreu da forma descrita em “i”, pode ser que Payments não tenha sido interrompida e ainda esteja executando o pagamento, por isso o App deve esperar pelo menos 10 minutos (desde o tempo registrado em “1”) antes de chamar cancelPayment(); iv. Caso o paymentStatus seja igual a UNREACHABLE ou PROCESSING, a transação foi interrompida antes mesmo de ser enviada ao autorizador. A aplicação deve considerar que a transação não foi realizada. Não é necessária nenhuma ação para resolver pendências com Payments; v. Caso o paymentStatus seja igual a DENIED, a transação foi negada. A aplicação deve considerar que a transação não foi realizada. Não é necessária nenhuma ação para resolver pendências com Payments; c. Nesses casos, para transações de pagamento com QR o comportamento recomendado é o seguinte: i. Chamar o método resolveQRCodePendencyV2(), passando o appTransactionId da intenção; ii. Caso o qrCodeIntentStatus seja igual a PENDING ou CREATED, o app deve continuar consultando (chamando resolveQRCodePendencyV2()) até receber um status final; iii. Caso o qrCodeIntentStatus seja igual a CANCELLED, EXPIRED ou DENIED, a aplicação deve considerar que a transação não foi realizada. Não é necessária nenhuma ação para resolver pendências com Payments; iv. Caso o qrCodeIntentStatus seja igual a APPROVED, a aplicação receberá os dados da transação e deverá processá-los. A aplicação deve considerar que a transação foi realizada. Não é necessária nenhuma ação para resolver pendências com Payments.