É uma SDK que oferece uma interface simples para fazer transações financeiras, utilizando o .NET Framework 4.5.2.
Oferecer aos nossos parceiros que possuam aplicações de pagamento/automações comerciais, ferramentas fáceis para efetuar pagamentos sem a utilização de um TEF.
Nome da SDK/Projeto | Razão de ser |
---|---|
Buy4.Framework.Portable | Faz a parte de comunicação HTTP. |
Tms.Sdk | Faz a comunicação com o Terminal Management Service da Stone. |
Poi.Sdk | Faz a comunicação com o autorizador da Stone. |
Pinpad.Sdk | Faz a comunicação lógica (protocolo ABECS) com o pinpad. |
MicroPos.Crossplaftorm | Define um contrato que a plataforma deverá cumprir. Atualmente, a MicroTef funciona nos ambientes descritos acima, mas se surgir a necessidade de implementar uma nova plataforma (iOS, por exemplo), um novo projeto não portable terá que ser criado e terá que cumprir as interfaces descritas nesse projeto. Exemplos de funcionalidades que são dependentes da plataforma: criptografia, log, comunicação serial, etc. |
MicroPos.Platform.Desktop | MicroTef para desktop (Windows, Mono). |
MicroPos.Interop | MicroTef para COM interop. |
MicroPos.Platform.Uwp | MicroTef para Windows.Core (Windows 10 IoT, Windows 10, Windows Mobile 10). |
Receipt.Sdk | Envia recibos de transação, cancelamento e ativação de um terminal por e-mail. |
Você precisará de um ou mais pinpads conectados ao PC.
// Inicializa a plataforma desktop:
MicroPos.Platform.Desktop.DesktopInitializer.Initialize();
// Inicializa a plataforma UWP:
CrossPlatformUniversalApp.CrossPlatformUniversalAppInitializer.Initialize();
A ativação é uma operação opcional. Deve ser feita quando a aplicação não tem acesso ao SAK, e sim ao StoneCode.
Você vai precisar de:
- 1x StoneCode
- 1x URL do TMS da Stone
A ativação é uma operação para, através do StoneCode, resgatar o SAK e as informações do estabelecimento.
// Cria um cliente para o TMS
ITmsClient tms = TmsProvider.Get(tmsUri);
// Envia uma requisição de ativação
IActivationReport activation = tms.Activate(stoneCode);
if (activation?.WasSuccessful == true)
{
// Ativação bem sucedida!
}
else if (activation?.WasSuccessful == false)
{
// Ativação falhou
// Mostra código de erro:
Debug.WriteLine(activation.ResponseCode);
// Mostra razão do erro:
Debug.WriteLine(activation.ResponseReason);
}
A interface IActivationReport reotrnada pelo TMS possui todos os dados sobre o estabelecimento.
Tipo | Informação | Descrição |
---|---|---|
MerchantAddress | Address | Endereço do estabelecimento. Com o método ToString(), é possível obter o endereço formatado. |
string | CompanyName | Nome (nome fantasia) do estabelecimento. |
string | IdentityCode | CPF ou CNPJ. |
string | ResponseCode | Código de resposta em caso de erro. |
string | ResponseReason | Razão da resposta em caso de erro. |
string | SaleAffiliationKey | Identificador unico do meio de captura relacionado a um StoneCode. Um StoneCode pode ter varios SAKs, assim como um SAK pode estar relacionado a somente um StoneCode. |
bool | WasSuccessful | Se a ativação foi bem sucedida. |
string | XmlRequest | XML de requisição da ativação. |
string | XmlResponse | XML de resposta da ativação, recebido pelo TMS. |
Você irá precisar de:
- 1x Sale Affiliation Key (SAK)
- 1x URL do autorizador da Stone
- 1x URL do TMS (Terminal Management Service) da Stone
Crie mensagens personalizadas para aparecerem na tela do pinpad. Cada mensagem não pode ter mais de 16 caracteres (caso contrário, serão mostrados os primeiros 16 caracteres). Assim:
DisplayableMessages pinpadMessages = new DisplayableMessages()
{
ApprovedMessage = "Aprovada :-)",
DeclinedMessage = "Negada :-(",
InitializationMessage = "Olá!",
MainLabel = "Stone Pagamentos",
ProcessingMessage = "Processando..."
};
Se você conhece a porta serial a qual o pinpad está conectado, utilize:
try
{
ICardPaymentAuthorizer authorizer = DeviceProvider.GetOneOrFirst("SAK_DE_EXEMPLO", "authorizador.com",
"tms.com", pinpadMessages, "COM6");
}
catch (PinpadNotFoundException)
{
// Nenhum pinpad conectado à máquina
}
Se você não souber, utilize:
try
{
ICardPaymentAuthorizer authorizer = DeviceProvider.GetOneOrFirst("SAK_DE_EXEMPLO", "authorizador.com",
"tms.com", pinpadMessages);
}
catch (PinpadNotFoundException)
{
// Nenhum pinpad conectado à máquina
}
Cada ICardPaymentAuthorizer está ligado à um único pinpad.
Se você quiser todos os pinpads conectados à màquina, use:
try
{
ICollection<ICardPaymentAuthorizer> authorizers = DeviceProvider.GetAll("SAK_DE_EXEMPLO",
"authorizador.com", "tms.com", pinpadMessages);
}
catch (PinpadNotFoundException)
{
// Nenhum pinpad conectado à máquina
}
Fluxo de transação em que a nossa SDK fica responsável por todo o processo de autorização, ou seja: leitura do cartão, leitura da senha, envio da mensagem ao autorizador e "compreensão" da resposta do autorizador.
Nesse fluxo, é necessário conhecer todos os dados [mandatórios] da transação, ou seja, valor e tipo (débito ou crédito).
// Montando uma transação de débito de 10 centavos:
TransactionEntry transaction = new TransactionEntry(TransactionType.Debit, 0.1m);
// Boa prática: sempre utilize o ITK!
transaction.InitiatorTransactionKey = "algum identificador";
try
{
// Inicia o fluxo transacional:
IAuthorizationReport report = authorizer.Authorize(transaction);
}
catch (ExpiredCardException)
{
// Um cartão expirado foi passado/inserido
}
catch (CardHasChipException)
{
// Um cartão que tem chip foi passado como tarja
}
Fluxo da transação em que não se tem todas as informações sobre a transação, ou se deseja performar alguma operação entre as etapas da transação.
- Exemplo: deseja-se iniciar a transação (esperar pelo cartão), mas antes de solicitar a senha o serviço precisa consultar um sistema que possui o valor da transação.
// Monta uma transação que não conhece nem o valor nem o tipo da transação:
TransactionEntry transaction = new TransactionEntry()
{
CaptureTransaction = true
};
ICard cardRead;
ResponseStatus status = ResponseStatus.Undefined;
try
{
// Lê o cartão.
// Como o tipo da transação não foi especificado, o pinpad perguntará se a
// transação é de crédito ou débito. Se o cartão for apenas de crédito ou
// apenas de débito, o pinpad escolherá automaticamente.
status = authorizer.ReadCard(out cardRead, transaction);
if (status != ResponseStatus.Ok) { throw new SomeErrorException(); }
}
catch (ExpiredCardException)
{
// Um cartão expirado foi passado/inserido
}
catch (CardHasChipException)
{
// Um cartão que tem chip foi passado como tarja
}
// Método FICTICIO, em que um suposto serviço retorna o valor da transação:
transaction.Amount = this.AutomationService.GetAmount();
Pin pinInformation;
// Lê a senha do cartão:
status = authorizer.ReadPassword(out pin, cardRead, transaction.Amount);
if (status != ResponseStatus.Ok) { throw new AnotherErrorException(); }
// Envia a transação para o autorizador da Stone:
IAuthorizationReport authorizationReport = authorizer.SendAuthorizationAndGetReport(card, transaction,
pin);
O Initiator Transaction Key (ITK) é um identificador da transação definido pela aplicação integradora. Se o ITK ficar vazio, iremos substituir esse valor por um GUID. "Mas por que devo utilizá-lo?"
- O cancelamento de uma transação é feito através de um ATK (identificador da transação definido pela Stone) ou pelo ITK. Caso algo dê errado no processo de autorização, o ATK não estará disponível. Ou seja, o cancelamento será através do ITK.
- Esse campo aparece na conciliação.
Em ambos os fluxos (clássico e alternativo), durante a autorização um evento será disparado com a status da transação. Para capturá-los (attach), faça o seguinte:
authorizer.OnStateChanged += this.OnTransactionStateChange;
private void OnTransactionStateChange(object sender, AuthorizationStatusChangeEventArgs e)
{
Debug.WriteLine(e.AuthorizationStatus + " " + e.Message);
}
A interface IAuthorizationReport retornada nos métodos de autorização possuem todos os dados da transação.
Tipo | Informação | Descrição |
---|---|---|
bool | WasApproved | Se a transação foi aprovada ou não |
string | AcquirerTransactionKey | ID da transação definido pela Stone (também conhecido por Stone ID). 🏆 Boa prática: persista esse dado em algum lugar! |
string | InitiatorTransactionKey | Identificador da transação definido pela aplicação. Se esse campo não for definido, um GUID será usado aqui. 🏆 Boa prática: persista esse dado em algum lugar! |
decimal | Amount | Valor da transação em reais. 🏆 Boa prática: persista esse dado em algum lugar! |
DateTime | DateTime | Data e hora da transação. |
TransactionType | TransactionType | Tipo da transação (débito/crédito). |
Installment | Installment | Dados do parcelamento da transação. |
ICard | Card | Dados do cartão utilizado na transação. |
int | ResponseCode | Código de resposta do autorizador. 🏆 Boa prática: persista esse dado em algum lugar! |
string | ResponseReason | Razão de resposta do autorizador. |
string | XmlResponse | XML de resposta da autorização. |
string | XmlRequest | XML de requisição da autorização. |
PoiResponseBase | RawResponse | Resposta "crua" de autorização. |
- Para cancelar uma transação através do IAuthorizationResponse:
// Montando uma transação de débito de 10 centavos:
TransactionEntry transaction = new TransactionEntry(TransactionType.Debit, 0.1m);
// Boa prática: sempre utilize o ITK!
transaction.InitiatorTransactionKey = "algum identificador";
IAuthorizationReport report = null;
try
{
// Envia a transação para o autorizador da Stone:
report = authorizer.Authorize(transaction);
}
catch (ExpiredCardException)
{
// Um cartão expirado foi passado/inserido
}
catch (CardHasChipException)
{
// Um cartão que tem chip foi passado como tarja
}
CancellationRequest cancelRequest = CancellationRequest.CreateCancellationRequest("SAK_DE_EXEMPLO",
report.RawResponse);
authorizer.AuthorizationProvider.SendRequest(cancelRequest);
Para cancelar uma transação através de um ID da transação, considere o seguinte trecho de código:
// Cria um tipo de parcelamento: crédito em 4 vezes sem juros:
Installment installment = new Installment() { Type = InstallmentType.Merchant, Number = 4 }
// Monta a transação
TransactionEntry transactionToCancel = new TransactionEntry(TransactionType.Credit, 120m, installment,
"ITK_DE_EXEMPLO");
IAuthorizationReport authorizationReport = null;
try
{
// Autoriza
authorizationReport = authorizer.Authorize(transactionToCancel);
}
catch (ExpiredCardException)
{
// Um cartão expirado foi passado/inserido
}
catch (CardHasChipException)
{
// Um cartão que tem chip foi passado como tarja
}
- Para cancelar uma transação através do ITK:
// Monta a requisição de cancelamento:
CancellationRequest cancelRequest = CancellationRequest.
CreateCancellationRequestByInitiatorTransactionKey("SAK_DE_EXEMPLO",
authorizationReport.InitiatorTransactionKey, authorizationReport.Amount, true);
// Envia a requirição de cancelamento:
authorizer.AuthorizationProvider.SendRequest(cancelRequest);
- Para cancelar uma transação através do ATK:
// Monta a requisição de cancelamento:
CancellationRequest cancelRequest = CancellationRequest.
CreateCancellationRequestByAcquirerTransactionKey("SAK_DE_EXEMPLO",
authorizationReport.AcquirerTransactionKey, authorizationReport.Amount, true);
// Envia a requisição de cancelamento:
authorizer.AuthorizationProvider.SendRequest(cancelRequest);
Task.Run(() =>
{
// Cancela o ultimo comando do pinpad:
this.authorizer.PinpadFacade.Communication.CancelRequest();
// Desconecta:
this.authorizer.PinpadFacade.Communication.ClosePinpadConnection(this.authorizer.
PinpadMessages.MainLabel);
});
Esta SDK implementa emissão de comprovante (vulgo: notinha) de operações como: Transação, Cancelamento de Transação e Ativação de Terminal.
Utilizando esta funcionalidade
- Para um e-mail de ativação:
IReceiptService service = ReceiptFactory.Build(ReceiptType.Activation, "garrick.ollivander@ollivanders.com.uk");
ActivationBodyParameters parameters = new ActivationBodyParameters
{
CompanyName = "Ollivanders",
CompanyAddress = "Diagon Alley",
CompanyLegalIdentification = "000.000.000-00",
CompanyStoneCode = "000 000 000"
};
service.AddBodyParameters(parameters);
service.Send();
- Para um e-mail de transação:
IReceiptService service = ReceiptFactory.Build(ReceiptType.Transaction, "garrick.ollivander@ollivanders.com.uk");
FinancialOperationParameters parameters = new FinancialOperationParameters
{
CardBrand = "MASTER - DEBITO",
ClientMaskedCardNumber = "1234 **** **** 7890",
ClientName = "Garrick Ollivander",
CompanyName = "Ollivanders",
CompanyAddress = "Diagon Alley",
CompanyTaxDocumentNumber = "123098",
DisplayAidArqc = true,
DisplayCompanyInformation = true,
TransactionAid = "123456",
TransactionAmount = 0.02m,
TransactionArqc = "1234567890",
TransactionDateTime = DateTime.Now,
TransactionStoneId = "12345678"
};
service.AddBodyParameters(parameters);
service.Send();
- Para um e-mail de cancelamento de transação:
IReceiptService service = ReceiptFactory.Build(ReceiptType.Cancellation, "garrick.ollivander@ollivanders.com.uk");
FinancialOperationParameters parameters = new FinancialOperationParameters
{
CardBrand = "MASTER - DEBITO",
ClientMaskedCardNumber = "1234 **** **** 7890",
ClientName = "Garrick Ollivander",
CompanyName = "Ollivanders",
CompanyAddress = "Diagon Alley",
CompanyTaxDocumentNumber = "123098",
DisplayAidArqc = true,
DisplayCompanyInformation = true,
TransactionAid = "123456",
TransactionAmount = 0.02m,
TransactionArqc = "1234567890",
TransactionDateTime = DateTime.Now,
TransactionStoneId = "12345678"
};
service.AddBodyParameters(parameters);
service.Send();
Entre em contato: devmicrotef@stone.com.br
🐙