Introdução


# EXEMPLOS
                

Integre e crie a melhor experiência com serviços financeiros.

Permitimos que você desenvolva de maneira rápida, simples e com poucas linhas de código as melhores soluções em serviços financeiros. Uma plataforma whitelabel para soluções de pagamentos sem burocracia.

Atendemos ao mais alto padrão da Certificação PCI, o PCI DSS Level 1, para garantir a proteção dos dados de cartão utilizados.

Para testar sua integração disponibilizamos uma tabela de cartões de crédito onde poderá ser simulado no seu ambiente de teste, transações efetuadas com sucesso, transações negadas, etc.

Esse ambiente é uma cópia exata do ambiente de produção, porém os cartões de crédito e as contas bancárias não são cobrados.

Os seguintes números de cartão de crédito podem ser usados para simular transações em ambiente de teste (sandbox), para pagamentos bem-sucedidos:

Número Bandeira
4539003370725497 Visa (Digitada)
4761340000000035 Visa (Chip & PIN)
4716588836362104 Visa (Crédito)
4532650104137832 Visa Electron (Crédito)
5356066320271893 MasterCard (Digitada)
5201561050024014 MasterCard (Chip & PIN)
5577270004286630 MasterCard (Crédito)
5138692036125449 MasterCard (Crédito)

Além disso, esses são os números "mágicos" de cartões que gerarão respostas específicas, úteis para testar diferentes cenários:

Número Bandeira
6011457819940087 A transação será recusada com um código de "card_declined".
4929710426637678 A transação será recusada com um código "card_declined".
4710426743216178 A transação será recusada com um código "service_request_timeout".

Com isso você reduz o seu time-to-market para atuar em serviços financeiros, sem a necessidade de se preocupar com os aspectos regulatórios.

Autenticação

Para utilizar esta API, você precisará de uma Secret Key. Por favor, nos contate por e-mail solicitando a criação da sua Secret key.

A Secretkey é uma chave única que identifica e autoriza o estabelecimento comercial na plataforma. Se seu marktplace realiza transações para múltiplos estabelecimentos comerciais, é necessário uma Secret Key para cada estabelecimento.

Nos casos de transações que realizam split (divisão de valores entre estabelecimentos) somente é necessário a Secret Key do estabelecimento comercial principal que origina as transações.

Toda requisição recebida que não esteja em HTTPS será considerada comprometida pelo nosso sistema e irá falhar.

Envio de Parâmetros

Integrar seu sistema às nossas APIs é muito fácil.

Todos os parâmetros podem ser passados pelos métodos GET e POST. Usando método GET é possível fazer testes de integração usando o navegador web.

(a) Método GET: os parâmetros são passados no URL, como query string.
Exemplo: https://integration.com?param1=value1&param2=value2

(b) Método POST: é possível passar como: (1) Formulários web (browser envia parâmetros como x-www-form-urlencoded ou FormData) ou, (2) Objeto JSON passado no post parâmetro.
Exemplo: { "param1": "value1", "param2":"value2"}.

Autenticação de Estabelecimentos Comerciais

A chave secreta (secret_key) é importante para operações usando API porque ela funciona como uma senha para o Estabelecimento Comercial originar vendas.

A chave secreta (secret_key) é usada para provar que você tem permissão para acessar informações.

SOLICITAR CHAVE SECRETA


REQUEST

{
    "action": "getkey",
    "secret_key": "1oi1oi2",
    "reference": "10000002",
    "taxId": "28781628030"
}


                    

POST api.ezcale.com/v1/auth


Solicitar chave secreta de um Estabelecimento Comercial através do seu CNPJ/CPF.

PARAMS

Campo Tipo Descrição
action string required
Ação a ser tomada
secret_key string required
A chave da API relacionada ao seller.
reference string required
Identificador único para cada requisição via API, este identificador não pode ser reutilizado.
taxId string optional
CPF do portador do cartão.

Carteira Digital

A carteira digital é uma forma segura de armazenar seus cartões de crédito para compras online.

Ela permite que você armazene todos os seus cartões de crédito em um só lugar, de forma segura e prática. Não é necessário lembrar os números e códigos de todos os cartões, pois a carteira digital os armazena de forma segura utilizando criptografia PCI-DSS Level 1, tornando-os completamente seguros.

Além disso, a carteira digital permite que você faça compras online de forma rápida e fácil. Ao usar a carteira digital, você não precisa preencher os números e códigos de seus cartões toda vez que for realizar uma compra, basta informar o identificador do cartão armazenado na carteira digital e pronto.

CRIAR NOVO MÉTODO DE PAGAMENTO


REQUEST

{
    "action": "create_method",
    "secret_key": "1oi1oi2",
    "reference": "10000002",
    "test": true,
    "walletExternalReference": "AH726422asfasfas",
    "holder_name": "Helio Musk",
    "taxId": "28781628030",
    "card_number": "5356066320271893",
    "expiration_month": "09",
    "expiration_year": "2044",
    "security_code": "222"
}


                    

POST api.ezcale.com/v1/wallet


Criar novo método de pagamento, armazenando um cartão de crédito de forma segura.

PARAMS

Campo Tipo Descrição
action string required
Ação a ser tomada
secret_key string required
A chave da API relacionada ao seller.
reference string required
Identificador único para cada requisição via API, este identificador não pode ser reutilizado.
test boolean optional
Flag para requisicões direcionadas ao ambiente de testes.
walletExternalReference string required
Referência externa para identificar a qual carteira digital o método de pagamento pertence.
holder_name string optional
Nome do portador do cartão (como está no cartão).
taxId string optional
CPF do portador do cartão.
card_number string optional
Número do cartão.
expiration_month string optional
Mês de vencimento.
expiration_year string optional
Ano de vencimento.
security_code string optional
Código de segurança do cartão.

LISTAR MÉTODOS DE PAGAMENTO DE UMA CARTEIRA DIGITAL


REQUEST

{
    "action": "list_methods",
    "secret_key": "19412biou",
    "reference": "10000200001",
    "walletExternalReference": "AH726422asfasfas"
}


                    

POST api.ezcale.com/v1/wallet


Listar transações associadas ao seller.

PARAMS

Campo Tipo Descrição
action string required
Ação a ser tomada
secret_key string required
A chave da API relacionada ao seller.
reference string required
Identificador único para cada requisição via API, este identificador não pode ser reutilizado.
walletExternalReference string required
Referência externa para identificar a qual carteira digital o método de pagamento pertence.

DESCARTAR MÉTODO DE PAGAMENTO DE UMA CARTEIRA DIGITAL


REQUEST

{
    "action": "dispose_method",
    "secret_key": "19412biou",
    "reference": "10000200001",
    "walletExternalReference": "AH726422asfasfas",
    "idCard": "13i19a"
}


                    

DELETE api.ezcale.com/v1/wallet


Descartar método de pagamento de uma carteira digital. Ele não poderá ser utilizado novamente.

PARAMS

Campo Tipo Descrição
action string required
Ação a ser tomada
secret_key string required
A chave da API relacionada ao seller.
reference string required
Identificador único para cada requisição via API, este identificador não pode ser reutilizado.
walletExternalReference string required
Referência externa para identificar a qual carteira digital o método de pagamento pertence.
idCard string required
Código / hash que representa o método de pagamento.

Transacional

A carteira digital é uma forma segura de armazenar seus cartões de crédito para compras online.

Ela permite que você armazene todos os seus cartões de crédito em um só lugar, de forma segura e prática. Não é necessário lembrar os números e códigos de todos os cartões, pois a carteira digital os armazena de forma segura utilizando criptografia PCI-DSS Level 1, tornando-os completamente seguros.

Além disso, a carteira digital permite que você faça compras online de forma rápida e fácil. Ao usar a carteira digital, você não precisa preencher os números e códigos de seus cartões toda vez que for realizar uma compra, basta informar o identificador do cartão armazenado na carteira digital e pronto.

PRÉ-CAPTURAR TRANSAÇÃO EM CARTÃO DE CRÉDITO


REQUEST

{
    "action": "preauth",
    "secret_key": "12222222",
    "reference": "13nro1i2n49",
    "test": true,
    "type": "credit",
    "installments": "1",
    "amountInCents": "10000",
    "idCard": "104gs1"
}


                    

POST api.ezcale.com/v1/transactions


Pré-capturar venda em cartão de crédito.

PARAMS

Campo Tipo Descrição
action string required
Ação a ser tomada
secret_key string required
A chave da API relacionada ao seller.
reference string required
Identificador único para cada requisição via API, este identificador não pode ser reutilizado.
test boolean optional
Flag para requisicões direcionadas ao ambiente de testes.
type string required
Tipo da Operação
installments integer required
Quantidade de parcelas da venda.
amountInCents integer required
Valor em centavos da venda.
idCard string required
Código / hash que representa o método de pagamento.

AUTORIZAR TRANSAÇÃO EM CARTÃO DE CRÉDITO


REQUEST

{
    "action": "auth",
    "secret_key": "12222222",
    "reference": "13nro1i2n49",
    "test": true,
    "type": "credit",
    "installments": "1",
    "amountInCents": "10000",
    "walletExternalReference": "AH726422asfasfas",
    "transactionId": "197241nsasd",
    "idCard": "104gs1"
}


                    

POST api.ezcale.com/v1/transactions


Autorizar transação em cartão de crédito.

PARAMS

Campo Tipo Descrição
action string required
Ação a ser tomada
secret_key string required
A chave da API relacionada ao seller.
reference string required
Identificador único para cada requisição via API, este identificador não pode ser reutilizado.
test boolean optional
Flag para requisicões direcionadas ao ambiente de testes.
type string required
Tipo da Operação
installments integer required
Quantidade de parcelas da venda.
amountInCents integer required
Valor em centavos da venda.
walletExternalReference string required
Referência externa para identificar a qual carteira digital o método de pagamento pertence.
transactionId string optional
identificador único da Venda
idCard string required
Código / hash que representa o método de pagamento.

VENDA COM PIX


REQUEST

{
    "action": "createpix",
    "secret_key": "12222222",
    "reference": "13nro1i2n49",
    "amountInCents": "10000"
}


                    

POST api.ezcale.com/v1/transactions


Vender com PIX. Nesta modalidade não é possível enviar o parâmetro de teste ('test')

PARAMS

Campo Tipo Descrição
action string required
Ação a ser tomada
secret_key string required
A chave da API relacionada ao seller.
reference string required
Identificador único para cada requisição via API, este identificador não pode ser reutilizado.
amountInCents integer required
Valor em centavos da venda.

DETALHES DA TRANSAÇÃO


REQUEST

{
    "action": "details",
    "secret_key": "12222222",
    "reference": "13nro1i2n49",
    "test": true,
    "transactionId": "1asnfi"
}


                    

GET api.ezcale.com/v1/transactions


Verificar status e outras informações de uma transação em cartão de crédito ou PIX.

PARAMS

Campo Tipo Descrição
action string required
Ação a ser tomada
secret_key string required
A chave da API relacionada ao seller.
reference string required
Identificador único para cada requisição via API, este identificador não pode ser reutilizado.
test boolean optional
Flag para requisicões direcionadas ao ambiente de testes.
transactionId string optional
identificador único da Venda

ESTORNAR TRANSAÇÃO


REQUEST

{
    "action": "void",
    "secret_key": "12222222",
    "reference": "13nro1i2n49",
    "test": true,
    "transactionId": "1asnfi",
    "amountInCents": "10000"
}


                    

DELETE api.ezcale.com/v1/transactions


Estornar transação em cartão de crédito ou PIX.

PARAMS

Campo Tipo Descrição
action string required
Ação a ser tomada
secret_key string required
A chave da API relacionada ao seller.
reference string required
Identificador único para cada requisição via API, este identificador não pode ser reutilizado.
test boolean optional
Flag para requisicões direcionadas ao ambiente de testes.
transactionId string optional
identificador único da Venda
amountInCents integer required
Valor em centavos da venda.

Credenciamento de Estabelecimentos Comerciais

Ao criar um novo Estabelecimento Comercial utilizando a API, as informações podem ser facilmente enviadas para o sistema do adquirente, sem a necessidade de inserir dados de forma manual. Garantindo a segurança e privacidade das informações

CREDENCIAR ESTABELECIMENTO COMERCIAL


REQUEST

{
    "test": true,
    "secret_key": "1oi1oi2",
    "action": "register",
    "reference": "10000003",
    "taxtype": "CNPJ",
    "ein": "26.982.099/0001-68",
    "business_name": "Loja de Testes 1234",
    "business_description": "Loja de Testes 123",
    "statement_descriptor": "Loja de Testes 123",
    "business_opening_date": "2023-02-13",
    "mcc": "29",
    "revenue": "10.000",
    "business_address-line1": "Rua Gonçalves Dias",
    "business_address-line2": "2064",
    "business_address-line3": "Sala 1",
    "business_address-neighborhood": "Jardim Primavera",
    "business_address-city": "Araraquara",
    "business_address-state": "SP",
    "business_email": "lojatester@gmail.com",
    "business_phone": "(16) 99405-7318",
    "business_address-postal_code": "14.802-416",
    "business_address-country_code": "BR",
    "owner-taxpayer_id": "961.818.181-20",
    "owner-first_name": "Patricia",
    "owner-last_name": "Ferreira",
    "owner-birthdate": "1982-06-14",
    "owner-phone_number": "(16) 99405-7318",
    "owner-email": "donadaloja@gmail.com",
    "bank_code": "341",
    "routing_number": "0001",
    "account_number": "2179067",
    "accType": "checking"
}


                    

POST api.ezcale.com/v1/sellers


Credenciar Estabelecimento Comercial na adquirente.

PARAMS

Campo Tipo Descrição
test boolean optional
Flag para requisicões direcionadas ao ambiente de testes.
action string required
Ação a ser tomada
secret_key string required
A chave da API relacionada ao seller.
reference string required
Identificador único para cada requisição via API, este identificador não pode ser reutilizado.
taxtype string optional
Tipo de cadastro, CNPJ ou CPF
ein string required
CNPJ ou CPJ
business_name string required
Razão Social
business_description optional
statement_descriptor string required
Descrição na fatura do cartão
business_opening_date string required
Data de abertura da empresa
mcc string required
Código de atividade do negócio
revenue string required
Receita mensal do Estabelecimento Comercial
business_address-line1 string required
Logradouro
business_address-line2 string required
Número
business_address-line3 string required
Complemento
business_address-neighborhood string required
Bairro
business_address-city string required
Cidade
business_address-state string required
Estado
business_email string required
Email comercial
business_phone string required
Telefone comercial
business_address-postal_code string required
CEP
business_address-country_code string required
Código do País
owner-taxpayer_id string required
CPF do representante legal
owner-first_name string required
Primeiro nome do representante legal
owner-last_name string required
Sobrenome do representante legal
owner-birthdate string required
Data de nascimento do representante legal
owner-phone_number string required
Telefone comercial do representante legal
owner-email string required
Email do representante legal
bank_code string optional
Código do banco
routing_number string optional
Agência Bancária
account_number string optional
Número da Conta bancária
accType string optional
Tipo da Conta bancária, conta corrente ou poupança

DETALHES DO ESTABELECIMENTO COMERCIAL


REQUEST

{
    "test": true,
    "secret_key": "1oi1oi3",
    "action": "details",
    "reference": "10000004"
}


                    

POST api.ezcale.com/v1/sellers


Verificar informações do Estabelecimento Comercial na adquirente.

PARAMS

Campo Tipo Descrição
test boolean optional
Flag para requisicões direcionadas ao ambiente de testes.
action string required
Ação a ser tomada
secret_key string required
A chave da API relacionada ao seller.
reference string required
Identificador único para cada requisição via API, este identificador não pode ser reutilizado.