O PosTransactionProvider é o provedor de transação utilizado ao efetuar pagamentos utilizando um POS Android.
Para passar uma transação, a primeira coisa a ser feita é instanciar um objeto do tipo TransactionObject
final TransactionObject transaction = new TransactionObject();
E popular os seguintes atributos do TransactionObject:
| Nome | Tipo | Descrição |
|---|---|---|
| amount obrigatório | String | Valor da transação em centavos. |
| requestId opcional | String | ID do pedido. |
| initiatorTransactionKey opcional | String | É um identificador único da transação definido pela aplicação que inicia a transação. O SDK possui um padrão próprio para gerar este identificador e usará esse padrão se um identificador não for definido. Caso você queira passar o seu próprio identificador, certifique-se que ele será sempre único para todos os seus clientes. |
| emailClient opcional | EmailClient | Seu email de noReply para envio do comprovante eletrônico. |
| instalmentTransactionEnum (¹) obrigatório | Enum | Quantidade de parcelas. |
| typeOfTransactionEnum (¹) obrigatório | Enum | Tipo da transação (débito, crédito, voucher ou PIX). |
| shortName (condicional) - Parceiros: opcional - Subadquirentes: Obrigatório | String | Nome fantasia do estabelecimento¹ (aparecerá na fatura do portador). Deve obrigatoriamente corresponder ao principal nome utilizado pelo estabelecimento. Campo obrigatório para subadquirentes, porém não restritivo à elas. ¹ Se o estabelecimento comercial faz parte do segmento de casas de câmbio, para transações da bandeira Mastercard será necessário identificar na tagShrtNm da autorização. Exemplo: nomedomerchant*cambio. |
| capture obrigatório | Boolean | Define se a transação será realizada com captura automática ou não. |
| subMerchantCategoryCode (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | MCC do sub-merchant que efetuou a transação. Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantAddress (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | Logradouro do sub-merchant. Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantCity (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | Cidade do sub-merchant. Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantPostalAddress (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | CEP do sub-merchant. Atributo obrigatório apenas em casos de aplicações de subadquirentes. |
| subMerchantRegisteredIdentifier (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | Identificador do sub-merchant no Sistema do Subadquirente. Atributo obrigatório apenas em casos de aplicações de subadquirentes. |
| subMerchantTaxIdentificationNumber (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | CNPJ do sub-merchant. Atributo obrigatório apenas em casos de aplicações de subadquirentes. |
| subMerchantStreetName (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | Rua/Avenida do sub-merchant. Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantLegalName (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | Razão social do sub-merchant. Atributo obrigatório para aplicações de subadquirentes. NÃO é a informação que aparece na fatura do portador. Veja o campo shortName. |
| subMerchantBuildingNumber (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | Número do prédio do sub-merchant. Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantCountryCode (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | Código do país do sub-merchant (ex: 076 para Brasil). Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantState (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | UF do estado do sub-merchant. Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantNeighborhood (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | Bairro do sub-merchant. Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantEmail (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | Email de contato do sub-merchant. Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantPhone (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | Telefone de contato do sub-merchant. Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantTaxIdentificationType (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | Físico (PRSN) ou jurídico (JRDC). Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantSiteUrl (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | URL do site do sub-merchant. Atributo obrigatório para aplicações de subadquirentes. |
| subMerchantPaymentGatewayId (condicional) - Parceiros: Não devem utilizar - Subadquirentes: Obrigatório | String | ID do gateway de pagamento do sub-merchant. Atributo obrigatório para aplicações de subadquirentes. |
Exemplo:
//Valor da transação em centavos
transaction.setAmount("10");//Valor da transação em centavos
transaction.setRequestId(null);
/* AVISO IMPORTANTE: Não é recomendado alterar o campo abaixo do ITK,
* pois ele gera um valor único. Contudo, caso seja necessário
* faça conforme a linha a seguir. */
transaction.setInitiatorTransactionKey("SEU_IDENTIFICADOR_UNICO_AQUI");
//Informa a quantidade de parcelas, veja a tabela de valores para o InstalmentTransactionEnum
transaction.setInstalmentTransaction(InstalmentTransactionEnum.ONE_INSTALMENT);
//Definir forma de pagamento
transaction.setTypeOfTransaction(TypeOfTransactionEnum.CREDIT);
// Define se transação será feita com captura ou não.
transaction.setCapture(true);
//Os campos abaixo são obrigatório apenas em casos de aplicações de subadquirentes
//Cidade do sub-merchant
stoneTransaction.setSubMerchantCity("city")
//CEP do sub-merchant (Apenas * números)
stoneTransaction.setSubMerchantPostalAddress("00000000")
// Identificador do sub-merchant
stoneTransaction.setSubMerchantRegisteredIdentifier("00000000")
// Identificador do sub-merchant
stoneTransaction.setSubMerchantTaxIdentificationNumber("33368443000199")
// Rua/Avenida do sub-merchant
stoneTransaction.setSubMerchantStreetName("Avenida Paulista")
// Razão social do sub-merchant
stoneTransaction.setSubMerchantLegalName("Stark Corporation Ltda")
// Número do prédio do sub-merchant
stoneTransaction.setSubMerchantBuildingNumber("1000")
// Código do país do sub-merchant
stoneTransaction.setSubMerchantCountryCode("076")
// UF do estado do sub-merchant
stoneTransaction.setSubMerchantState("SP")
// Bairro do sub-merchant
stoneTransaction.setSubMerchantNeighborhood("Bela Vista")
// Email de contato do sub-merchant
stoneTransaction.setSubMerchantEmail("contato@starkcorp.com.br")
// Telefone de contato do sub-merchant
stoneTransaction.setSubMerchantPhone("11987654321")
// Tipo de documento fiscal do sub-merchant
stoneTransaction.setSubMerchantTaxIdentificationType("JRDC")
// URL do site do sub-merchant
stoneTransaction.setSubMerchantSiteUrl("www.starkcorp.com.br")
// ID do gateway de pagamento do sub-merchant
stoneTransaction.setSubMerchantPaymentGatewayId("GATEWAY123")
Após instanciar e popular o objeto TransactionObject, você poderá passar o mesmo para o PosTransactionProvider, que será o responsável por enviar a transação para o autorizador e trabalhar com a inserção e atualização no TransactionDAO.
Exemplo:
//Processo para envio da transação
// Stone.getUserModel(0) é o usuário atual do aplicativo, que está na posição zero.
final PosTransactionProvider provider = new PosTransactionProvider("SUA_ACTIVITY_AQUI", transaction, "USUARIO_DO_APLICATIVO_AQUI");
provider.setConnectionCallback(new StoneActionCallback() {
@Override
public void onSuccess() {
// Transação enviada com sucesso e salva no banco. Para acessar, use o TransactionDAO
}
@Override
public void onStatusChanged(Action action) {
// Nesse callback é retornado o próximo passo a ser executado no fluxo de pagamento
}
@Override
public void onError() {
// Erro na transação
}
});
provider.execute();
//Processo para envio da transação
// Stone.getUserModel(0) é o usuário atual do aplicativo, que está na posição zero.
val provider = PosTransactionProvider("SUA_ACTIVITY_AQUI", transaction, "USUARIO_DO_APLICATIVO_AQUI")
provider.connectionCallback= object : StoneActionCallback {
override fun onSuccess() {
// Transação enviada com sucesso e salva no banco. Para acessar, use o TransactionDAO
}
override fun onStatusChanged(action: Action) {
// Nesse callback é retornado o próximo passo a ser executado no fluxo de pagamento
}
override fun onError() {
// Erro na transação
}
}
provider.execute()
Após a execução do provider, a sua aplicação receberá uma chamada no método onSuccess() ou onError().
Para ter acesso ao status da transação, você deve utilizar o método:
provider.getTransactionStatus();
Em caso de REJECTED e DECLINED, você pode capturar a mensagem do autorizador, utilizando o método:
provider.getMessageFromAuthorize();
Mensagens como, por exemplo: “Saldo insuficiente”, “Cartão inválido”, “Violação de segurança”, etc.
Transações de QRCode
O Stone SDK também suporta transações com QRCode em seus Providers de Transação. Este tipo de transação possui fluxo próprio mas de fácil integração dentro da mesma arquitetura utilizada para transações de cartão.
Para, por exemplo, realizar uma transação PIX, basta setar o tipo da transação
transaction.setTypeOfTransaction(TypeOfTransactionEnum.PIX);
Ou, caso queira suportar transações de QRCode Elo (Auxílio Emergencial), configure o tipo e o entry mode
transaction.setTypeOfTransaction(TypeOfTransactionEnum.DEBIT);
transaction.setEntryMode(EntryMode.QRCODE);
E responder à Action para exibição do QRCode gerado, exibindo-o na tela. A propriedade "QRCode" no TransactionObject é um Bitmap para ser atribuído em uma View
@Override
public void onStatusChanged(Action action) {
if (action == Action.TRANSACTION_WAITING_QRCODE_SCAN) {
// Mostre o QRCode na tela usando transaction.getQRCode()
}
}
Também é necessário que o StoneCode que esteja gerando o QRCode tenha uma Conta Stone cadastrada, caso contrário não será possível gerar o QRCode.
Caso não haja uma Conta Stone associada, a mensagem de erro será "Conta Stone não encontrada", no campo transactionProvider.getMessageFromAuthorize();
Antes de fazer uma transação de QRCode também é necessário configurar as chaves de acesso à API de QRCode, QRCODE_AUTHORIZATION e QRCODE_PROVIDERID, conforme coberto no tópico Inicializando o SDK
Caso as credenciais estejam incorretas, a mensagem de erro será "Erro no Sistema", no campo transactionProvider.getMessageFromAuthorize();
Abort Payment
O método de abortPayment() é utilizado como um recurso de cancelamento de transações que estão em andamento, podendo ser considerada uma reversão. Esse cenário pode acontecer por iniciativa do próprio usuário (cancelando a operação antes de passar o cartão usando a opção de cancelar, por exemplo) ou por algum motivo interno na comunicação entre as partes durante o processo de pagamento (após o usuário confirmar o pagamento com seu cartão ou outra modalidade escolhida).
Quando o abortPayment() é chamado, são realizadas as seguintes etapas:
- O
TransactionObject.transactionStatusé alterado paraTransactionStatusEnum.CANCELLED;- Em paralelo, o processo de pagamento tentará ser cancelado;
- O
TransactionObject.transactionStatusé alterado paraTransactionStatusEnum.PENDING_REVERSAL;- Em paralelo, a transação tentará ser revertida;
- Será checado se a transação foi gravada no banco de dados;
- Caso positivo, seus dados serão atualizados;
- Uma função de callback será chamada caso alguma tenha sido informada;
Java
PosTransactionProvider provider = PosTransactionProvider(context, transactionObject, userModel);
// Faça o processo de pagamento
// Em caso de retornar erro ou usuário cancelou o processo
provider.abortPayment();
Jornada: Integrar pelos Providers
Etapa 10 de 18