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âmetroDescriçãoFormatoObrigatório
merchant_idCódigo da loja no Carat. Os códigos de produção e certificação serão diferentes.< 15 ANSIM
merchant_keyChave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes.< 80 ANSIM
tokenToken obtido na etapa anterior, caso a autenticação seja via post de autenticidade Saiba mais.= 66 ANNÃO
Content-TypeDeve ser enviado com o valor application/json.= 15 ANSIM
AuthorizationDeve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg.< 2000 ANNÃ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

curl
--request POST "https://{{url}}/e-sitef/api/v1/merchants"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "token: 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--data-binary
{
"cnpj":"123123123123",
"fantasy_name":"Teste de Loja",
"corporate_name":"Testes de Loja Ltda.",
"mcc":"1234",
"threeds_enabled":"true",
"threeds_payment_link_authentication":"1",
"automatic_threeds_minimum_value" : "30000",
"automatic_threeds_maximum_value" : "99999",
"automatic_antifraud_minimum_value" : "100000",
"automatic_antifraud_maximum_value" : "999999",
"antifraud_over_threeds" : "false",
"version": "5",
"soft_descriptor":{
"fantasy_name":"Sub-comércio da Loja",
"country":"BR",
"id":"123456"
},
"subacquirer_group":{
"create":"true",
"id":"123456",
"cnpj":"12345678901234"
},
"domain":"www.testeloja.com",
"address":"Rua do Teste, 123",
"city":"São Teste",
"state":"SP",
"zip_code":"12345678",
"phone_number":"11912341234",
"email":"testeloja@teste.com",
"transactional_urls":{
"status":"https://www.testeloja.com/status",
"authenticity":"https://www.testeloja.com/autent",
"hash":"https://www.testeloja.com/hash"
},
"return_urls":{
"success":"https://www.testeloja.com/sucesso",
"failure":"https://www.testeloja.com/fracasso",
"cancel":"https://www.testeloja.com/cancel"
},
"permissions":{
"payment":"true",
"pre_authorization":"false",
"recharge":"false",
"risk_analysis":"true",
"schedule":"true",
"iata":"false",
"card_store":"false",
"payment_link":"true"
},
"establishments":[
{
"code":"00000000123",
"routing_id":"1125",
"subacquirer_group_id":"123456"
},
{
"code":"00000000321",
"routing_id":"1005"
}
],
"authorizers":[
{
"id":"1",
"routing_id":"1125",
"min_installments_amount":"100",
"max_installments_without_interest":"1",
"max_installments_with_interest":"12",
"enable_subacquirer_group":"true",
"acquirer_merchant_id":"11111",
"cvv_mandatory":"true"
},
{
"id":"2",
"routing_id":"201",
"min_installments_amount":"100",
"max_installments_without_interest":"1",
"max_installments_with_interest":"12",
"parameters":{
"merchantId":"8h37e9e23oe",
"merchantKey":"b9f374t5983t745f873tb45f93b4f2293b485ft34"
},
"acquirer_merchant_id":"22222"
}
]
}
--verbose

Exemplo utilizando assinatura#

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br

curl
--request POST "https://{{url}}/e-sitef/api/v1/merchants"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "Authorization: Bearer YYYYYYY"
--data-binary
{
"cnpj":"123123123123",
"fantasy_name":"Teste de Loja",
"corporate_name":"Testes de Loja Ltda.",
"mcc":"1234",
"threeds_enabled":"true",
"threeds_payment_link_authentication":"1",
"automatic_threeds_minimum_value" : "30000",
"automatic_threeds_maximum_value" : "99999",
"automatic_antifraud_minimum_value" : "100000",
"automatic_antifraud_maximum_value" : "999999",
"antifraud_over_threeds" : "false",
"version": "5",
"soft_descriptor":{
"fantasy_name":"Sub-comércio da Loja",
"country":"BR",
"id":"123456"
},
"subacquirer_group":{
"create":"true",
"id":"123456",
"cnpj":"12345678901234"
},
"domain":"www.testeloja.com",
"address":"Rua do Teste, 123",
"city":"São Teste",
"state":"SP",
"zip_code":"12345678",
"phone_number":"11912341234",
"email":"testeloja@teste.com",
"transactional_urls":{
"status":"https://www.testeloja.com/status",
"authenticity":"https://www.testeloja.com/autent",
"hash":"https://www.testeloja.com/hash"
},
"return_urls":{
"success":"https://www.testeloja.com/sucesso",
"failure":"https://www.testeloja.com/fracasso",
"cancel":"https://www.testeloja.com/cancel"
},
"permissions":{
"payment":"true",
"pre_authorization":"false",
"recharge":"false",
"risk_analysis":"true",
"schedule":"true",
"iata":"false",
"card_store":"false",
"payment_link":"true"
},
"establishments":[
{
"code":"00000000123",
"routing_id":"1125",
"subacquirer_group_id":"123456"
},
{
"code":"00000000321",
"routing_id":"1005"
}
],
"authorizers":[
{
"id":"1",
"routing_id":"1125",
"min_installments_amount":"100",
"max_installments_without_interest":"1",
"max_installments_with_interest":"12",
"enable_subacquirer_group":"true",
"acquirer_merchant_id":"11111",
"cvv_mandatory":"true"
},
{
"id":"2",
"routing_id":"201",
"min_installments_amount":"100",
"max_installments_without_interest":"1",
"max_installments_with_interest":"12",
"parameters":{
"merchantId":"8h37e9e23oe",
"merchantKey":"b9f374t5983t745f873tb45f93b4f2293b485ft34"
},
"acquirer_merchant_id":"22222"
}
]
}
--verbose

Resposta:

{
"id": "qereIoinsd3d",
"key": "9B71234TB12D938T9384TDB294T923D412T938D1293D4B923D",
"response_code": "0",
"response_message": "OK",
"authorizer_response_code": "0",
"authorizer_response_message": "OK"
}

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âmetroDescriçãoFormatoObrigatório
cnpjCNPJ ou CPF da loja. Apenas números.< 14 NSIM
force_sitef_merchant_creationSe 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 ANNÃO
fantasy_nameNome fantasia da loja.< 250 ANSIM
corporate_nameRazão social da loja.< 250 ANSIM
domainDomínio (site) da loja.< 500 ANNÃO
addressEndereço da loja.< 200 ANNÃO
cityCidade da loja.< 50 ANNÃO
stateEstado da loja (sigla).= 2 ANNÃO
zip_codeCEP da loja.< 9 ANNÃO
phone_numberTelefone da loja.< 30 ANNÃO
emailEndereço de e-mail da loja.< 100 ANNÃO
mccMerchant 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 NNÃO
threeds_enabledHabilita a loja para integrar com o 3DS Server e realiza as configurações necessárias no Carat, enviar true ou false. Saiba mais.< 5 ANNÃO
threeds_payment_link_authenticationTipo de autenticação padrão que será exibida na geração de link de pagamento no portal do lojista. Saiba mais.
  • 0 = Sem autenticação
  • 1 = Habilitar o uso de 3DS e se o 3DS server não suportar a bandeira ou falhar para realizar a autenticação, o pagamento será negado.
  • 2 = Habilitar o uso de 3DS apenas com bandeiras suportadas pelo 3DS server. Se o 3DS server não suportar a bandeira, a autenticação não é realizada.Caso a bandeira seja suportada e a autenticação seja negada, o pagamento será negado
  • 3 = Habilitar o uso de 3DS e se autenticação falhar, o pagamento não será negado na autenticação.
= 1 NNÃO
automatic_threeds_minimum_valueIndica 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 NNÃO
automatic_threeds_maximum_valueIndica 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 NNÃO
automatic_antifraud_minimum_valueIndica 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 NNÃO
automatic_antifraud_maximum_valueIndica 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 NNÃO
antifraud_over_threedsFlag 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 ANNÃO
versionEspecifica 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 51 NNÃO
soft_descriptorDados do sub-comércio.
idID do sub-comércio.< 22 ANNÃO
countryPaís do sub-comércio. Código numérico ISO 3166-1.= 3 NNÃO
fantasy_nameNome fantasia do sub-comércio< 22 ANNÃO
subacquirer_groupDados de grupo de subadquirência.
createFlag que indica se devemos criar o grupo de subadquirência< 5 T/FNÃO
idID do grupo de subadquirência< 6 ANNÃO
cnpjCNPJ do grupo de sub-adquirência= 14 NSIM, caso o campo subacquirer_group.create seja true
establishmentsDados dos estabelecimentos a serem cadastrados no SiTef.
codeCódigo do estabelecimento (número lógico) a ser cadastrado no SiTef< 32 ANNÃO
routing_idID do roteamento (tipo de pagamento do Carat)< 4 NNÃO
subacquirer_group_idID do grupo de sub-adquirência. Deve ser enviado caso esse estabelecimento deva ser cadastrado para o grupo ao invés da empresa.< 6 ANNÃO
extra_dataInformação adicional do estabelecimento.< 32 ANNÃO
transactional_urlsURLs utilizadas em fluxos transacionais.
statusURL para recebimento de avisos de status.< 500 ANNÃO
authenticityURL para recebimento de POSTs de autenticidade.< 500 ANNÃO
hashURL para recebimento de hash/token de cartão armazenado.< 500 ANNÃO
return_urlsURLs de retorno de pagamento HTML.
successURL de retorno de sucesso.< 500 ANNÃO
failureURL de retorno de fracasso.< 500 ANNÃO
cancelURL de retorno de cancelamento.< 500 ANNÃO
permissionsPermissões transacionais a serem designadas para a loja. Enviar o valor true para habilitar a funcionalidade em questão.
paymentPermissão para pagamento.< 5 ANNÃO
pre_authorizationPermissão para pré-autorização.< 5 ANNÃO
rechargePermissão para recarga.< 5 ANNÃO
risk_analysisPermissão para análise de risco.< 5 ANNÃO
schedulePermissão para agendamento.< 5 ANNÃO
iataPermissão para IATA.< 5 ANNÃO
card_storePermissão para armazenamento de cartão.< 5 ANNÃO
payment_linkPermissão para pagamento via link.< 5 ANNÃ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.
idID da autorizadora no Carat. Saiba mais.< 4 NSIM
routing_idID do roteamento/adquirente no Carat. Saiba mais.< 4 NSIM
min_installments_amountValor mínimo para parcelamento em transações HTML. Valor padrão: 1000< 12 NNÃO
max_installments_without_interestNúmero máximo de parcelas sem juros em transações HTML. Valor padrão: 3< 2 NNÃO
max_installments_with_interestNúmero máximo de parcelas com juros em transações HTML. Valor padrão: 12< 2 NNÃO
enable_subacquirer_groupHabilitar bandeira para uso de grupo de sub-adquirência. Enviar true para habilitar ou false para desabilitar.< 5 T/FNÃO
acquirer_merchant_idIdentificador da loja designado pelo adquirente. Caso threeds_enabled = true deve-se enviar pelo menos um acquirer_merchant_id< 35 ANNÃO
cvv_mandatoryHabilitar a obrigatoriedade do campo código de segurança do cartão. Enviar true para habilitar ou false para desabilitar.< 5 T/FNÃO
authorizers[].parametersParâmetros específicos do roteamento. Saiba mais.

Códigos de roteamento/adquirente#

IDRoteamento
201Cielo e-Commerce
202e-Rede.REST
407Getnet WS
408Global Payments WS
409Stone WS
1005Rede via SiTef
1181Getnet Lac via SiTef
1125Cielo via SiTef
1206Global Payments via SiTef
1229BIN via SiTef
1265Stone via SiTef
1296Safra 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âmetroDescrição
authorizers[].parametersParâmetros específicos do roteamento.
merchantIdIdentificação da loja na Cielo.
merchantKeyChave da loja na Cielo.

Getnet WS#

ParâmetroDescrição
authorizers[].parametersParâmetros específicos do roteamento.
usernameUsuário de acesso.
passwordSenha de acesso.
merchantIDCódigo de EC cadastrado na GetnetWS.
terminalIdentificação do Terminal.
subMerchantIdID do Sub comércio.

Global Payments WS#

ParâmetroDescrição
authorizers[].parametersParâmetros específicos do roteamento.
merchantCodeNúmero do estabelecimento definido pela Global Payments.
secretKeyChave secreta do lojista na Global Payments.
terminalNúmero de terminal que será definido pela Global Payments.

Stone WS#

ParâmetroDescrição
authorizers[].parametersParâmetros específicos do roteamento.
salesAffiliationKeyChave de identificação da loja na Stone.
subAdquirenciaHabilitadaEnviar true para habilitar sub-adquirência ou false caso contrário.

BIN via SiTef#

ParâmetroDescriçãoFormato
authorizers[].parametersParâmetros específicos do roteamento.
subacquirerMerchantIdCódigo do sub-comércio.
establishmentsDados dos estabelecimentos a serem cadastrados no SiTef.
extra_dataCódigo de terminal. Campo obrigatório para integração com a Bin.= 8 AN

e-Rede#

ParâmetroDescrição
authorizers[].parametersParâmetros específicos do roteamento.
filiationCódigo do filiação da loja na e-Rede.
tokenChave 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âmetroDescriçãoFormato
response_codeCódigo de resposta do Carat. Qualquer código diferente de 0 significa falha.< 4 N
response_messageMensagem de resposta do Carat.< 500 AN
authorizer_response_codeCódigo de resposta da autorizadora.< 4 N
authorizer_response_messageMensagem de resposta da autorizadora.< 500 AN
idCódigo da loja criada. Gerado automaticamente (obs: caracteres maiúsculas e minúsculas são diferenciados no sistema).< 15 AN
keyChave da loja criada.< 80 AN