Serviço de criação da transação
O consumo do serviço de criação de transação é obrigatório nos fluxos de pagamento e agendamento. Como resultado dessa operação, o lojista obterá um NIT (pagamento) que será necessário para os próximos passos do fluxo, assim como a utilização do serviço de consulta de transações.
O NIT possui um tempo limite para sua utilização. Este prazo está configurado na API, e caso seja excedido, a transação passará do status NOV (nova) para EXP (expirada), que impede futuras operações com essa transação, tornando necessário consumir novamente o serviço de criação de transação.
Detalhes da chamada#
- Recurso:
/v1/transactions - 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 |
Content-Type | Deve ser enviado com o valor application/json. | = 15 AN | SIM |
Exemplos#
Abaixo estão alguns exemplos de chamada do serviço de criação de transações utilizando a ferramenta cURL.
Criação de pagamento com confirmação automática#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
Criação de pagamento com confirmação tardia#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
Criação de pagamento com análise de risco #
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
Códigos de resposta
Veja a referencia no Códigos da API - códigos de 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 transações:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
merchant_usn | Número sequencial único para cada pedido, criado pela loja. O NSU será utilizado em toda a comunicação com a loja, de forma a identificar o pedido. Como se trata de uma possível chave para acesso do lado da loja, apesar de ser opcional para o Carat, é fortemente recomendado que o campo seja formatado e enviado pela aplicação da loja. | < 12 N | NÃO |
order_id | Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade. | < 40 AN | NÃO |
installments | Número de parcelas. Envie ‘1’ para transações à vista. | < 2 N | SIM |
installment_type | Tipo de financiamento do parcelamento: valor 3 = parcelamento com juros da administradora do cartão. valor 4 = parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista). Valor 6 = parcelamento com juros da administradora (IATA). valor 7 = parcelamento realizado pela loja e sem juros (IATA). O parcelamento IATA é utilizado somente por empresas do seguimento de transporte aéreo. | < 2 N | SIM |
authorizer_id | Código da autorizadora no Carat. Saiba mais. Nas operações com cartão tokenizado, se o codigo da autorizadora não for informado, será usado o código da autorizadora usado no armazenamento do cartão. | < 3 N | NÃO |
amount | Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto. | < 12 N | SIM |
soft_descriptor | Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais | < 25 AN | NÃO |
| additional_data | Elemento para envio de dados adicionais. | ||
postpone_confirmation | Esse campo deve ser enviado com valor true caso se deseje um pagamento com confirmação tardia. | < 5 T/F | NÃO |
customer_email | Para transações REST, envia o cupom do pagamento para o email informado. | < 50 AN | NÃO |
| additional_data.payer | Elemento para envio de dados referentes ao comprador. | ||
identification_number | Documento de identificação do comprador (CPF/RG). | < 20 AN | NÃO |
store_identification | Identificação do comprador para armazenamento de cartão. Esta identificação deve ser única para cada usuário da loja. Mas atenção, essa garantia de unicidade é de total responsabilidade da loja, A API não realizará nenhuma validação. | < 20 AN | SIM para agendamento |
name | Primeiro nome do comprador | < 100 AN | Não |
surname | Sobrenome nome do comprador | < 100 AN | Não |
| additional_data.merchant | Elemento para envio de dados referentes ao lojista. | ||
email | Endereço de e-mail do lojista. | < 1024 AN | NÃO |
| additional_data.extra_param.prefixes | Elemento para envio de prefixos do SiTef, como CICLOS, CPLANO e VLRADD. Caso o prefixo enviado não seja suportado pelo cartão enviado, a API invalidará a transação, impedindo que se dê uma falsa impressão do uso de uma determinada funcionalidade. Exemplo: { "key" : "value" } -> { "CICLOS" : "01" } | ||
key | Nome do prefixo. | < 1024 AN | NÃO |
value | Valor do prefixo. | < 1024 AN | NÃO |
Campos de MCC Dinâmico#
Inicialização da transação de pagamento ou de pré-autorização REST#
Parâmetros de requisição#
Adicionalmente aos campos mencionados, os campos abaixo são usados no cenário específico de MCC dinâmico da integração com a bin:
| Parâmetro | Descrição | Formato | Obrigatório | |||
|---|---|---|---|---|---|---|
soft_descriptor | Frase personalizada que será impressa na fatura do portador. Para informação referente ao MCC dinâmico, equivale ao nome do sublojista. | < 25 AN | SIM | |||
| additional_data | Elemento para envio de dados adicionais. | |||||
mcc | MCC do sublojista. | = 4 N | SIM | |||
subacquirer_merchant_id | Código do sublojista. Campo legado!!! Dar preferência ao additional_data.subacquirer_merchant.id | < 15 N | NÃO | |||
| additional_data.subacquirer_merchant | Elemento para envio de dados referentes ao lojista de uma subadquirente. | |||||
id | Código do sublojista. | < 15 N | SIM | |||
phone_number | Número de Telefone do sublojista. | < 14 AN | NÃO | |||
address | Endereço do sublojista. | < 48 AN | NÃO | |||
city | Cidade do sublojista. | < 13 AN | NÃO | |||
state | Estado do sublojista, em formato de sigla de dois dígitos (ex.: SP). | = 2 A | SIM | |||
country | País do sublojista. Seguir o padrão ISO 3166-1 alpha-2 (ex.: BR). | = 2 A | SIM | |||
zip_code | Código postal do sublojista. | < 9 AN | SIM | |||
identification_number | CNPJ do sublojista. | < 18 N | SIM | |||
payment_facilitator_id | Código do facilitador. | < 11 N | SIM | |||
Exemplo#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
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 transações:
| Parâmetro | Descrição | Formato |
|---|---|---|
code | Código de resposta do Carat. Qualquer código diferente de 0 significa falha. Saiba mais. | < 4 N |
message | Mensagem de resposta do Carat. | < 500 AN |
| payment | ||
status | Status da transação de pagamento no Carat. Saiba mais. | = 3 AN |
nit | Identificador da transação de pagamento no Carat. | = 64 AN |
order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 N |
amount | Valor da compra especificado pela loja (em centavos) na criação da transação. | < 12 N |
| schedule | ||
sid | Identificador da transação de agendamento no Carat. | = 64 AN |
amount | Valor dos pagamentos agendados especificado pela loja (em centavos) na criação da transação. | < 12 N |
status | Status do agendamento no Carat. Saiba mais. | = 3 AN |
order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 N |