Serviço de criação de loja
Após obter o token ou assinatura na etapa anterior, a loja virtual deve enviar os dados da loja a ser criada no Carat e no SiTef (caso necessário).
Atenção:
As lojas cadastradas terão as mesmas configurações de personalização da loja cadastradora, como seu logotipo, CSS e JS.
Detalhes da chamada#
- Recurso:
/v1/merchants - Método HTTP:
POST - Formato da requisição:
JSON - Formato da resposta:
JSON - Parâmetros de cabeçalho:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
merchant_id | Código da loja no Carat. Os códigos de produção e certificação serão diferentes. | < 15 AN | SIM |
merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | < 80 AN | SIM |
token | Token obtido na etapa anterior, caso a autenticação seja via post de autenticidade Saiba mais. | = 66 AN | NÃO |
Content-Type | Deve ser enviado com o valor application/json. | = 15 AN | SIM |
Authorization | Deve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg. | < 2000 AN | NÃO |
Atenção:
Durante a criação de loja, as configurações relativas ao uso de 3DS e antifraude são automaticamente replicadas a partir da loja cadastradora.
Exemplo utilizando token#
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Exemplo utilizando assinatura#
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Parâmetros de requisição#
Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de criação de loja:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
cnpj | CNPJ ou CPF da loja. Apenas números. | < 14 N | SIM |
force_sitef_merchant_creation | Se informado o valor true, aciona geração alternativa de números de empresa permitindo cadastrar mais de uma empresa para o mesmo CNPJ/CPF. Se não informado, assume false, ou seja, utiliza o algoritmo padrão para geração de código de empresa, que garante uma empresa para cada CNPJ/CPF. Enviar true ou false. | < 5 AN | NÃO |
fantasy_name | Nome fantasia da loja. | < 250 AN | SIM |
corporate_name | Razão social da loja. | < 250 AN | SIM |
domain | Domínio (site) da loja. | < 500 AN | NÃO |
address | Endereço da loja. | < 200 AN | NÃO |
city | Cidade da loja. | < 50 AN | NÃO |
state | Estado da loja (sigla). | = 2 AN | NÃO |
zip_code | CEP da loja. | < 9 AN | NÃO |
phone_number | Telefone da loja. | < 30 AN | NÃO |
email | Endereço de e-mail da loja. | < 100 AN | NÃO |
mcc | Merchant Category Code - código que indica a categoria do estabelecimento (utilizado no cadastro de antifraude). Caso o campo threeds_enabled=true, o mcc passa a ser obrigatório. Se o valor enviado possuir que menos 4 dígitos, serão adicionado zeros a esquerda do número até completar tamanho 4. | = 4 N | NÃO |
threeds_enabled | Habilita a loja para integrar com o 3DS Server e realiza as configurações necessárias no Carat, enviar true ou false. Saiba mais. | < 5 AN | NÃO |
threeds_payment_link_authentication | Tipo de autenticação padrão que será exibida na geração de link de pagamento no portal do lojista. Saiba mais.
| = 1 N | NÃO |
automatic_threeds_minimum_value | Indica o valor mínimo em centavos de uma transação para que seja habilitada automaticamente o 3DS. Atenção: intervalos que possibilitem a utilização de 3ds e antifraude juntos não devem ser utilizados. | < 12 N | NÃO |
automatic_threeds_maximum_value | Indica o valor máximo em centavos de uma transação para que seja habilitada automaticamente o 3DS. Atenção: intervalos que possibilitem a utilização de 3ds e antifraude juntos não devem ser utilizados. | < 12 N | NÃO |
automatic_antifraud_minimum_value | Indica o valor mínimo em centavos de uma transação para que seja habilitada automaticamente o Antifraude. Atenção: intervalos que possibilitem a utilização de 3ds e antifraude juntos não devem ser utilizados. | < 12 N | NÃO |
automatic_antifraud_maximum_value | Indica o valor máximo em centavos de uma transação para que seja habilitada automaticamente o Antifraude. Atenção: intervalos que possibilitem a utilização de 3ds e antifraude juntos não devem ser utilizados. | < 12 N | NÃO |
antifraud_over_threeds | Flag que liga a funcionalidade de ativar o antifraude automaticamente em caso de erro ou autenticação negada utilizando o 3DS Server integrado com o Carat | < 5 AN | NÃO |
version | Especifica a versão em que a loja será configurada. Caso este campo não seja enviado, será atribuído o valor configurado na loja cadastradora. Somente são aceitos os valores 4 ou 5 | 1 N | NÃO |
| soft_descriptor | Dados do sub-comércio. | ||
id | ID do sub-comércio. | < 22 AN | NÃO |
country | País do sub-comércio. Código numérico ISO 3166-1. | = 3 N | NÃO |
fantasy_name | Nome fantasia do sub-comércio | < 22 AN | NÃO |
| subacquirer_group | Dados de grupo de subadquirência. | ||
create | Flag que indica se devemos criar o grupo de subadquirência | < 5 T/F | NÃO |
id | ID do grupo de subadquirência | < 6 AN | NÃO |
cnpj | CNPJ do grupo de sub-adquirência | = 14 N | SIM, caso o campo subacquirer_group.create seja true |
| establishments | Dados dos estabelecimentos a serem cadastrados no SiTef. | ||
code | Código do estabelecimento (número lógico) a ser cadastrado no SiTef | < 32 AN | NÃO |
routing_id | ID do roteamento (tipo de pagamento do Carat) | < 4 N | NÃO |
subacquirer_group_id | ID do grupo de sub-adquirência. Deve ser enviado caso esse estabelecimento deva ser cadastrado para o grupo ao invés da empresa. | < 6 AN | NÃO |
extra_data | Informação adicional do estabelecimento. | < 32 AN | NÃO |
| transactional_urls | URLs utilizadas em fluxos transacionais. | ||
status | URL para recebimento de avisos de status. | < 500 AN | NÃO |
authenticity | URL para recebimento de POSTs de autenticidade. | < 500 AN | NÃO |
hash | URL para recebimento de hash/token de cartão armazenado. | < 500 AN | NÃO |
| return_urls | URLs de retorno de pagamento HTML. | ||
success | URL de retorno de sucesso. | < 500 AN | NÃO |
failure | URL de retorno de fracasso. | < 500 AN | NÃO |
cancel | URL de retorno de cancelamento. | < 500 AN | NÃO |
| permissions | Permissões transacionais a serem designadas para a loja. Enviar o valor true para habilitar a funcionalidade em questão. | ||
payment | Permissão para pagamento. | < 5 AN | NÃO |
pre_authorization | Permissão para pré-autorização. | < 5 AN | NÃO |
recharge | Permissão para recarga. | < 5 AN | NÃO |
risk_analysis | Permissão para análise de risco. | < 5 AN | NÃO |
schedule | Permissão para agendamento. | < 5 AN | NÃO |
iata | Permissão para IATA. | < 5 AN | NÃO |
card_store | Permissão para armazenamento de cartão. | < 5 AN | NÃO |
payment_link | Permissão para pagamento via link. | < 5 AN | NÃO |
| authorizers[] | Autorizadoras a serem cadastradas para a loja. A presença de um roteamento SiTef indica que deve ser criada uma empresa no SiTef. | ||
id | ID da autorizadora no Carat. Saiba mais. | < 4 N | SIM |
routing_id | ID do roteamento/adquirente no Carat. Saiba mais. | < 4 N | SIM |
min_installments_amount | Valor mínimo para parcelamento em transações HTML. Valor padrão: 1000 | < 12 N | NÃO |
max_installments_without_interest | Número máximo de parcelas sem juros em transações HTML. Valor padrão: 3 | < 2 N | NÃO |
max_installments_with_interest | Número máximo de parcelas com juros em transações HTML. Valor padrão: 12 | < 2 N | NÃO |
enable_subacquirer_group | Habilitar bandeira para uso de grupo de sub-adquirência. Enviar true para habilitar ou false para desabilitar. | < 5 T/F | NÃO |
acquirer_merchant_id | Identificador da loja designado pelo adquirente. Caso threeds_enabled = true deve-se enviar pelo menos um acquirer_merchant_id | < 35 AN | NÃO |
cvv_mandatory | Habilitar a obrigatoriedade do campo código de segurança do cartão. Enviar true para habilitar ou false para desabilitar. | < 5 T/F | NÃO |
| authorizers[].parameters | Parâmetros específicos do roteamento. Saiba mais. |
Códigos de roteamento/adquirente#
| ID | Roteamento |
|---|---|
201 | Cielo e-Commerce |
202 | e-Rede.REST |
407 | Getnet WS |
408 | Global Payments WS |
409 | Stone WS |
1005 | Rede via SiTef |
1181 | Getnet Lac via SiTef |
1125 | Cielo via SiTef |
1206 | Global Payments via SiTef |
1229 | BIN via SiTef |
1265 | Stone via SiTef |
1296 | Safra via SiTef |
Parâmetros específicos do roteamento#
Esses parâmetros devem ser enviados no campo authorizer[].parameters dependendo do roteamento escolhido.
Cielo e-Commerce#
| Parâmetro | Descrição |
|---|---|
| authorizers[].parameters | Parâmetros específicos do roteamento. |
merchantId | Identificação da loja na Cielo. |
merchantKey | Chave da loja na Cielo. |
Getnet WS#
| Parâmetro | Descrição |
|---|---|
| authorizers[].parameters | Parâmetros específicos do roteamento. |
username | Usuário de acesso. |
password | Senha de acesso. |
merchantID | Código de EC cadastrado na GetnetWS. |
terminal | Identificação do Terminal. |
subMerchantId | ID do Sub comércio. |
Global Payments WS#
| Parâmetro | Descrição |
|---|---|
| authorizers[].parameters | Parâmetros específicos do roteamento. |
merchantCode | Número do estabelecimento definido pela Global Payments. |
secretKey | Chave secreta do lojista na Global Payments. |
terminal | Número de terminal que será definido pela Global Payments. |
Stone WS#
| Parâmetro | Descrição |
|---|---|
| authorizers[].parameters | Parâmetros específicos do roteamento. |
salesAffiliationKey | Chave de identificação da loja na Stone. |
subAdquirenciaHabilitada | Enviar true para habilitar sub-adquirência ou false caso contrário. |
BIN via SiTef#
| Parâmetro | Descrição | Formato |
|---|---|---|
| authorizers[].parameters | Parâmetros específicos do roteamento. | |
subacquirerMerchantId | Código do sub-comércio. | |
| establishments | Dados dos estabelecimentos a serem cadastrados no SiTef. | |
extra_data | Código de terminal. Campo obrigatório para integração com a Bin. | = 8 AN |
e-Rede#
| Parâmetro | Descrição |
|---|---|
| authorizers[].parameters | Parâmetros específicos do roteamento. |
filiation | Código do filiação da loja na e-Rede. |
token | Chave pública da loja na e-Rede. |
Saiba mais detalhes sobre o roteamento e-Rede
Cadastro de lojas com antifraude#
É possível realizar o cadastro automático de novas lojas com as seguintes soluções de antifraude: Fraud Detect, ClearSale, CyberSource e Konduto. Para isso o lojista deve entrar em contato com a instituição de análise de risco e solicitar as credenciais necessárias. Em seguida, o lojista deve passar um conjunto de MCC's (Merchant Category Code) para cada credencial registrada para a equipe de Produção do Carat, que fará o cadastro desses dados. Será feito um mapeamento desses conjuntos de MCC para cada credencial e esses valores serão utilizados no cadastro de cada loja. Uma vez feito esse pré-cadastro, será possível realizar o cadastro de antifraude de forma automática utilizando a API de criação de lojas.
Atenção:
- É necessário ativar a permissão de anti fraude (
risk_analysis) no cadastro da loja.- Apenas a API de criação de lojas faz o cadastro de antifraude automático.
Parâmetros de resposta#
Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de loja:
| Parâmetro | Descrição | Formato |
|---|---|---|
response_code | Código de resposta do Carat. Qualquer código diferente de 0 significa falha. | < 4 N |
response_message | Mensagem de resposta do Carat. | < 500 AN |
authorizer_response_code | Código de resposta da autorizadora. | < 4 N |
authorizer_response_message | Mensagem de resposta da autorizadora. | < 500 AN |
id | Código da loja criada. Gerado automaticamente (obs: caracteres maiúsculas e minúsculas são diferenciados no sistema). | < 15 AN |
key | Chave da loja criada. | < 80 AN |