Pagamento

Interface de pagamentos que permite a loja realizar requisições de autorizações de venda

Detalhes da chamada#

  • Recurso: /v2/payments/
  • 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
Content-TypeDeve ser enviado com o valor application/json.= 15 ANSIM

Exemplos#

Requisição:

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

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: ************' \
--header 'merchant_key: ************' \
--data-raw '{
"merchant_usn": "12050620649",
"order_id": "121314",
"installments": "10",
"installment_type": "4",
"authorizer_id": "2",
"amount": "10000",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555"
}
}'
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "1657810477538",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "14/07/2022T11:54",
"authorization_number": "145778",
"merchant_usn": "12050620649",
"esitef_usn": "220714103502410",
"sitef_usn": "145778",
"host_usn": "999145778 ",
"amount": "10000",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"terminal_id": "ES000032",
"payment_date": "14/07/2022T11:54"
}
}

Pagamento Via Sitef - Token#

Requisição:

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

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
"merchant_usn": "12050620649",
"order_id": "1657833175201",
"installments": "10",
"installment_type": "4",
"authorizer_id": "2",
"amount": "10000",
"card": {
"token": "qJgaDApmM1APmglEpPUq7PomYpCXVqPWLW0MuEws1ZeOk95tDhqkKp-3n4KUNXAzsYxIazMSxNNSUXJ0zgwcuA=="
}
}'
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "APROVADA",
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "1657833175201",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "14/07/2022T18:12",
"authorization_number": "500335",
"merchant_usn": "12050620649",
"esitef_usn": "220714103502980",
"sitef_usn": "500335",
"host_usn": "007500335 ",
"amount": "10000",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000000",
"terminal_id": "ES000001",
"payment_date": "14/07/2022T18:12",
"recurrency_tid": "999988887777666"
}
}

Pagamento Via Sitef - Anti fraude Konduto#

Para mais informações verifique nossa seção específica da Konduto

Requisição:

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

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
"merchant_usn": "2423423434",
"order_id": "1657904793420",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "1300",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555"
},
"additional_data": {
"anti_fraud": "enabled_before_auth",
"visitor_id": "XKhas09jcks",
"items": [
{
"title": "title1",
"quantity": "1",
"unit_price": "1111",
"description": "description1",
"id": "id1",
"discount_amount": "111",
"sku": "sku1",
"creation_date": "11/01/2011"
}
],
"payer": {
"name": "Marcos",
"surname": "da Silva",
"email": "marocs@dasilva.com",
"born_date": "1990-01-01T11:11:11",
"creation_date": "02/03/2004",
"is_new_client": "true",
"is_vip_client": "true",
"phones": [
{
"number": "333333333",
"ddd": "22",
"ddi": "11"
},
{
"number": "666666666",
"ddd": "55",
"ddi": "44"
}
],
"identification_number": "47764543004"
},
"shipment": {
"name": "Fernando",
"surname": "Bezerra",
"address": {
"zip_code": "98764312",
"street_number": "987",
"street_name": "Rua Shipment",
"complement": "ap. 587",
"city": "São Shipment",
"state": "MA",
"country": "BRA"
}
},
"passengers": [
{
"name": "Miguel",
"last_name": "Herrera",
"frequent_flyer_card": "frequentFlyerCard",
"legal_document_type": "1",
"legal_document": "12312312312",
"birth_date": "1980-07-28T10:40:00",
"customer_class": "customerClass",
"nationality": "BRA",
"is_frequent_traveler": "true",
"is_with_special_needs": "true"
}
],
"connections": [
{
"company": "Verde",
"class": "first",
"from": "GRU",
"to": "CGH",
"departure_date": "2023-09-07T07:09:00",
"journey_type": "OUTWARD",
"origin_city": "San Juan",
"destination_city": "Homero Lopez",
"class_code": "VIP"
},
{
"company": "Rosa",
"class": "economy",
"from": "BSB",
"to": "VCP",
"departure_date": "2022-10-21T16:39:00",
"journey_type": "RETURN",
"origin_city": "San Pablo",
"destination_city": "Juanito Cruz",
"class_code": "ECONOMY"
}
],
"hotel_reservations": [
{
"hotel": "Hotel Green Tree",
"address": {
"zip_code": "83392019",
"street_number": "529",
"street_name": "Rua Hoteleira",
"complement": "ap. 019",
"city": "San Hotel",
"state": "AC",
"country": "EN"
},
"rooms": [
{
"number": "902",
"code": "ROOM902",
"type": "King Size",
"check_in_date": "2020-01-09T12:30:00",
"check_out_date": "2020-01-19T13:00:00",
"number_of_guests": "1",
"board_basis": "Vegan",
"guests": [
{
"name": "José Aníbal",
"document": "98798798712",
"document_type": "cpf",
"birth_date": "12/03/1970",
"nationality": "BRA"
}
]
}
],
"category": "categoryhotel"
}
],
"billing_data": {
"address": {
"zip_code": "12341234",
"street_number": "666",
"street_name": "Rua Billing",
"complement": "ap. 2369",
"city": "São Billing",
"state": "AM",
"country": "BRA"
}
},
"travel": {
"transport_type": "flight",
"expiration_date": "2022-02-14T01:30:00"
},
"discount_info": "Informações de desconto",
"events": [
{
"name": "Evento de Rock",
"date": "2021-11-22T09:28:00",
"type": "show",
"subtype": "music",
"venue": {
"name": "Debicard Hall",
"street_name": "Rua do Evento",
"street_number": "928",
"city": "Jardinópolis",
"state": "MS",
"country": "DO",
"capacity": "300"
},
"tickets": [
{
"id": "12h374612h4h",
"category": "social",
"section": "Seção 1",
"premium": "true",
"attendee": {
"name": "Daniel Almeida",
"document": "71728293945",
"document_type": "other",
"birth_date": "03/10/1990"
}
}
]
}
]
}
}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "1657904793420",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "15/07/2022T14:06",
"authorization_number": "155321",
"merchant_usn": "2423423434",
"esitef_usn": "220715103604930",
"sitef_usn": "155321",
"host_usn": "999155321 ",
"amount": "1300",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"terminal_id": "ES000015",
"payment_date": "15/07/2022T14:06",
"analysis": {
"status": "ACC",
"code": "0",
"message": "Recommendation: [APPROVE] Score: [0,00]"
}
}
}

Pagamento com captura posterior#

Requisição:

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

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
"merchant_usn": "12050620649",
"order_id": "1657810601498",
"installments": "10",
"installment_type": "4",
"authorizer_id": "2",
"amount": "10000",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555"
},
"acquirer": {},
"additional_data": {
"postpone_confirmation": "true"
}
}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "PPC",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "1657810601498",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "14/07/2022T11:56",
"authorization_number": "145779",
"merchant_usn": "12050620649",
"esitef_usn": "220714103502420",
"sitef_usn": "145779",
"host_usn": "999145779 ",
"amount": "10000",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"terminal_id": "ES000032",
"payment_date": "14/07/2022T11:56"
}
}

Requisição de confirmação:

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

curl --location --request PUT 'https://{{url}}/e-sitef/api/v2/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true' \
--header 'Content-Type: application/json' \
--header 'merchant_id: ********' \
--header 'merchant_key: ********'

Resposta de confirmação:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "130",
"status": "CON",
"acquirer_id": "5",
"host_usn": "999145779 ",
"payment_date": "14/07/2022T11:58"
}
}

Pagamento sem envio do order_id#

Requisição:

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

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
"merchant_usn": "12050620649",
"installments": "10",
"installment_type": "4",
"authorizer_id": "2",
"amount": "10000",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555"
}
}'

Resposta:

{
"code": "187",
"message": "Empty order_id value"
}

Pagamento de validação de conta - Zero Auth Dollar#

Requisição:

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

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
"merchant_usn": "12050620649",
"order_id": "1661350282230",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "0",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555"
}
}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "200",
"authorizer_message": "Success. [Cód.: 00]",
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "1661350282230",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "202",
"acquirer_name": "e.Rede REST",
"authorizer_date": "24/08/2022T11:11",
"authorization_number": "866551",
"merchant_usn": "12050620649",
"esitef_usn": "220824105973790",
"host_usn": "513089380",
"tid": "220824105973790",
"amount": "0",
"payment_type": "C",
"payment_date": "24/08/2022T11:11"
}
}

Pagamento - 3DS#

Requisição:

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

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
"merchant_usn": "12050620649",
"order_id": "1660136901859",
"installments": "1",
"installment_type": "4",
"authorizer_id": "1",
"amount": "9900",
"card": {
"expiry_date": "1023",
"number": "5555555555555555",
"security_code": "123",
"holder": "Joao Silva"
},
"external_authentication": {
"xid": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
"eci": "05",
"cavv": "jMoRyYgNSt0ZAREBBu8LHI+3oZo="
}
}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "00",
"authorizer_message": "TRANSACAO EXECUTADA COM SUCESSO",
"status": "CON",
"nit": "1dac764c4e38f6bea19a30656bc6ecb40b4cd58f139e56870a638a6bf0bfa2c0",
"order_id": "1660136901859",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "1",
"acquirer_id": "407",
"acquirer_name": "GetNetWS",
"authorizer_date": "03/10/2022T14:25",
"authorization_number": "267692",
"merchant_usn": "12050620649",
"esitef_usn": "221003109032570",
"host_usn": "072483954509",
"tid": "-1",
"amount": "9900",
"payment_type": "C",
"authorizer_merchant_id": "142365",
"payment_date": "03/10/2022T14:25"
}
}

Pagamento - Token Bandeira#

Algumas bandeiras de cartão possuem uma solução de tokenização que oferece o armazenamento de cartões em cofres na própria bandeira, de forma criptografada. Essa tokenização de bandeira tem o intuito de melhorar a segurança e qualidade das informações de cartão trafegadas, o que acarreta em possíveis aumentos na conversão de aprovação pelos bancos emissores.

Parêmetros de requisição

ParâmetroDescriçãoFormatoObrigatório
card
numberToken gerado pela bandeira (DPAN)≤ 19 NSim
cryptogramCriptograma gerado pela bandeira.= 28 ASim para pagamentos com token bandeira
wallet_typeCampo que especifica se a transação é processada com PAN ou DPAN. Se houver uma transação tokenizada, deverá enviar o valor “network_token”.ANSim para pagamentos com token bandeira

Requisição:

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

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
"merchant_usn": "12050620649",
"order_id": "1665002632429",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "10000",
"card": {
"number": "5555555555555555",
"expiry_date": "1223",
"cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
"wallet_type": "network_token",
}
}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "CON",
"nit": "41252cb6d538652cd8293541c8740cbe9bbd1dc380ecd65ab340d9dc0abf1d4a",
"order_id": "1665002632429",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "05/10/2022T17:43",
"authorization_number": "050246",
"merchant_usn": "12050620649",
"esitef_usn": "221005109152250",
"sitef_usn": "050246",
"host_usn": "999050246 ",
"amount": "10000",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000007",
"terminal_id": "ES000001",
"payment_date": "05/10/2022T17:43"
}
}

Serviço de confirmação de pagamento#

Após criar e efetuar um pagamento pendente de confirmação, o lojista deve chamar o serviço de confirmação para confirmar ou desfazer o pagamento utilizando o mesmo NIT obtido na primeira etapa do fluxo.

Detalhes da chamada#

  • Recurso: /v1/payments/{nit}
  • Método HTTP: PUT
  • Formato da requisição: query string
  • 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

Exemplo#

Abaixo estão exemplos de chamadas do serviço de confirmação de pagamento utilizando a ferramenta cURL.

Confirmação de pagamento com valor total#

Requisição:

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

curl
--request PUT "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true"
--header "merchant_id:xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"status": "CON"
}
}

Confirmação de pagamento com valor parcial#

Requisição:

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

curl
--request PUT "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true&amount=1000"
--header "merchant_id:xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"status": "CON",
"acquirer_id": "5"
}
}

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:

ATENÇÃO: Os parâmetros terminal e company_code deverão ser usados somente para roteamentos via SiTef e devem ser enviados simultaneamente.
É necessário também solicitar à equipe de atendimento do Carat a permissão Permite envio de Empresa e Terminal Sitef via REST. Informações relativas aos passageiros Informações relativas à reserva de hotel Informações relativas ao endereço do hotel Informações relativas a quartos do hotel Informações relativas a hóspedes do quarto Informações relativas a dados de um evento Informações relativas a dados de local de um evento Informações relativas aos ingressos de um evento Informações relativas ao participante do evento Informações relativas às conexões de viagem Informações relativas à fatura Informações relativas à passagem aérea
ParâmetroDescriçãoFormatoObrigatório
merchant_usnNú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 NNÃO
order_idCódigo do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade.
Para as transações roteadas pela adquirente Bin, existe uma limitação de 20 caracteres.
< 40 ANSIM
installmentsNúmero de parcelas. Envie ‘1’ para transações à vista.< 2 NSIM
installment_typeTipo 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 NSIM
authorizer_idCódigo da autorizadora no Carat. Saiba mais.< 3 NNÃO
amountValor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto.< 12 NSIM
soft_descriptorTexto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais< 30 ANNÃO
cardDados do cartão.
numberNúmero do cartão do comprador (PAN).

Token gerado pela bandeira (DPAN) para pagamento com Token Bandeira. Saiba mais
< 19 NSIM
expiry_dateData de vencimento do cartão no formato MMAA. Sua obrigatoriedade depende da adquirente escolhida. Na maioria dos casos, esse campo é obrigatório.= 4 NCOND.
security_codeCódigo de segurança. Este campo pode não ser obrigatório se a empresa possuir um acordo no contrato firmado com as redes adquirentes, somente para o pagamento de determinados seguimentos. Entretanto é possível configurar a obrigatoriedade do campo nas configurações da loja, consulte o suporte do Carat para mais informações.
Importante: um pagamento com agendamento implica no armazenamento dos dados do cartão do comprador no ambiente do Carat. Porém, por questões de segurança, o código de segurança não pode ser armazenado. Por isso, os pagamentos agendados sempre serão executados sem o envio do código de segurança.
< 5 NCOND.
holderNome do portador do cartão. Obrigatório apenas para pagamentos com e-Rede, GetNet WS e VR (SmartNet).< 30 ANNO.
tokenHASH de um cartão armazenado no Carat. Não é permitido enviar um número de cartão aberto (campo number) e um cartão armazenado (campo token) na mesma requisição.= 88 ANNÃO
cryptogramCriptograma gerado pela bandeira= 28 ANNÃO
wallet_typeCampo que especifica se a transação é processada com PAN ou DPAN. Se “tipo” estiver vazio, o valor padrão é PAN (número de cartão não tokenizado). Se houver uma transação tokenizada, deverá enviar o valor “network_token”.ANNÃO
external_authenticationEste elemento recebe campos de resultados de autenticação MPI.
eciEletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão< 3 NNÃO
xidIdentificador da transação de autenticação do dono do cartão, feita em serviço externo ao Carat< 40 NNÃO
cavvCardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.< 40 NNÃO
iataEste elemento contém campos específicos de transações IATA.
departure_taxTaxa de embarque em centavos.< 12 NSIM apenas para installment_type = 6 ou 7
first_installment Entrada em transações IATA em centavos. Funcionalidade disponível apenas para o adquirente Getnet. < 12 N NÃO
acquirerDados específicos necessários dependendo da adquirente/roteamento.
financing_planCódigo de plano de financiamento. Necessário apenas para pagamentos parcelados com juros roteados pela Via Certa Financiadora via SiTef.< 4 NNÃO
special_codeCódigo de uso geral da Conductor/Renner.< 6 NNÃO
midCódigo do estabelecimento da adquirente - Para roteamentos BIN, o MID a ser utilizado pelo estabelecimento é único. Este campo deve ser utilizado caso seja necessário selecionar um MID diferente do padrão.< 15 ANCOND
recurrencyFlag que define se o pagamento é ou não recorrente. Aceito para todos os roteamentos via SiTef, Cielo e-Commerce, Stone WS, Global Payments WS, SafraPay, e.Rede REST e GetnetWS.
No caso de recorrência via Stone WS, é obrigatório o envio adicional de apenas um dos campos abaixo, is_first_recurring OU is_subsequent_recurring.
< 5 T/FNÃO
recurrency_tidTID da primeira transação da recorrência. Identificador que diferencia a primeira recorrência das subsequentes. Só é utilizado quando for uma recorrência. Campo utilizado somente no roteamento e.Rede REST para as bandeiras Visa e Mastercard e roteamento GetnetWS.< 18 ANNÃO
is_first_recurringFlag usada apenas para roteamento StoneWS. Indica que a transação é a primeira de uma série de transações recorrentes.< 5 T/FCOND.
is_subsequent_recurringFlag usada apenas para roteamento StoneWS. Indica que a transação é a segunda ou n-ésima de uma série de transações recorrentes, onde n > 2. < 5 T/FCOND.
recurrency_original_amountValor original da transação que originou a recorrência. Este valor deve ser informado em todas a recorrências subsequentes. Só é utilizado quando for uma recorrência. Campo utilizado somente no roteamento BIN, obrigatório quando for recorrência< 18 ANNÃO
product_codeCódigo de produto.
É obrigatório em roteamento via Marisa.
< 6 NCOND.
terminalTerminal SiTef que se deseja usar. Se não for enviado, o Carat gerará um terminal aleatório.= 14 NNÃO
company_codeCódigo de empresa SiTef que se deseja usar. Se não for enviado, o Carat enviará o código de empresa cadastrado na loja.= 8 NNÃO
authorization_numberCódigo de autorização. Obrigatório para autorizadora Bradescard Voucher.< 6 ANCOND.
acquirer.vouchers_filter[]Filtro de Vouchers - Escolha dos vouchers que não serão aceitos. Opções de "Vouchers": 01 - Alimentação, 02 - Refeição 03 - Cultura, 04 - Combustível, 05 - Benefício.
Exemplo:
Não se quer aceitar Vouchers: Cultura, Combustível, Benefício. Deve enviar:
"vouchers_filter": [ "03", "04", "05" ]
acquirer.prefixesElemento para envio de prefixos do SiTef, como CICLOS, CPLANO e VLRADD. Caso o prefixo enviado não seja suportado pelo cartão enviado, o Carat invalidará a transação, impedindo que se dê uma falsa impressão do uso de uma determinada funcionalidade.

Exemplo:
{ "key" : "value" } -> { "CICLOS" : "01" }
keyNome do prefixo.< 1024 ANNÃO
valueValor do prefixo.< 1024 ANNÃO
acquirer.submerchant_split[]Consiste em um array para pagamentos split, exclusivos para roteamentos BIN e Sipag, ambos via SiTef. Permite a divisão de partes do valor total do pagamento entre outras empresas.
O máximo de itens permitido neste array é de 5 itens. Cada item é composto pelos campos submechant_code e submerchant_amount.
submerchant_codecódigo de estabelecimento BIN/Sipag< 51 ANNÃO
submerchant_amountvalor de transação referente ao estabelecimento< 12 NNÃO
acquirer.card_on_fileÉ destinado ao envio de informações específicas como, por exemplo, autorização de armazenamento de cartão, confirmando que o dono do cartão autorizou o armazenamento do cartão.
Saiba mais
usageIdentifica a utilização.
Por exemplo, para autorização de armazenamento: authorized
< 11 ANNÃO
reasonIdentifica o motivo.
Por exemplo, para autorização de armazenamento: card
< 11 ANNÃO
additional_dataElemento para envio de dados adicionais.
postpone_confirmationEsse campo deve ser enviado com valor true caso se deseje um pagamento com confirmação tardia.< 5 T/FNÃO
visitor_idIdentificador do visitante obtido no JavaScript da Konduto< 40 ANNÃO
descriptionDescrição do produto< 100 ANNÃO
discount_amountValor de desconto do produto em centavos< 10 NNÃO
discount_infoInformações de desconto.< 500 ANNÃO
skuCódigo de produto do item< 100 ANNÃO
creation_dateIndica a data de publicação do produto no site da loja (Formato: DD/MM/AAAA)= 10 ANNÃO
additional_data.payerElemento para envio de dados referentes ao comprador.
nameNome do cliente< 100 ANSIM
surnameSobrenome do cliente< 100 ANSIM
emailEndereço de e-mail do cliente< 100 ANSIM
born_dateData de nascimento do cliente (formato : AAAA-MM-DDTHH:MM:SS)= 19 ANNÃO
identification_numberNúmero de documento fiscal do cliente< 100 ANNÃO
creation_dateData de criação da conta ou cadastro do cliente no site (formato: DD/MM/AAAA )= 10 ANNÃO
is_new_clientBoolean indicando se o cliente está usando uma conta recém-criada nesta compra< 5 T/FNÃO
is_vip_clientBoolean indicando se este é um cliente VIP ou comprador frequente.< 5 T/FNÃO
additional_data
.passengers[]
namePrimeiro nome do passageiro< 100 ANSIM
last_nameSobrenome do passageiro< 100 ANSIM
legal_documentNúmero do documento< 100 ANSIM
legal_document_typeTipo do documento (5 = passport, qualquer outro número = id)< 8 ANSIM
birth_dateData de nascimento do passageiro (formato: AAAA-MM-DDTHH:MM:SS)< 17 ANNÃO
nationalityPaís de nascimento do passageiro, seguindo a ISO 3166-1 alfa-3= 3 ANNÃO
is_frequent_travelerFlag de viajante frequente< 5 T/FNÃO
is_with_special_needsFlag de viajante com necessidades especiais< 5 T/FNÃO
frequent_flyer_cardTipo de programa de fidelidade< 255 ANNÃO
customer_classCategoria do programa de fidelidade< 255 ANNÃO
additional_data
.hotel_reservations[]
hotelNome do hotel< 100 ANSIM
categoryCategoria do hotel< 100 ANNÃO
additional_data
.hotel_reservations[]
.address
street_name Rua do hotel< 255 ANNÃO
street_numberNúmero do hotel< 255 ANNÃO
complementComplemento do endereço hotel.< 100 ANNÃO
cityCidade do hotel< 100 ANNÃO
stateSigla do estado do hotel< 100 ANNÃO
zip_codeCEP do hotel< 100 ANNÃO
countryPaís do hotel, seguindo a ISO 3166-1 alfa-3.= 3 ANNÃO
additional_data
.hotel_reservations[]
.rooms[]
numberNúmero do quarto< 100 ANNÃO
codeCódigo do quarto< 100 ANNÃO
typeTipo do quarto< 100 ANNÃO
check_in_dateDate e hora do entrada (formato: AAAA-MM-DDTHH:MM:SS)< 17 ANSIM
check_out_dateDate e hora de saída (formato: AAAA-MM-DDTHH:MM:SS)< 17 ANNÃO
number_of_guestsNúmero de pessoas< 9999 NNÃO
board_basisRegime de alimentação< 100 ANNÃO
additional_data
.hotel_reservations[]
.rooms[]
.guests[]
nameNome do hóspede< 100 ANSIM
documentNúmero do documento do hóspede< 8 ANNÃO
document_typeDocumento usado pelo cliente:
  • cpf
  • rg
  • passport
  • id
  • other
< 8 ANNÃO
birth_dateData de nascimento do cliente (formato: AAAA-MM-DDTHH:MM:SS)< 17 ANNÃO
nationalityNacionalidade do hóspede, seguindo a ISO 3166-1 alfa-3.= 3 ANNÃO
additional_data
.events[]
nameNome do evento< 255 ANSIM
dateDate e hora do evento em UTC (formato AAAA-MM-DDTHH:MM:SS)< 17 ANSIM
typeTipo do evento:
  • show
  • theater
  • movies
  • party
  • festival
  • course
  • sports
  • corporate
< 9 ANSIM
subtypeDetalhe do tipo do evento< 255 ANNÃO
additional_data
.events[]
.venue
nameNome do local< 255 ANNÃO
street_nameNome da rua< 255 ANNÃO
street_numberNúmero da rua< 255 ANNÃO
cityCidade do local< 255 ANNÃO
stateEstado do local< 255 ANNÃO
countryPais do local, seguindo a ISO 3166-1 alfa-3.= 3 ANNÃO
capacityCapacidade do local< 255 ANNÃO
additional_data
.events[]
.tickets[]
idIdentificador único do ticket.< 255 ANNÃO
categoryCategoria do ticket:
  • student
  • senior
  • government
  • social
  • regular
< 10 ANSIM
sectionSeção do ticket< 255 ANNÃO
premiumIndicador de ticket premium< 5 T/FNÃO
additional_data
.events[]
.tickets[]
.ateendee
nameNome do participante< 255 ANNÃO
documentDocumento do participante< 100 ANSIM
document_typeTipo de documento do participante:
  • cpf
  • cnpj
  • rg
  • passport
  • other
< 100 ANNÃO
birth_dateData de nascimento do participante (formato: AAAA-MM-DDTHH:MM:SS)< 17 ANNÃO
additional_data.merchantElemento para envio de dados referentes ao lojista.
emailEndereço de e-mail do lojista.< 1024 ANNÃO
additional_data.extra_param.prefixesElemento para envio de prefixos do SiTef, como CICLOS, CPLANO e VLRADD. Caso o prefixo enviado não seja suportado pelo cartão enviado, o Carat invalidará a transação, impedindo que se dê uma falsa impressão do uso de uma determinada funcionalidade.

Exemplo:
{ "key" : "value" } -> { "CICLOS" : "01" }
keyNome do prefixo.< 1024 ANNÃO
valueValor do prefixo.< 1024 ANNÃO
additional_data.shipment.receiver_address
street_nameEndereço de entrega.< 255 ANNÃO
street_numberNúmero do endereço de entrega.< 15 ANNÃO
complementComplemento do endereço de entrega.< 50 ANNÃO
zip_codeCEP do endereço de entrega. Ex.: 21241-140.< 9 ANNÃO
cityCidade do endereço de entrega.< 50 ANNÃO
stateEstado do endereço de entrega.= 2 ANNÃO
countryPaís do endereço de entrega seguindo a AN 3166-1. Ex.: BRA= 3 ANNÃO
additional_data.browser
cookies_acceptedIdentifica se o browser do cliente aceita cookies. Enviar true caso positivo.< 5 T/FNÃO
emailE-mail registrado no browser do comprador.< 100 ANNÃO
host_nameNome do host onde o comprador estava antes de entrar no site da loja.< 60 ANNÃO
agentNome do browser utilizado pelo comprador. Ex.: Chrome.< 40 ANNÃO
additional_data.items[]
gift_categoryCampo que avaliará os endereços de cobrança e entrega para diferentes cidades, estados ou países. Pode assumir os seguintes valores:
OFF – Ignora a análise de risco para endereços divergentes.
YES – Em caso de divergência entre endereços de cobrança e entrega, marca com risco pequeno.
NO – Em caso de divergência entre endereços de cobrança e entrega, marca com risco alto.
< 3 ANNÃO
riskNível do risco do produto. Pode assumir os seguintes valores:
LOW – O produto tem um histórico de poucos chargebacks.
NORMAL – O produto tem um histórico de chargebacks considerado normal.
HIGH – O produto tem um histórico de chargebacks acima da média.
< 6 ANNÃO
titleNome do produto.< 255 ANNÃO
quantityQuantidade do produto a ser adquirido.< 15 NNÃO
idCódigo comerciante identificador do produto.< 255 ANNÃO
unit_pricePreço unitário do produto em centavos.< 15 NNÃO
additional_data.items[].passenger
emailE-mail do passageiro.< 255 ANNÃO
legal_documentId do passageiro a quem o bilhete foi emitido.< 32 ANNÃO
nameNome do passageiro.< 120 ANNÃO
customer_classClassificação da empresa aérea. Pode-se usar valores como Gold ou Platina.< 32 ANNÃO
additional_data.items[].passenger.phone
ddiCódigo do país do telefone do passageiro. Para pedidos fora dos E.U.A., é recomendável o envio deste campo.< 3 NNÃO
dddCódigo da área do telefone do passageiro.< 3 NNÃO
numberNúmero de telefone do passageiro.< 9 NNÃO
additional_data.shipment
nameNome do destinatário da entrega.< 255 ANNÃO
additional_data.shipment.phones[]
ddiCódigo do país do telefone do destinatário da entrega. Para pedidos fora dos E.U.A., é recomendável o envio deste campo.< 3 NNÃO
dddCódigo da área do telefone do destinatário da entrega.< 3 NNÃO
numberNúmero de telefone do destinatário da entrega.< 9 NNÃO
additional_data
.connections[]
journey_type
  • OUTWARD - para ida
  • RETURN - para volta
< 7 ANSIM
origin_cityCidade de origem.< 100 ANSIM, se transport_type=bus
destination_cityCidade de destino.< 100 ANSIM, se transport_type=bus
fromCódigo aeroportuário IATA para o aeroporto de origem= 3 ANSIM, se transport_type=flight
toCódigo aeroportuário IATA para o aeroporto de destino.= 3 ANSIM, se transport_type=flight
departure_dateDate e hora do embarque (formato: AAAA-MM-DDTHH:MM:SS)< 17 ANSIM
classNome da classe (Ex: economy, business e first)< 8 ANNÃO
class_codeCódigo da classe< 20 ANNÃO
companyNome da cia aérea< 20 ANNÃO
additional_data
.billing_data
.address
street_nameRua da fatura do cliente com o banco< 255 ANNÃO
street_numberNúmero da rua da fatura do cliente com o banco< 255 ANNÃO
complementComplemento do endereço de fatura.< 100 ANNÃO
cityCidade do titular< 100 ANNÃO
stateEstado do titular< 100 ANNÃO
zip_codeCEP do titular< 100 ANNÃO
countryCódigo do país do titular, seguindo a ISO 3166-1 alfa-3= 3 ANNÃO
additional_data
.travel
transport_typeTipo de viagem (flight ou bus)< 6 ANSIM
expiration_dateData de expiração (formato: DD/MM/AAAA )= 10 ANNÃO

Na tabela abaixo está a descrição dos parâmetros adicionais que devem ser enviados num pagamento com análise de fraude:

ParâmetroDescriçãoFormatoObrigatório
additional_data
anti_fraudHabilita o serviço de análise de fraude. Valores permitidos:
enabled_before_auth – a análise de fraude será realizada ANTES da autorização do pagamento. Caso a análise seja rejeitada, o pagamento não será iniciado.
enabled_after_auth – a análise de fraude será realizada APÓS a autorização do pagamento. Caso a análise seja rejeitada, o pagamento que já foi autorizado será cancelado.
< 19 ANSIM para análise de fraude
journey_typeTipo de viagem. Valores permitidos:
ROUND_TRIP – ida e volta.
OUTWARD – ida.
RETURN – volta.
< 10 ANNÃO

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 efetivação de pagamento:

ParâmetroDescriçãoFormato
codeCódigo de resposta do Carat. Qualquer código diferente de 0 significa falha. Saiba mais.< 4 N
messageMensagem de resposta do Carat.< 500 AN
payment
authorizer_codeCódigo de resposta do autorizador.< 10 AN
authorizer_messageMensagem de resposta do autorizador.< 500 AN
statusStatus da transação de pagamento no Carat. Saiba mais.= 3 AN
nitIdentificador da transação de pagamento no Carat.= 64 AN
order_idCódigo de pedido enviado pela loja na criação da transação.< 40 AN
merchant_usnNúmero sequencial único enviado pela loja na criação da transação.< 12 N
amountValor da compra especificado pela loja (em centavos) na criação da transação.< 12 N
sitef_usnNúmero sequencial único da transação de pagamento no SiTef.= 6 N
esitef_usnNúmero sequencial único da transação de pagamento no Carat.= 15 N
customer_receiptCupom (via cliente).< 4000 AN
merchant_receiptCupom (via estabelecimento).< 4000 AN
authorizer_idCódigo da autorizadora utilizada na transação.< 4 N
acquirer_idCódigo da adquirente utilizado na transação.< 4 N
acquirer_nameNome da adquirente utilizado na transação.< 100 AN
authorizer_dateData de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03= 16 D
authorization_numberNúmero de autorização.< 6 AN
host_usnNSU da autorizadora.< 15 AN
tidID da transação na adquirente. Este campo só é retornado em transações com adquirentes externas ao SiTef.< 40 AN
eciEletronic Commerce Indicator.< 3 AN
payment_dateData de efetivação do pagamento no Carat no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03= 16 D
issuerCódigo da bandeira retornado pelo autorizador.< 5 AN
authorizer_merchant_idCódigo de afiliação do lojista na autorizadora.< 100 AN
xidCampo XID retornado em autenticações 3DS ou certos adquirentes.< 40 AN
cavvCardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.< 40 N
recurrency_tidId de transação (TID) da bandeira, referente à primeira transação da recorrência. Só é retornado quando for uma recorrência. Campo utilizado somente no roteamento e.Rede REST para as bandeiras Visa e Mastercard.< 16 AN
terminal_idCódigo do terminal utilizada na transação< 8 AN
payment_typeTipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service= 1 AN
payment.analysis
statusStatus da transação de pagamento no Carat. Saiba mais.= 3 AN
codeCódigo de resposta do Carat. Qualquer código diferente de 0 significa falha. Saiba mais.< 4 N
messageMensagem de resposta do Carat.< 500 AN