Pré-requisitos

• Versão da API: Esta guia refere-se à Versão 2 (startPaymentV2).
• Bind Assíncrono: Antes de qualquer chamada à API, certifique-se de bindar o PaymentClient usando paymentClient.bind(this). O bind é assíncrono, então verifique se a conexão está estabelecida antes de prosseguir (por exemplo, implemente um listener para o bind).
• Fluxo Geral: O pagamento segue um fluxo de autorização pendente, que requer confirmação (confirmPayment) ou desfazimento (cancelPayment) para conclusão. Consulte o diagrama de fluxo na documentação principal para detalhes.

Passos para Iniciar um Pagamento

1. Instancie o PaymentClient

Crie uma instância do PaymentClient na sua Activity ou Fragment. Recomenda-se fazer isso no onCreate ou onResume.

import br.com.phoebus.android.payments.api.PaymentClient;

// Dentro da sua Activity
private PaymentClient paymentClient;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    paymentClient = new PaymentClient();
}

2. Bindar o Client

Bind o client ao serviço de pagamentos. Faça isso no onResume para garantir reconexão ao retornar à tela.

@Override
protected void onResume() {
    super.onResume();
    paymentClient.bind(this);  // Bind assíncrono - aguarde confirmação se necessário
}

Desbinde no onDestroy para liberar recursos:

@Override
protected void onDestroy() {
    try {
        paymentClient.unbind(this);
    } catch (Exception e) {
        // Log de erro
    }
    super.onDestroy();
}

3. Prepare a Requisição de Pagamento (PaymentRequestV2)

Crie um objeto PaymentRequestV2 com os parâmetros necessários. Os campos obrigatórios incluem credenciais e ID da transação do app. Exemplo básico:

import br.com.phoebus.android.payments.api.PaymentRequestV2;
import br.com.phoebus.android.payments.api.ApplicationInfo;
import br.com.phoebus.android.payments.api.Credentials;
import java.math.BigDecimal;

// Método para preparar a requisição
private void preparePayment() {
    PaymentRequestV2 request = new PaymentRequestV2();
    
    // Valor do pagamento (ex.: R$ 50,00)
    BigDecimal value = BigDecimal.valueOf(5000).movePointLeft(2);  // 50.00
    request.setValue(value);
    
    // ID único da transação no seu app (até 6 caracteres)
    request.setAppTransactionId("123456");
    
    // Credenciais do Portal PayStore
    Credentials credentials = new Credentials();
    credentials.setApplicationId("SEU_APPLICATION_ID");  // Substitua pelo seu ID
    credentials.setSecretToken("SEU_SECRET_TOKEN");      // Substitua pelo seu token
    
    // Informações da aplicação
    ApplicationInfo appInfo = new ApplicationInfo();
    appInfo.setCredentials(credentials);
    appInfo.setSoftwareVersion("1.0");  // Versão do seu app
    request.setAppInfo(appInfo);
    
    // Outros parâmetros opcionais (ex.: tipos de pagamento, parcelas, etc.)
    // request.setPaymentTypes(Arrays.asList(PaymentType.CREDIT));  // Exemplo: Apenas crédito
    // request.setInstallments(3);  // Exemplo: 3 parcelas
    
    // Inicie o pagamento (veja próximo passo)
}

Para detalhes completos dos parâmetros, consulte a tabela "Detalhe dos Parâmetros" na documentação principal (ex.: additionalValue, productShortName, etc.). Doc

4. Inicie o Pagamento (startPaymentV2)

Chame o método startPaymentV2 passando a requisição e um callback para lidar com o resultado. Implemente a interface PaymentClient.PaymentCallback na sua Activity.

import br.com.phoebus.android.payments.api.PaymentV2;
import br.com.phoebus.android.payments.api.ErrorData;
import br.com.phoebus.android.payments.api.exception.ClientException;

// Sua Activity deve implementar PaymentClient.PaymentCallback<PaymentV2>
public class SuaActivity extends AppCompatActivity implements PaymentClient.PaymentCallback<PaymentV2> {

    // Método para iniciar
    private void startPayment() {
        preparePayment();  // Do passo anterior
        try {
            paymentClient.startPaymentV2(request, this);  // 'this' é o callback
        } catch (ClientException e) {
            // Trate erro de cliente (ex.: bind não conectado)
        }
    }

    @Override
    public void onSuccess(PaymentV2 payment) {
        // Pagamento autorizado (pendente) - confirme ou cancele
        // Ex.: payment.getPaymentId() para usar em confirm/cancel
        doConfirmPayment(payment.getPaymentId());
    }

    @Override
    public void onError(ErrorData errorData) {
        // Erro na autorização - exiba mensagem
        String message = errorData.getResponseMessage();
        // Log ou Toast
    }
}

• onSuccess: Recebe um PaymentV2 com detalhes da transação (ex.: paymentId, value, status = PENDING). Use para confirmar ou cancelar.
• onError: Recebe ErrorData com códigos de erro (consulte "Códigos de Resposta" na doc principal).

5. Confirme ou Cancele o Pagamento

Após sucesso na autorização, chame confirmPayment ou cancelPayment usando o paymentId. Exemplo de confirmação:

private void doConfirmPayment(String paymentId) {
    try {
        paymentClient.confirmPayment(paymentId, new PaymentClient.PaymentCallback<PaymentV2>() {
            @Override
            public void onSuccess(PaymentV2 payment) {
                // Confirmação OK - imprima comprovante se configurado
            }

            @Override
            public void onError(ErrorData errorData) {
                // Erro na confirmação - tente cancelar
            }
        });
    } catch (ClientException e) {
        // Erro de cliente
    }
}

Para cancelamento, substitua por cancelPayment(paymentId, callback).

6. Tratamento de Erros e Considerações

• Erros Comuns: Verifique códigos em ErrorData.paymentsResponseCode. Ex.: "TRANSACTION_NOT_FOUND" se o paymentId for inválido.
• Interface do Terminal: Durante o processo, o terminal pode exibir telas (ex.: inserir senha). Não interfira na UI do app.
• Impressão de Comprovantes: Configure printMerchantReceipt e printCustomerReceipt na requisição para controlar impressões automáticas após confirmação.
• Segurança: Armazene credenciais de forma segura (não hardcode em produção).