Merchant creation service
After getting the token or signature in the previous step, the virtual store must send the data of the merchant to be created on Carat Portal and SiTef (if necessary).
Attention:
Registered merchants will have the same personalization settings as the registering merchant, such as their logo, CSS and JS.
Call details#
- Resource:
/v1/merchants - HTTP Method:
POST - Request format:
JSON - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
token | Token obtained in the previous step. Learn more. | = 66 AN | NO |
Content-Type | Must be sent with the value application/json. | = 15 AN | YES |
Attention:
During merchant registration, the settings related to the use of 3DS and anti-fraud are automatically replicated from the registering merchant.
Example#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Request parameters#
The table below describes the parameters of the merchant creation service:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
cnpj | CNPJ or CPF of the merchant. Numbers only. | = 14 N | YES |
force_sitef_merchant_creation | If the value true is informed, it activates the alternative generation of company numbers, allowing more than one company to be registered for the same CNPJ/CPF. If not informed, it assumes false, that is, it uses the standard algorithm for generating company code, which guarantees only one company for each CNPJ/CPF. Send true or false. | < 5 AN | NO |
fantasy_name | Fantasy name of the merchant. | < 250 AN | YES |
corporate_name | Corporate name of the merchant. | < 250 AN | YES |
domain | Domain (site) of the merchant. | < 65 AN | NO |
address | Address of the merchant. | < 30 AN | NO |
city | City of the merchant. | < 13 AN | NO |
state | State of the merchant (abbreviation). | = 2 AN | NO |
zip_code | Zip code of the merchant. | < 9 AN | NO |
phone_number | Phone number of the merchant. | < 30 AN | NO |
email | E-mail address of the merchant. | < 100 AN | NO |
mcc | Merchant Category Code - code indicating the category of the establishment (used on the anti-fraud registration). If the field threeds_enabled=true, mcc becomes mandatory. If the value's length has less than 4 digits, zeros will be added to the left of the number until it reaches size 4. | = 4 N | NO |
threeds_enabled | Enables the merchant to integrate with the 3DS Server and performing the necessary configurations on Carat Portal, send true or false. Learn more. | < 5 AN | NO |
threeds_payment_link_authentication | Default authentication type that will be displayed when generating the payment link.
| = 1 N | NO |
automatic_threeds_minimum_value | Indicates the minimum amount in cents for a transaction to automatically enable the 3DS. Attention: intervals that allow the use of 3ds and anti-fraud together must not be used. | < 12 N | NO |
automatic_threeds_maximum_value | Indicates the maximum amount in cents for a transaction to automatically enable the 3DS. Attention: intervals that allow the use of 3ds and anti-fraud together must not be used. | < 12 N | NO |
automatic_antifraud_minimum_value | Indicates the minimum amount in cents for a transaction to automatically enable Anti-Fraud. Attention: intervals that allow the use of 3ds and anti-fraud together must not be used. | < 12 N | NO |
automatic_antifraud_maximum_value | Indicates the maximum amount in cents of a transaction to automatically enable Anti-Fraud. Attention: intervals that allow the use of 3ds and anti-fraud together must not be used. | < 12 N | NO |
antifraud_over_threeds | Flag that turns on the functionality to activate the anti-fraud automatically in case of error or denied authentication using the 3DS Server integrated with Payment Online | < 5 AN | NO |
| soft_descriptor | Submerchant data. | ||
id | Submerchant ID | < 22 AN | NO |
country | Submerchant country. ISO 3166-1 numeric code. | = 3 N | NO |
fantasy_name | Submerchant fantasy name | < 22 AN | NO |
| subacquirer_group | Subacquirer group data. | ||
create | Flag indicating whether the subacquirer group should be created | < 5 T/F | NO |
id | Subacquirer group ID | < 6 AN | NO |
cnpj | Subacquirer group CNPJ | = 14 N | YES, if the field subacquirer_group.create is true |
| establishments | Data of the establishments to be created on SiTef. | ||
code | Establishment code (logical number) to be created on SiTef | = 11 N | NO |
routing_id | Acquirer/routing ID on Carat Portal | < 4 N | NO |
subacquirer_group_id | Subacquirer group ID. Should be sent in case the establishment must be created for the group instead of the merchant. | = 6 N | NO |
extra_data | Additional establishment information | < 32 AN | NO |
| transactional_urls | URLs used on transactional flows. | ||
status | URL for receiving status notifications. | < 500 AN | NO |
authenticity | URL for receiving authenticity POSTs. | < 500 AN | NO |
hash | URL for receiving stored card hash/token. | < 500 AN | NO |
| return_urls | HTML payment return URLs. | ||
success | Success return URL. | < 500 AN | NO |
failure | Failure return URL. | < 500 AN | NO |
cancel | Cancel return URL. | < 500 AN | NO |
| permissions | Transactional permissions to be attributed to the merchant. Send the value true to enable the desired functionality. | ||
payment | Payment permission. | < 5 AN | NO |
pre_authorization | Pre-authorization permission. | < 5 AN | NO |
recharge | Recharge permission. | < 5 AN | NO |
risk_analysis | Risk analysis permission. | < 5 AN | NO |
schedule | Schedule permission. | < 5 AN | NO |
iata | IATA permission. | < 5 AN | NO |
card_store | Card store permission. | < 5 AN | NO |
payment_link | Payment link permission. | < 5 AN | NO |
| authorizers[] | Authorizers to be registered to the merchant. The presence of a SiTef routing indicates that a SiTef merchant must also be created. | ||
id | Authorizer ID on Carat Portal. Learn more. | < 4 N | YES |
routing_id | Routing/acquirer ID on Carat Portal. Learn more. | < 4 N | YES |
min_installments_amount | Minimum installment amount for HTML transactions. Default value: 1000 | < 12 N | NO |
max_installments_without_interest | Maximum installments without interest for HTML transactions. Default value: 3 | < 2 N | NO |
max_installments_with_interest | Maximum installments with interest for HTML transactions. Default value: 12 | < 2 N | NO |
enable_subacquirer_group | Enable subacquirer group usage for the authorizer. Send true to enable or false to disable. | < 5 T/F | NO |
acquirer_merchant_id | Merchant identifier designated by the acquirer. If threeds_enabled = true you must send at least one acquirer_merchant_id | < 35 AN | NO |
cvv_mandatory | Enable mandatory card security code field. Send true to enable or false to disable. | < 5 T/F | NO |
| authorizers[].parameters | Specific routing parameters. Learn more. |
Routing/acquirer codes#
| ID | Routing |
|---|---|
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 |
Specific routing parameters#
These parameters must be sent in the authorizer[].parameters field depending on the chosen acquirer.
Cielo e-Commerce#
| Parameter | Description |
|---|---|
| authorizers[].parameters | Specific routing parameters. |
merchantId | Merchant identification on Cielo. |
merchantKey | Merchant key on Cielo. |
Getnet WS#
| Parameter | Description |
|---|---|
| authorizers[].parameters | Specific routing parameters. |
username | Access user. |
password | Access password. |
merchantID | EC code registered on Getnet. |
terminal | Terminal identification. |
subMerchantId | Submerchant ID. |
Global Payments WS#
| Parameter | Description |
|---|---|
| authorizers[].parameters | Specific routing parameters. |
merchantCode | Establishment number defined by Global Payments. |
secretKey | Merchant secret key on Global Payments. |
terminal | Terminal number that will be defined by Global Payments. |
Stone WS#
| Parameter | Description |
|---|---|
| authorizers[].parameters | Specific routing parameters. |
salesAffiliationKey | Merchant identification key on Stone. |
subAdquirenciaHabilitada | Send true to enable sub-acquiring or false otherwise. |
BIN via SiTef#
| Parameter | Description | Format |
|---|---|---|
| authorizers[].parameters | Specific routing parameters. | |
subacquirerMerchantId | Submerchant code. | |
| establishments | Data of the establishments to be created on SiTef. | |
establishments.extra_data | Terminal code. Mandatory field for integration with the Bin acquirer. | = 8 AN |
e-Rede#
| Parameter | Description |
|---|---|
| authorizers[].parameters | Specific routing parameters. |
filiation | Merchant filiation code on e-Rede. |
token | Merchant public key on e-Rede. |
Check more details about "e-Rede routing")
Registering merchants with anti-fraud#
It's possible to automatically register new merchants with the following anti-fraud solutions: Fraud, ClearSale, CyberSource and Konduto. To do it, the merchant must contact the risk analysis institution and request the necessary credentials. Then, the merchant must pass a set of MCC's (Merchant Category Code) for each registered credential to the Carat Portal Production team, which will register this data. These MCC's will be mapped for each credential and these values will be used on the registration of each merchant. Once this pre-registration is done, it will be possible to perform the anti-fraud registration automatically using the merchant creation API.
Attention:
- It's required to activate the anti-fraud permission (
risk_analysis) on the merchant creation call.- Only the merchant creation service performs the automatic anti-fraud registration.
Response parameters#
If successful, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes the response parameters of the merchant creation service:
| Parameter | Description | Format |
|---|---|---|
response_code | Carat Portal response code. Any code different from 0 means failure. | < 4 N |
response_message | Carat Portal response message. | < 500 AN |
authorizer_response_code | Authorizer response code. | < 4 N |
authorizer_response_message | Authorizer response message. | < 500 AN |
id | Code of the created merchant. Automatically generated (note: uppercase and lowercase characters are differentiated in the system). | < 15 AN |
key | Key of the created merchant. | < 80 AN |