Consumption

Serviço responsável pelo monitoramento e pagamento de contas de consumos.

O monitoramente é realizado através da inclusão de contas de consumo com recepção periódica do saldo atualizado e consulta de movimentos para visualização de extrato sob demanda.

O pagamento é realizado através de transações de cartão de crédito para realizar recargas ou pagamentos.

Warning

O aplicativo deve estar preparado para que uma mesma conta de consumo esteja incluída em múltiplas contas de usuário, bem como estar igualmente preparado para que uma mesma conta de usuário esteja ativa simultaneamente em múltiplos aparelhos.

Connect

Testa a conectividade com o serviço.

Parâmetros

Este método não possui nenhum parâmetro de entrada.

Retorno

Tipo	Descrição
Boolean	Retorna verdadeiro se houver conectividade com o servidor. Obrigatório.

AddAccount

Adiciona uma nova conta de consumo para ser monitorada em uma conta de acesso.
As contas de consumos criadas a partir dos ingressos adquiridos pela loja do cliente através da conta de acesso serão automaticamente vinculadas.
O campo NfcUid é obrigatório, caso o código da conta de consumo informado esteja criptografado
O campo NfcUid é opcional, caso o código da conta de consumo informado não esteja criptografado

Parâmetros

Nome	Tipo	Descrição
data	AddAccountData	Dados para adição. Obrigatório.

Retorno

Tipo	Descrição
AddAccountResult	Retorna os dados conta de consumo adicionada. Obrigatório.

RemoveAccount

Remove uma ou mais contas de consumo do monitoramento de uma conta de acesso.
As contas de consumos criadas a partir dos ingressos adquiridos pela loja do cliente através da conta de acesso não poderão ser removidos.

Parâmetros

Nome	Tipo	Descrição
data	RemoveAccountData	Dados para remoção. Obrigatório.

Retorno

Este método não possui retorno.

Refresh

Recebe as atualizações das contas de consumo monitoradas por uma conta de acesso, recebendo:

1. Saldo das contas de consumo monitoradas por uma conta de acesso.
2. As configurações atualizadas que orientam as ações que devem ser realizadas pelo aplicativo. Tais configurações podem ser alteradas a qualquer momento e o aplicativo deve ser preparado para mudanças a cada chamada.

Contas de consumo não retornadas devem ser removidas da visualização do usuário. Esta situação ocorre quando a conta de consumo for removida da conta de acesso através de outro aparelho logado.

Parâmetros

Nome	Tipo	Descrição
data	RefreshData	Dados para atualização. Obrigatório.

Retorno

Tipo	Descrição
RefreshResult	Retorna os dados atualizados das contas de consumo e configurações. Obrigatório.

LoadMovements

Consulta os movimentos de consumo dos últimos 30 dias de uma conta de consumo.
O saldo dos movimentos anteriores a 30 dias são retornados como saldo anterior.

Parâmetros

Nome	Tipo	Descrição
data	LoadMovementsData	Dados para consulta. Obrigatório.

Retorno

Tipo	Descrição
LoadMovementsResult	Retorna os movimentos de consumo realizados. Obrigatório.

LoadPayment

Carrega os dados necessários o pagamento de pós-pago ou recarga de pré-pago nas contas de consumo monitoradas por uma conta de acesso.

Além disso, esse método recebe eventuais atualizações realizadas nas contas de consumo. Este comportamento tem objetivo de evitar nova consulta ao servidor caso tenha havido atualizações e garantir que a função de pagamento seja sempre ativada com as contas de consumo atualizadas.

Parâmetros

Nome	Tipo	Descrição
data	LoadPaymentData	Dados para carregamento. Obrigatório.

Retorno

Tipo	Descrição
LoadPaymentResult	Retorna os dados necessários para realização do pagamento e as últimas atualizações as contas de consumo. Obrigatório.

LoadAcquirerAuthentication

Carrega os parâmetros necessários para compor os dados que serão utilizados no processo de autenticação do SDK (https://developercielo.github.io/manual/3ds)
O processo de autenticação deverá ser implementado de acordo com a documentação da adquirente Cielo, seja para plataforma Android, IOS ou JavaScript.

Android: https://developercielo.github.io/manual/integracao-sdk-android
IOS: https://developercielo.github.io/manual/integracao-sdk-ios
JavaScript: https://developercielo.github.io/manual/integracao-javascript


Fluxo resumido:
1) Realizar chamada ao método LoadAcquirerAuthentication da API antes da efetivação do pagamento, depois de todas as informações do cartão/pagamento terem sido capturadas.
2) Realizar o processo de autenticação do SDK utilizando os parâmetros retornados no método LoadAcquirerAuthentication, juntamente com os parâmetros existentes na própria aplicação, dados do cartão, valores, etc...
3) Usuário poderá interagir (gerenciado pelo SDK) com o popup do desafio (onde algumas informações serão requeridas/confirmadas)
4) Independente do resultado da autenticação no SDK, recomendamos realizar chamada aos métodos de pagamento (PerformPayment/PerformRecharge) passando todas as informações do resultado da autenticação (através do campo AcquirerAuthenticationData) juntamente com o restante das informações de pagamento.
5) A decisão do processamento do pagamento (processar ou descartar, de acordo com o resultado da autenticação) será guiado pela configuração 'Autenticação 3DS' nas configurações da API no MultiClubes.
Para ter acesso ao aplicativo de exemplo da implementação SDK Android, clique aqui.

Parâmetros

Nome	Tipo	Descrição
data	LoadAcquirerAuthenticationData	Dados para carregamento. Obrigatório.

Retorno

Tipo	Descrição
LoadAcquirerAuthenticationResult	Retorna os parâmetros necessários para realização da autenticação. Obrigatório.

PerformPayment

Paga um saldo negativo de uma conta de consumo pós-paga.

Caso a transação de cartão de crédito seja aprovada pela adquirente, o pagamento é realizado e as atualizações serão retornadas. Dentre as atualizações haverá o movimento de consumo de pagamento.
Caso a transação de cartão de crédito seja negada pela adquirente, o pagamento não será realizado e será retornada mensagem de erro contendo o motivo que deve ser exibido para o usuário.

Parâmetros

Nome	Tipo	Descrição
data	PerformPaymentData	Dados para pagamento. Obrigatório.

Retorno

Tipo	Descrição
PaymentResult	Retorna os dados da tentativa de pagamento e as últimas atualizações das contas de consumo caso seja aprovado.

PerformRecharge

Recarrega um valor em uma conta de consumo pré-paga.

Caso a transação de cartão de crédito seja aprovada pela adquirente, a inclusão do valor como recarga é realizado e as atualizações serão retornadas. Dentre as atualizações haverá o movimento de consumo de recarga.
Caso a transação de cartão de crédito seja negada pela adquirente, a inclusão do valor não será realizada e será retornada mensagem de erro contendo o motivo que deve ser exibido para o usuário.

Parâmetros

Nome	Tipo	Descrição
data	PerformRechargeData	Dados para recarga. Obrigatório.

Retorno

Tipo	Descrição
PaymentResult	Retorna os dados da tentativa de recarga e as últimas atualizações das contas de consumo caso seja aprovado.

LoadLimit

Carrega os dados necessários para a alteração de limite crédito em contas de consumo pós-pagas.
O limite máximo de crédito pode ser distribuído entre todas as contas de consumo com limite de crédito, incluindo contas com limite nulos ou zerado.
Contas de consumo não retornadas por este método não podem ter seu limite de crédito alterado.

Parâmetros

Nome	Tipo	Descrição
data	LoadLimitData	Dados para o carregamento. Obrigatório.

Retorno

Tipo	Descrição
LoadLimitResult	Retorna os dados necessários para alteração do limite de crédito pós-pago. Obrigatório.

EditLimit

Altera o limite de crédito em contas de consumo pós-pagas.
Retorna as atualizações acumuladas incluindo a alteração de limite realizada.
Somente contas de consumo retornadas por Consumption.LoadLimit podem ter seus limites de créditos alterados.

Parâmetros

Nome	Tipo	Descrição
data	EditLimitData	Dados para alteração de limite. Obrigatório.

Retorno

Tipo	Descrição
RefreshResult	Retorna os dados atualizados das contas de consumo e configurações. Obrigatório.

Transfer

Transfere saldo para contas de consumo.
Retorna os números de movimentos e a atualização de saldo.

Parâmetros

Nome	Tipo	Descrição
data	PerformTransferData	Dados para transferência de saldo. Obrigatório.

Retorno

Tipo	Descrição
TransferResult	Retorna os dados atualizados das contas de consumo e configurações, e os números de movimento. Obrigatório.

ReverseTransfer

Reverte a transferência de saldo para contas de consumo.

Parâmetros

Nome	Tipo	Descrição
data	ReverseTransferData	Dados para reverter transferência de saldo. Obrigatório.

Retorno

Tipo	Descrição
RefreshResult	Retorna os dados atualizados das contas de consumo e configurações. Obrigatório.

LoadVouchers

Carrega os dados dos vouchers de uma conta.

Parâmetros

Nome	Tipo	Descrição
data	LoadVoucherData	Dados para o carregamento dos vouchers.

Retorno

Tipo	Descrição
LoadVoucherResult[]	Retorna os dados dos vouchers da conta.

Error codes

Códigos de erro retornados pelo serviço

Valores

Nome	Valor	Descrição
UnavailableCloud	0	Não é possível estabelecer conexão com o data center do sistema.
UnavailableMultiVendas	1	Não é possível estabelecer conexão com o servidor de consumo do sistema.
InvalidCreditCardNumber	3	Fornecido como parâmetro um número de cartão de crédito inválido.
InvalidCreditCardType	4	Fornecido como parâmetro uma bandeira de cartão de crédito inválida.
InvalidCardExpiryDate	5	Fornecido como parâmetro uma data de validade de cartão de crédito inválida.
InvalidSecurityCode	6	Fornecido como parâmetro um código de segurança de cartão de crédito inválido.
InvalidConsumptionAccount	7	Fornecido como parâmetro um identificador de conta de consumo inválido.
ConsumptionAccountNotFound	8	Fornecido como parâmetro um identificador de conta de consumo inexistente.
CardDamaged	9	Fornecido como parâmetro um identificador de conta de consumo que possui o cartão ou pulseira de consumo sinalizada como danificada. Essa sinalização ocorre pela operação da conta de consumo no cliente.
InvalidPaymentValue	10	Fornecido como parâmetro um valor de pagamento inválido.
PaymentValueChanged	11	Fornecido como parâmetro um valor de pagamento de conta de consumo pós-pago que não confere com o valor a pagar esperado. Este cenário é observado quando ocorre novos movimentos de consumo após a chamada do método Consumption.LoadPayment e antes efetivamente realizar o pagamento pela chamada do método Consumption.PerformPayment.
InvalidPaymentMode	12	Não existe forma de pagamento de sistema da integração com aplicativo configurado. Este erro ocorre devido a falha de configuração na administração do servidor.
InvalidNfcUid	13	Fornecido como parâmetro uma TAG NFC inválida.
InvalidCardRemoval	14	Fornecido como parâmetro para remoção uma conta de consumo que não pode ser removida pois foi adquirida juntamente com o ingresso de acesso pela loja online.
MaxCreditLimitExceeded	15	Tentativa de alteração de limite de crédito que excede o limite máximo de crédito.
UnauthorizedCreditLimit	16	Tentativa de alteração de limite de crédito não permitida.
InvalidCloudAccount	17	Fornecido como parâmetro um identificador único de conta de acesso inválido.
UnauthorizedCloudAccount	18	Tentativa de operação em uma conta de consumo que não está vinculada a conta de acesso informada.
RequiredCreditCard	19	Nenhum cartão de crédito foi informado.
InvalidRechargeValue	20	Valor de recarga de cartão inválido. Este erro ocorre quando o valor (<conteúdo não suportado>) é diferente do somatório dos valores de cada recarga (<conteúdo não suportado>), ou quando o valor de recarga é maior ou menor que os limites configurados de recarga do cartão de consumo.
InvalidOperation	21	Operação de recarga inválida. Este erro ocorre quando cartão pós-pago não pode receber créditos ou quando não é permitido recarga para cartão com valor de face.
EmptyRechargeData	22	Dados de recarga não fornecidos. Este erro ocorre quando não é passado os dados para recarga.
EmptyConsumptionDueValue	23	Não há valor devido. Este erro ocorre ao tentar pagar um cartão de consumo pós-pago que não possui valor em aberto.
InvalidProductVoucher	24	Produto voucher inválido. Esse erro ocorre ao tentar carregar dados dos vouchers e não encontrar o produto.
PaymentGatewayRulesConflict	25	Este erro ocorre por tentativa de pagamento de duas ou mais contas de consumos que estão configuradas em regras de gateways diferentes.
AcquirerAuthenticationEmptyNewCreditCard	26	Dados do cartão de crédito não fornecidos para autenticação. Ocorre quando o novo cartão não é informado durante o carregamento dos parâmetros de autenticação ou realização de um pagamento autenticado.
ExistingCreditCardNotAllowed	27	Cartão de crédito já cadastrado não autorizado para utilização. Ocorre quando o ambiente não está configurado para reutilizar cartões cadastrados durante os pagamentos.
StoreNewCreditCardNotAllowed	28	Novo cartão de crédito não autorizado para uso futuro. Ocorre quando o ambiente não está configurado para armazenar cartões de crédito para uso futuro.
AcquirerAuthenticationNotAllowed	29	Autenticação não autorizada para uso. Ocorre quando o ambiente não está configurado para utilizar autenticação.
EmptyAcquirerAuthenticationData	30	Dados da autenticação não fornecidos. Ocorre quando os dados retornados da autenticação não são informados corretamente.
AcquirerAuthenticationNotSupported	31	Processo de autenticação não suportado pelo adquirente. Ocorre quando o adquirente não suporta autenticação.
AcquirerAuthenticationLoadError	32	Falha no carregamento dos parâmetros da autenticação. Ocorre quando o adquirente suporte mas houve erro durante o carregamento dos parâmetros de autenticação.
AutenticationKeyMissing	901	Chave de autenticação não informada.
AutenticationKeyInvalid	902	Fornecido como parâmetro uma chave de autenticação inválida. Este erro ocorre quando, a chave não é encontrada, quando a chave informada está incorreta ou quando o usuário associado a chave não possui permissão para utilizar a API.
IntegrationDisabled	903	A integração com o aplicativo está desativada. Este erro ocorre devido a configuração na administração do servidor.