Introdução
Bem-vindo(a) à API de pagamentos da AixMobil!
Disponibilizamos nossa API para que você possa ter acesso a todas as operações para integrar o seu negócio com a nossa plataforma de pagamento.
Nossa plataforma adota rigorosos padrões de segurança e possui a certificação PCI-DSS (o que é), certificação esta que abrange uma extensa lista de requisitos de segurança que precisam ser cumpridas por empresas que processam dados de cartões de pagamento.
Como nossa API é baseada nas mais modernas tecnologias e está sempre atualizada com as melhores práticas de mercado, proporcionamos uma integração mais simples, com menor custo e prazo para implementação da solução.
Esta documentação descreve apenas as operações básicas para realizar as integrações com capturas de pagamentos. Outras operações como consultas de transações, cancelamentos de transações e recorrências, relatórios de vendas e recebimentos podem ser realizadas através da nossa plataforma web da AixMobil ou caso necessite integrar essas outras operações com outro sistema, disponibilizamos a documentação completa da API.
Segurança
nossa API é disponibilizada somente através de ambiente seguro utilizando o protocolo HTTPS, que garante que todos os dados trafegados pela rede até chegarem a nossa infra-estrutura são encriptados.
não armazenamos nenhum dado sensível relacionado ao pagamento, como número do cartão de crédito ou débido, CVV ou data de expiração do cartão. Estes dados são repassados diretamente para as adquirentes responsáveis por aprovar e processar os pagamentos.
da mesma forma que aplicamos as melhores formas de proteger os dados do pagamento e do pagador dentro da nossa infra-estrutura, procuramos estabelecer critérios e boas práticas do lado da entidade que está realizando a integração com a nossa API. A segurança da informação precisa acontecer de ponta a ponta! (Veja nossa documentação de como encriptar dados sensíveis do formulário de pagamento em client-side encryption).
Pré-requisitos
para utilizar nossa API de integração, é necessário fornecer a lista com os endereços IP de origem que farão as requisições para a nossa API, para que sejam liberadas no Firewall, ou seja, nossa API não deve ser chamada diretamente do FrontEnd, como uma tela de checkout de e-commerce.
o endereço web onde a captura dos dados de cartão de crédito ou debito for realizada deve necessariamente possuir um certificado HTTPS.
Configurações
Todos os desenvolvimentos de integração devem ser feitos utilizando os endpoints do ambiente de Testes da AixMobil e apenas direcionados para Produção quando as integrações estiverem finalizadas.
Host de testes: https://api-dev.aixmobil.com/api/
Host de produção: https://api.aixmobil.com/api/
Autenticação
Login
Toda e qualquer interação com os serviços da API deve se feita de forma autenticada, utilizando as credenciais da conta AixMobil cadastrada na plataforma.
Este endpoint autentica as credenciais fornecidas e retorna um token de sessão que deve ser informado nas requisições subsequentes.
curl -X POST https://api.aixmobil.com/api/login \
-H "Content-Type: application/json" \
-d '{
"usuario": "[EMAIL_DE_ACESSO]",
"senha": "[SENHA_DE_ACESSO]"
}'
Requisição HTTP
POST https://api.aixmobil.com/api/login
Cabeçalho da requisição
Atributo | Valor |
---|---|
Content-Type | application/json |
Payload da requisição
Atributo | Tipo | Obrigatório | Descrição |
---|---|---|---|
usuario | String(80) | Sim | E-mail ou username (se o usuário foi criado pela API) do usuário da conta cadastrada na plataforma |
senha | String(40) | Sim | Senha da conta cadastrada |
Status de retorno
Retorno da requisição:
200 OK
{
"token": "[B@459fecb0",
"sucesso": true,
"codigoStatus": 1001,
"mensagem": "Acesso autorizado"
}
Response Status: HTTP_OK (200)
Objeto de retorno
Atributo | Tipo | Descrição |
---|---|---|
token | String(40) | Token de sessão para utilização nas requisições |
sucesso | Boolean | Sucesso da requisição |
codigoStatus | Number(6) | Código de retorno |
mensagem | String(80) | Mensagem de retorno |
Transações
Cartão de crédito
Cria uma transação com cartão de crédito.
Os dados sensíveis do pagamento (número do cartão, data de validade e CVV) devem ser encriptados seguindo as instruções do manual de client-side encryption (CSE).
curl -X POST https://api.aixmobil.com/api/transacoes/encryptCredito \
-H "Content-Type: application/json" \
-H "SessionId: [B@459fecb0" \
-d '{
"idCliente": "998877",
"cartao": "[NUMERO_CARTAO_ENCRIPTADO]",
"portador": "Carlos Aragão",
"cvv": "[CVV_ENCRIPTADO]",
"validade": "[VALIDADE_ENCRIPTADO]",
"valor": 123.45,
"parcelas": 1,
"seuNumero": "123456",
"cpfCnpjPortador": "11111111111",
"dataNascimento": "1978-03-07",
"telefone": 5199998877,
"email": "carlos.aragao@dominio.com.br",
"dadosAdicionais": "Promoção de Natal",
"endereço": {
"logradouro": "Rua dos Atores",
"numero": "123",
"complemento": "Ap. 201 / BL A",
"bairro": "Higienópolis",
"cidade": "Paraíso do Sul",
"estado": "RS",
"cep": "90000000"
},
"checkoutSessionToken": "[TOKEN_SESSAO_RECEBIDO_PELA_LIB_CSE]"
}'
Requisição HTTP
POST https://api.aixmobil.com/api/transacoes/encryptCredito
Cabeçalho da requisição
Atributo | Valor |
---|---|
Content-Type | application/json |
SessionId | [TOKEN_RETORNADO_NO_LOGIN] |
Payload da requisição
Objeto Endereço
Atributo | Tipo | Obrigatório | Descrição |
---|---|---|---|
logradouro | String(120) | Sim | |
numero | String(10) | Não | |
complemento | String(30) | Não | |
cep | String(8) | Sim | CEP contendo apenas números |
bairro | String(40) | Sim | |
cidade | String(60) | Sim | |
estado | String(2) | Sim | Sigla do estado |
Atributo | Tipo | Obrigatório | Descrição |
---|---|---|---|
idCliente | String(40) | Não | Identificação do cliente (sub-conta) na plataforma AixMobil. Se não for informado, assume-se que a transação está relacionada ao cliente logado na sessão. |
cartao | String(512) | Sim | Número do cartão (apenas números) |
portador | String(60) | Sim | Nome do portador do cartão |
cvv | String(512) | Sim | CVV do cartão |
validade | String(512) | Sim | Validade do cartão no formato MM/AAAA |
valor | Number(15,2) | Sim | Valor da transação no formato ######.## (usar "." Como separador decimal) |
parcelas | Number(2) | Sim | Número de parcelas (valor entre 1 e 12) |
seuNumero | String(30) | Não | Campo livre para identificação interna do cliente |
cpfCnpjPortador | String(14) | Sim | CPF/CNPJ do pagador (apenas números) |
telefone | Number(11) | Não | Número de telefone do pagador (apenas números) |
String(120) | Não | E-mail do pagador. Utilizado para o envio do recibo da transação, caso o cliente esteja configurado para receber recibos por e-mail quando a transação é aprovada. | |
dadosAdicionais | String(120) | Não | Campo livre para inclusão de dados adicionais da transação. Conteúdo é exibido no recibo da transação. |
dataNascimento | Date | Não | Data de nascimento do pagador no formato AAAA-MM-DD. É obrigatório apenas se o cliente estiver configurado para ter os CPFs das transações validados na Receita Federal. |
tipoRecorrencia | String(1) | Não | Tipo de recorrência: "D" (diária) "M" (mensal) "A" (anual) "H" (Ad-hoc) Ao selecionar a opção "H" é retornado no response o token do cartão |
periodoRecorrencia | Number(2) | Não | Número de dias / meses / anos para recorrência |
qtdeLimite | Number(2) | Não | Máximo de transações recorrentes a serem geradas (incluindo a primeira) |
dataLimite | Date | Não | Data limite para gerar transações recorrentes no formato AAAA-MM-DD |
endereco | Objeto endereço | Não | Endereço do pagador |
nomeFantasia | String(11) | Não | Nome que aparecerá na fatura do cartão, após o nome "AIXMOBIL*". Exemplo: AIXMOBIL*LOJAS123. |
Status de retorno
Retorno da requisição:
201 CREATED
{
"sucesso": true,
"codigoStatus": 50201,
"mensagem": "Pagamento realizado com sucesso!",
"idTransacao": 100,
"valorLiquido": 117.28,
"tarifa": 6.17,
"endereço": {
"logradouro": "Rua dos Atores",
"numero": "123",
"complemento": "Ap. 201 / BL A",
"bairro": "Higienópolis",
"cidade": "Paraíso do Sul",
"estado": "RS",
"cep": "90000000"
},
"cartao": "1234 56** **** 7890",
"modalidade": "CRE",
"autorizacao": "12345678",
"qtdeParcelas": 1,
"dataHora": 1541595588912
}
Response Status: HTTP_CREATED (201)
Objeto de retorno
Atributo | Tipo | Descrição |
---|---|---|
sucesso | Boolean | Sucesso da requisição |
codigoStatus | Number(6) | Código de retorno |
mensagem | String(80) | Mensagem de retorno |
idTransacao | Number(32) | Identificação da transação na plataforma |
tokenCartao | String(80) | Token gerado para o cartão (somente quando houver recorrência) |
sequencial | Number(10) | Número sequencial da transação (somente quando houver recorrência) |
tarifa | Number(15,2) | Valor a ser descontado sobre o valor bruto da transação, de acordo com o plano do cliente |
valorLiquido | Number(15,2) | Valor da transação descontadas as tarifas incidentes sobre a mesma |
endereco | Objeto Endereço | Endereço do pagador |
cartao | String(16) | Número do cartão truncado, seguro para exibição |
bandeira | Number(3) | Identificação da bandeira do cartão (ver códigos na tabela de valores) |
autorizacao | String(20) | Código de autorização retornado pela processadora de cartão |
modalidade | String(3) | Modalidade de pagamento (CRE) |
qtdeParcelas | Number(2) | Número de parcelas (valor entre 1 e 12) |
dataHora | String ??? | Timestamp representando a data e hora do pagamento |
Cartão de débito
Diferente das transações de crédito, nas operações de débito a criação da transação e autorização ocorrem em momentos distintos.
Esta operação realiza a criação da transação de débito e, ao término desta operação, devolve um link no atributo urlAutenticacao
que precisa ser aberto para o pagador poder confirmar o pagamento através da digitação do código do cartão de débito.
Após a confirmação da senha, a página do banco emissor redireciona o pagador para a página informada no campo urlCallback
da requisição e é a partir deste momento que a consulta da transação pode ser realizada para saber se a autorização ocorreu com sucesso.
Os dados sensíveis do pagamento (número do cartão e data de validade) devem ser encriptados seguindo as instruções do manual de client-side encryption (CSE).
curl -X POST https://api.aixmobil.com/api/transacoes/encryptDebito \
-H "Content-Type: application/json" \
-H "SessionId: [B@459fecb0" \
-d '{
"idCliente": "998877",
"cartao": "[NUMERO_CARTAO_ENCRIPTADO]",
"portador": "Carlos Aragão",
"validade": "[VALIDADE_ENCRIPTADO]",
"valor": 123.45,
"parcelas": 1,
"seuNumero": "123456",
"cpfCnpjPortador": "11111111111",
"dataNascimento": "1978-03-07",
"telefone": 5199998877,
"email": "carlos.aragao@dominio.com.br",
"dadosAdicionais": "Promoção de Natal",
"urlCallback": "http://www.meusite.com.br/recibo",
"endereço": {
"logradouro": "Rua dos Atores",
"numero": "123",
"complemento": "Ap. 201 / BL A",
"bairro": "Higienópolis",
"cidade": "Paraíso do Sul",
"estado": "RS",
"cep": "90000000"
},
"checkoutSessionToken": "[TOKEN_SESSAO_RECEBIDO_PELA_LIB_CSE]"
}'
Requisição HTTP
POST https://api.aixmobil.com/api/transacoes/encryptDebito
Cabeçalho da requisição
Atributo | Valor |
---|---|
Content-Type | application/json |
SessionId | [TOKEN_RETORNADO_NO_LOGIN] |
Payload da requisição
Objeto Endereço
Atributo | Tipo | Obrigatório | Descrição |
---|---|---|---|
logradouro | String(120) | Sim | |
numero | String(10) | Não | |
complemento | String(30) | Não | |
cep | String(8) | Sim | CEP contendo apenas números |
bairro | String(40) | Sim | |
cidade | String(60) | Sim | |
estado | String(2) | Sim | Sigla do estado |
Atributo | Tipo | Obrigatório | Descrição |
---|---|---|---|
idCliente | String(40) | Não | Identificação do cliente (sub-conta) na plataforma AixMobil. Se não for informado, assume-se que a transação está relacionada ao cliente logado na sessão. |
cartao | String(512) | Sim | Número do cartão (apenas números) |
g | portador | String(60) | Sim |
validade | String(512) | Sim | Validade do cartão no formato MM/AAAA |
valor | Number(15,2) | Sim | Valor da transação no formato ######.## (usar "." Como separador decimal) |
parcelas | Number(2) | Sim | Número de parcelas (valor entre 1 e 12) |
seuNumero | String(30) | Não | Campo livre para identificação interna do cliente |
cpfCnpjPortador | String(14) | Sim | CPF/CNPJ do pagador (apenas números) |
telefone | Number(11) | Não | Número de telefone do pagador (apenas números) |
String(120) | Não | E-mail do pagador. Utilizado para o envio do recibo da transação, caso o cliente esteja configurado para receber recibos por e-mail quando a transação é aprovada. | |
dadosAdicionais | String(120) | Não | Campo livre para inclusão de dados adicionais da transação. Conteúdo é exibido no recibo da transação. |
dataNascimento | Date | Não | Data de nascimento do pagador no formato AAAA-MM-DD. É obrigatório apenas se o cliente estiver configurado para ter os CPFs das transações validados na Receita Federal. |
urlCallback | String(240) | Não | A plataforma faz uma requisição GET para a URL informada retornando as propriedades idTransacao , tokenCartao e seuNumero na querystring. Esta URL só é chamada se a cobrança for realizada de forma agendada, como uma cobrança no crédito utilizando o token do cartão ou nos pagamentos de débito ou boleto. |
endereco | Objeto endereço | Não | Endereço do pagador |
nomeFantasia | String(11) | Não | Nome que aparecerá na fatura do cartão, após o nome "AIXMOBIL*". Exemplo: AIXMOBIL*LOJAS123. |
Status de retorno
Retorno da requisição:
201 CREATED
{
"sucesso": true,
"codigoStatus": 50203,
"mensagem": "Transação criada com sucesso!",
"idTransacao": 100,
"urlAutenticacao": "https://ecommerce.cielo.com.br/web/index.cbmp?id=XXX…",
"endereço": {
"logradouro": "Rua dos Atores",
"numero": "123",
"complemento": "Ap. 201 / BL A",
"bairro": "Higienópolis",
"cidade": "Paraíso do Sul",
"estado": "RS",
"cep": "90000000"
}
}
Response Status: HTTP_CREATED (201)
Objeto de retorno
Atributo | Tipo | Descrição |
---|---|---|
sucesso | Boolean | Sucesso da requisição |
codigoStatus | Number(6) | Código de retorno |
mensagem | String(80) | Mensagem de retorno |
idTransacao | Number(32) | Identificação da transação na plataforma |
urlAutenticacao | String(240) | Endereço para onde o pagador deve ser redirecionado para realizar a autorização da transação. A autorização é feita no ambiente do banco emissor do cartão conforme bandeira selecionada. |
endereco | Objeto Endereço | Endereço do pagador |
Boleto
Cria uma transação cuja forma de pagamento será o Boleto Bancário.
Este serviço realiza o registro do boleto bancário e disponibiliza a imagem do mesmo para ser visualizada/salva através do link retornado no parâmetro urlAutenticacao
.
O acesso ao link de exibição do boleto retornará como não encontrado após seu vencimento ou caso já tenha sido pago.
Consultas de status desta transação retornarão com status Pendente até que seja pago e compensado pela plataforma AixMobil. Após sua compensação, a consulta retornará com o status Aprovado. Caso o boleto não seja pago até o vencimento, o título será baixado e sua consulta retornará com o status Cancelado.
curl -X POST https://api.aixmobil.com/api/transacoes/boleto \
-H "Content-Type: application/json" \
-H "SessionId: [B@459fecb0" \
-d '{
"idCliente": "998877",
"portador": "Carlos Aragão",
"valor": 123.45,
"seuNumero": "123456",
"cpfCnpjPortador": "11111111111",
"dataNascimento": "1978-03-07",
"telefone": 5199998877,
"email": "carlos.aragao@dominio.com.br",
"dataLimite": "2018-02-20",
"tipoTitulo": "DS",
"dadosAdicionais": "NÃO RECEBER APÓS O VENCIMENTO.",
"endereço": {
"logradouro": "Rua dos Atores",
"numero": "123",
"complemento": "Ap. 201 / BL A",
"bairro": "Higienópolis",
"cidade": "Paraíso do Sul",
"estado": "RS",
"cep": "90000000"
}
}'
Requisição HTTP
POST https://api.aixmobil.com/api/transacoes/boleto
Cabeçalho da requisição
Atributo | Valor |
---|---|
Content-Type | application/json |
SessionId | [TOKEN_RETORNADO_NO_LOGIN] |
Payload da requisição
Objeto Endereço
Atributo | Tipo | Obrigatório | Descrição |
---|---|---|---|
logradouro | String(120) | Sim | |
numero | String(10) | Não | |
complemento | String(30) | Não | |
cep | String(8) | Sim | CEP contendo apenas números |
bairro | String(40) | Sim | |
cidade | String(60) | Sim | |
estado | String(2) | Sim | Sigla do estado |
Atributo | Tipo | Obrigatório | Descrição |
---|---|---|---|
idCliente | String(40) | Não | Identificação do cliente (subconta) na plataforma AixMobil. Se não for informado, assume-se que a transação está relacionada ao cliente logado na sessão. |
portador | String(60) | Sim | Nome do pagador |
valor | Number(15,2) | Sim | Valor da transação no formato ######.## (usar "." Como separador decimal) |
seuNumero | String(30) | Não | Campo livre para identificação interna do cliente |
cpfCnpjPortador | String(14) | Sim | CPF/CNPJ do pagador (apenas números) |
telefone | Number(11) | Não | Número de telefone do pagador (apenas números) |
String(120) | Não | E-mail do pagador. Utilizado para o envio do recibo da transação, caso o cliente esteja configurado para receber recibos por e-mail quando o boleto é compensado. | |
dataLimite | Date | Não Default (D+10) |
Data de validade do boleto no formato AAAA-MM-DD |
tipoTitulo | String(3) | Sim | Ver tabela Espécie Título |
dadosAdicionais | String(120) | Não | Campo livre para inclusão de dados adicionais na transação. É exibido na área de instruções de pagamento do boleto. |
dataNascimento | Date | Não | Data de nascimento do pagador no formato AAAA-MM-DD. É obrigatório apenas se o cliente estiver configurado para ter os CPFs das transações validados na Receita Federal. |
endereco | Objeto endereço | Sim | Endereço do pagador |
Status de retorno
Retorno da requisição:
201 CREATED
{
"sucesso": true,
"codigoStatus": 50203,
"mensagem": "Transação criada com sucesso!",
"idTransacao": 100,
"urlAutenticacao": "https://ecommerce.cielo.com.br/web/index.cbmp?id=XXX…",
"endereço": {
"logradouro": "Rua dos Atores",
"numero": "123",
"complemento": "Ap. 201 / BL A",
"bairro": "Higienópolis",
"cidade": "Paraíso do Sul",
"estado": "RS",
"cep": "90000000"
}
}
Response Status: HTTP_CREATED (201)
Objeto de retorno
Atributo | Tipo | Descrição |
---|---|---|
sucesso | Boolean | Sucesso da requisição. Neste momento o boleto é registrado e a transação permanece com status Pendente |
codigoStatus | Number(6) | Código de retorno |
mensagem | String(80) | Mensagem de retorno |
idTransacao | Number(32) | Identificação da transação na plataforma |
endereco | Objeto Endereço | Endereço do pagador |
Tabelas de valores
Bandeiras
Bandeiras associadas à cartões de crédito e débito aceitas na plataforma de pagamento da AixMobil.
Código | Descrição |
---|---|
1 | VISA |
2 | MASTERCARD |
3 | ELO |
4 | DINERS |
Tipos de espécie de título (boletos)
Possíves tipos de espécie relacionados a um boleto.
Código | Descrição |
---|---|
DM | Duplicata Mercantil |
DS | Duplicata de Serviço |
ND | Nota de Débito |
REC | Recibo |