EvoluServices API
Introdução
O objetivo desta documentação é orientar o desenvolvedor sobre como utilizar nossas APIs para integrar com a solução Evo/SaúdeService de transações Pinpad, descrevendo as funcionalidades, os métodos a serem utilizados, listando informações a serem enviadas e recebidas, e provendo exemplos.
As APIs estão organizadas em torno de um conjunto de endpoints acessíveis via HTTP que recebem e respondem JSON.
Antes do início da operação em ambiente de produção, é necessário passar pelo processo de homologação para que as implementações sejam certificadas junto à EvoluServices. Para maiores informações, por favor, entre em contato com a equipe de suporte.
Suporte EvoluServices
Disponibilizamos uma equipe de Suporte especializada para auxiliá-lo caso tenha alguma dúvida. Para entrar em contato conosco clique aqui
Caso queira se tornar um Parceiro EvoluServices clique aqui
Postman
Aqui está uma coleção de requisições de exemplo no Postman para ajudar a se familiarizar mais rapidamente com a nossas APIs.
Importante
Para usar a requisição de Autenticação, é preciso ter definido, dentro de algum Environment, as seguintes variáveis:
username
apiKey
Para usar as demais requisições, é preciso ter definido, dentro de algum Environment, as seguintes variáveis:
bearer
merchantId
Visão Geral - Transação Remota
A API de transação remota permite que o processamento de transações de cartões de crédito e débito, através de dispositivos físicos (PinPad), seja disparadas por uma chamada HTTP.
Cada transação remota é reconhecida como uma cobrança que deverá ser efetivada através de uma transação. Para realizar a conciliação das cobranças e manter os dados consistentes, ao criar uma nova transação remota, você pode registrar um endereço de retorno (através do parâmetro callbackUrl
) que receberá notificações sobre mudanças de estado da transação.
Aquisição das chaves
Para que seja possível a utilização do API da transação remota, é necessário uma chave que deve ser inserida dentro do campo merchantId
do corpo da requisção, no caso criação da transação remota ou no campo merchantCode
da URL, no caso da listagem de terminais.
Aconselhamos que o parceiro crie uma área da sua plataforma para que os seus estabelecimentos clientes possam cadastrar sua chave de acesso e que inclua instruções de como localizá-la no portal da Evoluservices.
Os estabelecimentos devem acessar este link. Na página, constará uma lista com as chaves de acesso para cada parceiro.
Para mais detalhes, contate o nosso Suporte da Evoluservices.
Autenticação
private string GetToken()
{
HttpWebRequest request = HttpWebRequest.CreateHttp("http://sandbox.evoluservices.com/remote/token");
request.Method = "POST";
request.ContentType = "application/json";
using (Stream requestStream = request.GetRequestStream())
{
string auth = JsonConvert.SerializeObject(new { auth = new { username = "teste", apiKey = "123mudar" } });
byte[] buffer = Encoding.ASCII.GetBytes(auth);
requestStream.Write(buffer, 0, buffer.Length);
}
try
{
using (WebResponse response = request.GetResponse())
{
using (Stream responseStream = response.GetResponseStream())
{
using (StreamReader sr = new StreamReader(responseStream))
{
return JsonConvert.DeserializeObject<dynamic>(sr.ReadToEnd()).Bearer.Value;
}
}
}
}
catch (WebException webException)
{
throw new ApiError(webException.Message, ((HttpWebResponse)webException.Response).StatusCode, ((HttpWebResponse)webException.Response).StatusDescription);
}
}
public class ApiError : Exception
{
public HttpStatusCode StatusCode { get; set; }
public string ReasonPhrase { get; set; }
public ApiError(string message, HttpStatusCode statusCode, string reasonPhrase) : base(message)
{
ReasonPhrase = reasonPhrase;
StatusCode = statusCode;
}
}
Os endpoints das APIs são protegidos por um Bearer
token que deve ser enviado no cabeçalho das requisições HTTP
Para obter um token de acesso é necessário apresentar as credenciais da sua aplicação ao método POST /remote/token
. As credenciais de acesso (username e apiKey) podem ser obtidas entrando em contato com a equipe de suporte.
O token de acesso possui uma data de expiração, mas também pode ser revogado antes do tempo. Sua implementação deve, portanto, ser capaz de tratar a renovação do token e fazer uma nova tentativa caso o token apresentado esteja inválido.
Requisição HTTP
POST /remote/token
Header
É necessário especificar no header o tipo de conteúdo enviado no body da requisição.
Content-Type
: application/json
Content-Type application/json
Body
{
"auth": {
"username": "teste",
"apiKey": "123mudar"
}
}
Encapsular as propriedades abaixo em um objeto "auth".
Propriedade | Tipo | Obrigatório | Descrição |
---|---|---|---|
username |
Texto | Sim | Identificador do estabelecimento. |
apiKey |
Texto | Sim | Chave para Autenticação de uso exclusivo do estabelecimento. |
Resposta
{
"Bearer": "token"
}
Propriedade | Tipo | Obrigatório | Descrição |
---|---|---|---|
Bearer |
Texto | Sim | Token a ser utilizado no header de criação das transações. |
Erros
Os erros desse método são do tipo HTTP 500
.
Status: 500
Status: 500
{
"success": "false",
"error": "<Error message>"
}
Mensagem | Descrição |
---|---|
USER_TOKEN_NOT_FOUND |
Verifique se o usuário está correto, ou entre em contato com o suporte para um novo usuário da API. |
PASSWORD_INVALID |
Verifique se a chave da API está correta ou peça uma nova. |
Transação Remota
Requisições
A seguir, é possível ter uma visão geral das requisições que fazem parte dos processos de autenticação, registro de uma transação e retorno dos dados:
- Autenticação:
[POST] /remote/token
Para acessar os endpoints da API é necessário apresentar o token da sua aplicação que pode ser obtido através deste método, mediante apresentação das credenciais de acesso fornecidas pelo suporte (username e apiKey)
- Cria uma transação remota:
[POST] /remote/transaction
Cria uma nova transação referente a uma cobrança. Os parâmetros permitem detalhar o modo que a transação será executada e informar o endereço de retorno.
- Retorno dos dados: Callback
Durante todo o ciclo de vida da transação (criação, aprovação/cancelamento, pagamento, etc), os dados da transação referentes às mudanças de estado são enviadas ao endereço informado ao criar a cobrança.
Cria Transação Remota
Para criar uma transação que utilizará cartão de crédito, é necessário enviar uma requisição utilizando o método POST
utilizando no header o token informado além dos dados de uma transação para registro na EvoluServices, conforme o exemplo.
Requisição HTTP
POST /remote/transaction
Header
É necessário especificar no header o tipo de conteúdo enviado no body da requisição, junto com o Bearer.
Parâmetro | Valor |
---|---|
Content-Type |
application/json |
Bearer |
TOKEN |
Content-Type application/json
Bearer TOKEN
Body
public static void main(String[] args) throws IOException {
// JSON com as informações de inicio da transação remota
String rawData = "{'transaction': { 'merchantId': 'ABC123','value': '10.00','installments': '2','paymentBrand': 'VISA_CREDITO'}}";
// Endpoint com somente os atributos necessários setados
URL u = new URL("https://sandbox.evoluservices.com/remote/transaction");
HttpURLConnection conn = (HttpURLConnection) u.openConnection();
conn.setDoOutput(true);
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json; charset=utf8");
conn.setRequestProperty(
"Bearer",
"xyz_456");
OutputStream os = conn.getOutputStream();
os.write(rawData.toString().getBytes("UTF-8"));
os.close();
StringBuilder sb = new StringBuilder();
int HttpResult = conn.getResponseCode();
// Se o resultado for HTTP OK, recebemos uma mensagem de sucesso
if (HttpResult == HttpURLConnection.HTTP_OK) {
BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String line = null;
while ((line = br.readLine()) != null) {
sb.append(line + "\n");
}
br.close();
System.out.println("" + sb.toString());
} else {
// Caso contrário, lemos o código e mensagem de erro
System.out.println(conn.getResponseCode());
System.out.println(conn.getResponseMessage());
}
}
private static void CreateTransaction()
{
HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://sandbox.evoluservices.com/remote/transaction");
request.Method = "POST";
request.ContentType = "application/json";
request.Headers["Bearer"] = "XYZ456";
using (Stream requestStream = request.GetRequestStream())
{
string auth = JsonConvert.SerializeObject(new { transaction = new { merchantId = "ABC123", value = "10.00", installments = "2", paymentBrand = "VISA_CREDITO" } });
byte[] buffer = Encoding.ASCII.GetBytes(auth);
requestStream.Write(buffer, 0, buffer.Length);
}
try
{
using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
{
using (Stream responseStream = response.GetResponseStream())
{
using (StreamReader sr = new StreamReader(responseStream))
{
dynamic transactionApproved = JsonConvert.DeserializeObject<dynamic>(sr.ReadToEnd());
string transactionId = transactionApproved.transactionId.Value;
Debug.WriteLine("TransactionID:" + transactionId);
}
}
}
}
catch (WebException webException)
{
throw new ApiError(webException.Message, ((HttpWebResponse)webException.Response).StatusCode, ((HttpWebResponse)webException.Response).StatusDescription);
}
}
public class ApiError : Exception
{
public HttpStatusCode StatusCode { get; set; }
public string ReasonPhrase { get; set; }
public ApiError(string message, HttpStatusCode statusCode, string reasonPhrase) : base(message)
{
ReasonPhrase = reasonPhrase;
StatusCode = statusCode;
}
}
{
"transaction": {
"merchantId": "<id>",
"terminalId": "<id>",
"value": "10.00",
"installments": 2,
"paymentBrand": "VISA_CREDITO",
"callbackUrl": "<url>",
"clientName": "<name>",
"installmentsCanChange" : "false",
"clientEmail": "<email>",
"splits": [{
"code": "<code>",
"value": "2.00",
"chargeFees": true
}, {
"code": "<code>",
"value": "3.00",
"chargeFees": false
}]
}
}
Propriedade | Tipo | Obrigatório | Descrição | Validação |
---|---|---|---|---|
merchantId |
Texto | Sim | Identificador do estabelecimento (obtido junto ao suporte). | [0-9A-Za-z]+ |
terminalId |
Texto | Não | Id do terminal reponsável por processar a transação. Caso especificado, a transação iniciará automaticamente, caso contrário, uma notificação será exibida nos dispositivos habilitados. A lista de ids pode ser obtida através do método Listar terminais | [0-9A-Za-z+/*]{6,300} |
value |
Número | Sim | Valor do orçamento (em decimal, com o "." como separador e 2 casas decimais). | \d+\.\d{2} |
installments |
Número | Não | Número de parcelas | \d{1,9} |
paymentBrand |
Texto | Não | Bandeira do cartão. Se o número de parcelas for especificado, a bandeira se torna obrigatória. | Tabela de bandeiras |
callbackUrl |
Texto | Não | URL de retorno com os dados da transação após processamento. A URL deve ser https. | URLValidator (Com schema apenas https ) |
clientName |
Texto | Não | Nome do cliente final ao qual a transação pertence. Apesar de não obrigatório, recomenda-se fortemente que esse campo se preenchido. | [0-9A-Za-záéíóúÁÉÍÓÚàèìòùÀÈÌÒÙâêîôûÂÊÎÔÛãõÃÕçÇäëïöüÄËÏÖÜ&!() #%@$+',-.]+ |
installmentsCanChange |
Booleano | Não | Define se o número de parcelas e a bandeira da transação podem ou não ser alterados pelo cliente. | (true|false) |
clientEmail |
Texto | Não | Email do cliente, para onde pode ser enviado o comprovante da venda, opcionalmente | .+ |
splits |
Lista de objetos | Não | Lista contendo informações de split de pagamento para cada beneficiário. | Ver Parâmetros do Split abaixo. |
// Exemplos
{
"paymentBrand" : "MAESTRO", // Transação de débito
},
{
"paymentBrand" : "MASTERCARD", // Transação de crédito
}
Parâmetros do split
Propriedade | Tipo | Obrigatório | Descrição | Validação |
---|---|---|---|---|
code |
Texto | Sim | Código do beneficiário. | [0-9]+ |
value |
Número | Sim | Valor do split destinado ao beneficiário. | \d+\.\d{2} |
chargeFees |
Booleano | Não | Define se aplica taxas sobre o valor do split ou não. Considera como true , caso o campo não seja definido. |
(true|false) |
Resposta
{
"success": "true",
"error": "REMOTE_TRANSACTION_SUCCESS",
"transactionId": "NTcwMA*3"
}
Em caso de sucesso, retorna Status 200 e o json contendo transactionId e mensagem de sucesso.
Erros
Status: 500
Status: 500
{
"success": "false",
"error": "<Error message>"
}
Mensagem | Descrição |
---|---|
PAYMENT_BRAND_ID_INVALID |
A bandeira não existe. |
INSTALLMENTS_INVALID_FOR_DEBIT |
Cartão de débito não pode ter mais de uma parcela. |
INVALID_PAYMENT_BRAND |
A bandeira não está habilitada para o estabelecimento. |
INVALID_INSTALLMENTS_QUANTITY_OR_VALUE |
O número de parcelas ou valor minimo da parcela não é aceito pelo estabelecimento. |
MERCHANT_ID_INVALID |
Id do estabelecimento não existe. |
TERMINAL_ID_INVALID |
Id do terminal não existe. |
MERCHANT_TERMINAL_INVALID |
Terminal do estabelecimento não está apto a receber transações remotas |
VALUE_FIELD_INVALID |
Formato do campo value inválido |
NAME_CLIENT_INVALID |
Campo clientName inválido |
SPLIT_SUM_GREATER_THAN_TRANSACTION_VALUE |
A soma dos valores do split ultrapassam o valor total a receber. |
SUPPLIER_NOT_FOUND |
O código informado não corresponde a um beneficiário existente |
SUPPLIER_INVALID |
O beneficiário informado não está conectado ao estabelecimento |
Callback
Se uma URL for enviada ao criar a transação, um JSON contendo os dados a seguir será enviado via POST quando o status da transação for alterado.
{
"remoteTransactionId": "<id>",
"status": "APPROVED",
"merchantId": "<id>",
"value": "10.00",
"paymentBrand": "VISA_CREDITO",
"transactionNumber": "<transactionNumber>",
"paymentQuantity": "2",
"clientName": "CLIENT_NOT_INFORMED",
"terminalId": "<id>",
"payments": [
{
"status": "UNPAID",
"value": 4.95,
"number": 1,
"date": "21/12/2016",
"recipientName": "<name>",
"recipientDocument": "<document>"
},
{
"status": "UNPAID",
"value": 4.95,
"number": 2,
"date": "21/01/2017",
"recipientName": "<name>",
"recipientDocument": "<document>"
}
],
"splits": [
{
"status": "UNPAID",
"value": 2.35,
"number": 1,
"date": "02/02/2020",
"recipientName": "<name>",
"recipientDocument": "<document>"
},
{
"status": "UNPAID",
"value": 3.15,
"number": 2,
"date": "02/03/2020",
"recipientName": "<name>",
"recipientDocument": "<document>"
}
]
}
Propriedade | Tipo | Descrição |
---|---|---|
remoteTransactionId |
Texto | Identificador da transação. |
transactionNumber |
Texto | Número da transação. |
status |
Texto | Status da transação (consulte a tabela de valores de status). |
merchantId |
Número | Identificador do estabelecimento. |
value |
Número | Valor total da transação. |
paymentBrand |
Texto | Bandeira do cartão (para lista consulte tabela de bandeiras). |
terminalId |
Texto | ID do terminal. |
payments |
Lista de objetos | Pagamentos aos estabelecimentos da transação. |
paymentQuantity |
Número | Número de pagamentos ao estabelecimento. |
splits |
Lista de objetos | Informações ligadas aos splits de pagamento. |
clientName |
Texto | Nome do cliente que passou a transação, quando fornecido. |
NSU |
Número | NSU da transação, disponível apenas depois de aprovada. |
authorizationNumber |
Número | Número de autorização da transação, disponível apenas depois de aprovada. |
Parâmetros dos pagamentos aos estabelecimentos e dos splits
Propriedade | Tipo | Descrição |
---|---|---|
status |
Texto | Status do pagamento. |
value |
Número | Valor destinado ao estabelecimento ou ao beneficiário, no caso do split. |
number |
Número | Número do pagamento. |
date |
Texto | Data estimada de pagamento. |
recipientName |
Texto | Nome do estabelecimento ou do beneficiário, no caso do split. |
recipientDocument |
Texto | Documento do estabelecimento ou do beneficiário, no caso do split. |
Exclui Transação Remota
É possivel remover transações remotas que ainda não foram processadas, enviando uma requisição do tipo Delete para a URL raiz da transação remota.
Requisição HTTP
DELETE /remote/{id}
Parâmetros da URL
Parâmetro | Descrição |
---|---|
id |
Identificador da transação remota (retornada na requisição da transação). |
Erros
Os erros desse método são do tipo HTTP 500
Status: 500
Status: 500
{
"success": "false",
"error": "<Error message>"
}
Mensagem | Descrição |
---|---|
INEXISTENT_REMOTE_TRANSACTION |
Transação remota inexistente |
REMOTE_TRANSACTION_ALREADY_PROCESSED |
Já foi iniciado o processamento da transação remota |
ID_INVALID |
Id da transação inválido |
Acesso na maquininha (POS)
É possível acessar as transações remotas pela máquininha através do menu Operações > Operações remotas. Caso não haja esta opção, vá no menu Contas > Encerrar Sessão e autentique-se novamente.
Terminais
Listar todos os terminais
Retorna os terminais do estabelecimento que estão aptos a receber transação remota.
Requisição HTTP
GET /remote/merchants/{merchantCode}/terminals
Header
Você deve especificar no cabeçalho da requisição o tipo de conteúdo enviado no corpo, bem como o token de acesso.
Parâmetro | Valor |
---|---|
Content-Type |
application/json |
Bearer |
TOKEN |
Content-Type application/json
Bearer TOKEN
Parâmetros da URL
Parâmetro | Descrição |
---|---|
merchantCode |
O código do estabelecimento (obtido junto ao suporte). |
Resposta
[
{
"macAddress": "8d:c1:d3:12:14:bb",
"computerName": "DESKTOP",
"terminalId": "AA009999",
"terminalStatus": "ONLINE"
}
]
Propriedade |
Tipo | Descrição |
---|---|---|
macAddress |
Texto | O endereço físico (MAC Address) associado ao terminal. |
computerName |
Texto | O nome do computador associado ao terminal. |
terminalId |
Texto | O id do terminal que pode ser utilizado como parâmetro para iniciar uma transação remota. |
terminalStatus |
Texto | O status do terminal (consulte a tabela de valores). |
Erros
Os erros desse método são do tipo HTTP 401
e HTTP 500
Status: 401
Status: 401
{
"success": "false",
"error": "<Error message>"
}
Mensagem | Descrição |
---|---|
INVALID_TOKEN |
Token inválido. |
Listar Beneficiários do Split de Pagamentos
Listar os beneficiários
Retorna a lista de beneficiários aptos a receber splits de pagamentos para este estabelecimento.
Requisição HTTP
GET /remote/merchants/{merchantCode}/recipients
Header
Você deve especificar no cabeçalho da requisição o tipo de conteúdo enviado no corpo, bem como o token de acesso.
Parâmetro | Valor |
---|---|
Content-Type |
application/json |
Bearer |
TOKEN |
Content-Type application/json
Bearer TOKEN
Parâmetros da URL
Parâmetro | Descrição |
---|---|
merchantCode |
O código do estabelecimento (obtido junto ao suporte). |
Resposta
[
{
"name": "<name>",
"document": "<document>",
"code": "<code>"
}
]
Propriedade |
Tipo | Descrição |
---|---|---|
name |
Texto | O nome do beneficiário. |
document |
Texto | O documento do beneficiário. |
code |
Texto | O código do beneficiário. |
Erros
Os erros desse método são do tipo HTTP 401
e HTTP 500
Status: 401
Status: 401
{
"success": "false",
"error": "<Error message>"
}
Mensagem | Descrição |
---|---|
INVALID_TOKEN |
Token inválido. |
MERCHANT_CODE_INVALID |
Código do estabelecimento inválido. |
Tabela de valores
Status da transação
Status da Transação | Motivo |
---|---|
APPROVED |
Transação aprovada com sucesso |
CANCELLED |
Transação cancelada pelo estabelecimento |
ABORTED |
Transação abortada devido a erros durante o processamento |
ABORTED_BY_MERCHANT |
Transação abortada pelo estabelecimento |
PARTIALLY_CANCELLED |
Transação parcialmente cancelada |
Status da parcela
Status da Transação | Motivo |
---|---|
PAYED |
Parcela paga |
UNPAID |
Parcela a pagar |
ANTICIPATION_REQUESTED |
Antecipação da parcela solicitada |
ANTICIPATED |
Antecipação da parcela paga |
CANCEL_REQUESTED |
Cancelamento da parcela solicitado |
CANCELLED |
Parcela cancelada |
Status do terminal
Status do Terminal |
Motivo |
---|---|
ONLINE |
Terminal pronto para receber transações. |
ONLINE_DIFFERENT_ACCOUNT |
Terminal está sendo utilizado por outro estabelecimento. Se o terminal está na versão 4.14 ou superior, está apto a receber transações. |
OFFLINE |
Terminal desligado. Transações não serão processadas até que o terminal fique ONLINE (ou ONLINE_DIFFERENT_ACCOUNT para versões superiores a v4.14). |
UNKNOWN |
Terminal em estado desconhecido (retornado para os terminais com versões anteriores a v4.0). |
Bandeira
String da Bandeira | Nome da bandeira |
---|---|
VISA_CREDITO |
Visa |
VISA_ELECTRON |
Visa Electron (Débito) |
MASTERCARD |
MasterCard |
MAESTRO |
MasterCard Maestro (Débito) |
AMEX |
American Express |
DINERS |
Diners |
HIPERCARD |
Hipercard |
AURA |
Aura |
SOROCRED |
Sorocred |
ELO |
Elo |
SICREDI |
Sicred |
ELO_DEBITO |
Elo Débito |
HIPER |
Hiper |
AGIPLAN |
Agiplan |
BANESCARD |
Banescard |
CREDZ |
CredZ |
JCB |
JCB |
CABAL |
Cabal |
MAIS |
Mais |
Erros Gerais
Códigos retornados em caso de erro, identificando o motivo do erro e suas respectivas mensagens.
Os erros desse método são do tipo HTTP 401
e HTTP 500
Status: 401
Status: 401
{
"success": "false",
"error": "<Error message>"
}
Mensagem | Descrição |
---|---|
REVOKED_TOKEN |
O token foi revogado antes da data de expiração. |
INVALID_TOKEN |
O token informado não é igual ao cadastrado. |
EXPIRED_TOKEN |
O token não tem mais validade. |
Status: 500
Status: 500
{
"success": "false",
"error": "<Error message>"
}
Mensagem | Descrição |
---|---|
MERCHANT_NOT_FOUND |
Estabelecimento não encontrado. |
Histórico de revisões
v1.0.7
- Adição da nova seção "Aquisição das chaves"
v1.0.6
- Adição de informações sobre a transação remota na maquininha (POS)
v1.0.5
- Adição do split da transação remota
v1.0.4
- Adição de número de autorização na callback
v1.0.3
- Adição do botão "Run in Postman" com uma coleção de requisições de exemplo
v1.0.2
- Alteração na descrição do parâmetro
paymentBrand
para indicar sua obrigatoriedade caso o número de parcelas for informado - Adição da coluna
validação
na lista de parâmetros ao criar uma transação remota
v1.0.1
- Descrição do parâmetro TerminalId do método RemoteTransaction #create
- Adição do endpoint Terminal #list
v1.0.0
- Versão incial da documentação