Serviço de consulta de cartão

Esta seção explica sob o contexto de pagamento. Veja mais detalhes no fluxo.

A partir de um NIT de pagamento com status NOV (novo), é possível realizar uma consulta do BIN do cartão (seis primeiros dígitos) no SiTef para obter dados sobre suas capacidades (possibilidade de pagamento parcelado, máximo de parcelas, exigência de código de segurança, etc.), ou ainda, saber qual autorizadora da loja é a mais adequada para a realização do pagamento.

No caso de transações com Visa Checkout, este serviço também retornará dados do cartão e do usuário retornados pelo Visa.

Fluxo#

Consulta Cartão

Descrição do fluxo:

  1. O lojista cria uma transação no Carat passando informações como código da loja, número de parcelas e código de pedido e obtém como resposta um NIT (Número Identificador de Transação).
  2. O lojista envia o NIT obtido na etapa anterior e os dados do cartão a ser consultado. Com isso, o Carat retorna dados sobre as capacidades do cartão enviado.
  3. A loja virtual prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT e os dados do cartão do comprador. Em caso de sucesso, a transação de pagamento mudará seu status para CON (confirmada).

Detalhes da chamada#

  • Recurso: /v1/payments/{nit}/cards
  • 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

Obs.: apesar de se tratar de uma consulta, o método POST foi escolhido por questões de segurança.

Exemplos#

Abaixo estão alguns exemplos de chamada do serviço de consulta de cartão utilizando a ferramenta cURL.

Consulta de cartão com envio de autorizadora#

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 POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"number":"5555555555555555"
},
"authorizer_id":"1"
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"status": "NOV"
},
"card": {
"acquirer_name": "Bin",
"authorizer_id": "1",
"authorizer_response_code": "000",
"is_customer_id_required": "false",
"is_expiry_date_required": "true",
"is_installment_funding_enabled": "true",
"is_security_code_required": "true",
"is_spot_sale_enabled": "true",
"is_with_interest_sale_enabled": "true",
"is_without_interest_sale_enabled": "true",
"max_installments_with_interest": "12",
"min_installments_with_interest": "01",
"prefixes": {
"TRAT": "2",
"PERIFERICO": "1",
"CSEG": "2"
}
}
}

Consulta de cartão sem envio de autorizadora#

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 POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"number":"6543210987654321"
}
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"status": "NOV"
},
"card": {
"acquirer_name": "Bin",
"authorizer_id": "1",
"authorizer_response_code": "000",
"is_customer_id_required": "false",
"is_expiry_date_required": "true",
"is_installment_funding_enabled": "true",
"is_security_code_required": "true",
"is_spot_sale_enabled": "true",
"is_with_interest_sale_enabled": "true",
"is_without_interest_sale_enabled": "true",
"max_installments_with_interest": "12",
"min_installments_with_interest": "01",
"prefixes": {
"TRAT": "2",
"PERIFERICO": "1",
"CSEG": "2"
}
}
}

Consulta de cartão Visa Checkout#

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 POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"wallet_transaction_id":"4444444444444444444"
},
"authorizer_id":"406"
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"status": "NOV"
},
"card": {
"acquirer_name": "Bin",
"authorizer_id": "406",
"authorizer_response_code": "000",
"is_customer_id_required": "false",
"is_expiry_date_required": "true",
"is_installment_funding_enabled": "true",
"is_security_code_required": "true",
"is_spot_sale_enabled": "true",
"is_with_interest_sale_enabled": "true",
"is_without_interest_sale_enabled": "true",
"max_installments_with_interest": "12",
"min_installments_with_interest": "01",
"prefixes": {
"TRAT": "2",
"PERIFERICO": "1"
},
"visa_checkout_data": {
"payment_request": {
"currency_code": "BRL",
"subtotal": "115.5",
"total": "115.5",
"order_id": "09387",
"source_id": "LOJAVISACHECK"
},
"user_data": {
"user_first_name": "Comprador",
"user_last_name": "Esitef",
"user_full_name": "Comprador Esitef",
"user_name": "esitef2@gmail.com",
"user_email": "esitef2@gmail.com",
"enc_user_id": "c5DmPXTXC3VwZywsFESEGAqiLM5PXSZG7hgyQgRv0j8=",
"user_personal_id": "12345678909"
},
"creation_time_stamp": 1502206049403,
"payment_instrument": {
"id": "AWUU0/rQrmKCMx+C740kBefZP2GNsdAMYUTXAzCPk+M=",
"last_four_digits": "1010",
"bin_six_digits": "406897",
"verification_status": "VERIFIED",
"expired": "false",
"issuer_bid": "10029901",
"nick_name": "Cartão PAN",
"name_on_card": "aaaaaaaaaa vvvvvvvvvv",
"card_first_name": "aaaaaaaaaa",
"card_last_name": "vvvvvvvvvv",
"payment_type": {
"card_brand": "VISA",
"card_type": "CREDIT"
},
"billing_address": {
"person_name": "aaaaaaaaaa vvvvvvvvvv",
"first_name": "aaaaaaaaaa",
"last_name": "vvvvvvvvvv",
"line1": "qqqqqqqqqq",
"line2": "eeeeee",
"line3": "wwwwwwwww",
"city": "cccccccc",
"state_province_code": "SP",
"postal_code": "01238010",
"country_code": "BR",
"phone": "987654321",
"default": "false"
},
"card_arts": {
"card_art": [
{
"base_image_file_name": "https://sandbox.secure.checkout.visa.com/VmeCardArts/lg_visa_card.png",
"height": 105,
"width": 164
}
]
},
"expiration_date": {
"month": "11",
"year": "2022"
}
},
"risk_data": {
"advice": "UNAVAILABLE",
"score": 0,
"avs_response_code": "0",
"cvv_response_code": "0",
"age_of_account": "704"
},
"visa_checkout_guest": "false"
}
}
}

Consulta de cartão com planos de financiamento#

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 POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"number":"6543210987654321"
},
"authorizer_id":"313"
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"status": "NOV"
},
"card": {
"acquirer_name": "Via Certa Financiadora",
"authorizer_id": "313",
"authorizer_response_code": "000",
"is_customer_id_required": "false",
"is_expiry_date_required": "true",
"is_installment_funding_enabled": "true",
"is_security_code_required": "true",
"is_spot_sale_enabled": "true",
"is_with_interest_sale_enabled": "true",
"is_without_interest_sale_enabled": "true",
"max_installments_with_interest": "99",
"min_installments_with_interest": "00",
"prefixes": {
"CADSENHA": "11",
"NPSAQ": "0199",
"ECHO": "MIG3DH00000"
},
"financing_plan_list": [
{
"cod_plano": "0201",
"tipo_plano": "02",
"desc_plano": "Plano de Teste para CDC 01 ",
"parc_plano": "99"
},
{
"cod_plano": "0301",
"tipo_plano": "03",
"desc_plano": "Plano de Teste para Saque e CDC 01 ",
"parc_plano": "99"
},
{
"cod_plano": "0201",
"tipo_plano": "02",
"desc_plano": "Plano de Teste para CDC 01 ",
"parc_plano": "99"
},
{
"cod_plano": "0202",
"tipo_plano": "02",
"desc_plano": "Plano de Teste para CDC 02 ",
"parc_plano": "99"
},
{
"cod_plano": "0301",
"tipo_plano": "03",
"desc_plano": "Plano de Teste para Saque e CDC 01 ",
"parc_plano": "99"
},
{
"cod_plano": "0302",
"tipo_plano": "03",
"desc_plano": "Plano de Teste para Saque e CDC 02 ",
"parc_plano": "99"
},
{
"cod_plano": "0303",
"tipo_plano": "03",
"desc_plano": "Plano de Teste para Saque e CDC 03 ",
"parc_plano": "99"
}
]
}
}

Consulta de cartão com dados adicionais para roteamento iCards via SiTef#

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 POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"number":"6543210987654321"
},
"authorizer_id":"38"
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"card": {
"acquirer_name": "iCards",
"authorizer_id": "38",
"authorizer_response_code": "000",
"is_customer_id_required": "true",
"is_expiry_date_required": "true",
"is_installment_funding_enabled": "true",
"is_security_code_required": "true",
"is_spot_sale_enabled": "true",
"is_with_interest_sale_enabled": "true",
"is_without_interest_sale_enabled": "true",
"max_installments_with_interest": "12",
"min_installments_with_interest": "01",
"prefixes": {
"NPSAQ": "0299",
"CAPTPPRE": "1",
"XCAPPREAUT": "11"
},
"is_customer_postal_code_required": "true",
"is_card_holder_required": "true"
},
"payment": {
"status": "NOV"
}
}

Consulta de cartão com dados adicionais para roteamento IPG#

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 POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"number":"4036952187654321"
},
"routing_id":"414"
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"status": "NOV"
},
"details": [
{
"brand": "VISA",
"brand_product_id": "VI",
"card_function": "CREDIT",
"issuer_country": "USA",
"issuer_name": "Simulation"
},
{
"brand": "VISA",
"brand_product_id": "VI",
"card_function": "DEBIT",
"issuer_country": "BRA",
"issuer_name": "Simulation"
}
]
}

Consulta de cartão com envio do tipo de autorizadora#

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 POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"number":"5555555555555555"
},
"authorizer_type":"D"
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"status": "NOV"
},
"card": {
"acquirer_name": "Bin",
"authorizer_id": "1",
"authorizer_response_code": "000",
"is_customer_id_required": "false",
"is_expiry_date_required": "true",
"is_installment_funding_enabled": "true",
"is_security_code_required": "true",
"is_spot_sale_enabled": "true",
"is_with_interest_sale_enabled": "true",
"is_without_interest_sale_enabled": "true",
"max_installments_with_interest": "12",
"min_installments_with_interest": "01",
"prefixes": {
"TRAT": "2",
"PERIFERICO": "1",
"CSEG": "2"
}
}
}

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 consulta de cartão:

ParâmetroDescriçãoFormatoObrigatório
authorizer_idCódigo da autorizadora no Carat. Saiba mais. Este campo só é obrigatório caso o campo wallet_transaction_id seja enviado.
Se esse campo não é enviado, o Carat assume que se trata de um cartão de crédito
< 3 NCOND.
authorizer_typeTipo da autorizadora no Carat.
  • C = Crédito
  • D = Débito
  • G = Gift
Caso este campo não seja enviado, é assumido o valor C.
= 1 ANÃO
routing_idCódigo do roteamento no Carat. Este campo só é obrigatório para obter dados adicionais pela IPG.< 3 NCOND.
card
numberNúmero do cartão do comprador (PAN).< 19 NSIM
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
wallet_transaction_idID de uma transação de carteiras digitais. Por enquanto, essa funcionalidade está disponível apenas para a autorizadora Visa Checkout (authorizer_id:406).
Não é permitido enviar um número de cartão aberto (campo number), um cartão armazenado (campo token) e um wallet_transaction_id na mesma requisição.
< 25 ANNÃO
do_par_inquiryInforma se a chamada para o VISA PAR Inquiry será realizada. O Valor resposta será retornado no campo par do do retorno da chamada.

Valores permitidos:
true - Requisição de PAR será realizada
false - Requisição de PAR não será realizada.

Valor default: false
< 5 ANÃO

Parâmetros de resposta#

Em caso de sucesso, o código de resposta HTTP será 200. 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 consulta de cartão:

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
statusStatus da transação de pagamento no Carat. Saiba mais.= 3 AN
card
authorizer_codeCódigo de resposta do autorizador.< 10 AN
authorizer_messageMensagem de resposta do autorizador.< 500 AN
acquirer_nameNome do roteamento. Ex.: Cielo< 256 AN
authorizer_idCódigo da autorizadora (utilizar este ID ao realizar o pagamento).< 3 N
is_customer_id_requiredIndica a obrigatoriedade da coleta do documento do cliente.< 5 T/F
is_expiry_date_requiredIndica a obrigatoriedade da coleta da data de validade do cartão do comprador.< 5 T/F
is_installment_funding_enabledIndica se o parcelamento está habilitado.< 5 T/F
is_security_code_requiredIndica a obrigatoriedade da coleta do código de segurança.< 5 T/F
is_spot_sale_enabledIndica se o pagamento à vista está habilitado.< 5 T/F
is_with_interest_sale_enabledIndica se o pagamento com juros está habilitado.< 5 T/F
is_without_interest_sale_enabledIndica se o pagamento sem juros está habilitado.< 5 T/F
max_installments_with_interestParcelamento máximo com juros.< 2 N
min_installments_with_interestParcelamento mínimo com juros.< 2 N
visa_checkout_dataObjeto com os dados retornados pela Visa Checkout.O
financing_plan_listObjeto que consiste em um array de planos de financiamento apresentados em roteamento Via Certa Financiadora. Um plano de financiamento consiste dos seguintes campos:
cod_plano: código de identificação do plano de financiamento, que deve ser enviado no momento da efetivação do pagamento;
tipo_plano: código do tipo do plano de financiamento;
desc_plano: descrição do plano, que pode ser apresentado ao comprador;
parc_plano: número máximo de parcelas possíveis para o plano.
O
is_customer_postal_code_requiredIndica a obrigatoriedade da coleta do código postal do usuário (CEP no Brasil).< 5 T/F
parValor do PAR retornado pela VISA caso o campo do_par_inquiry seja enviado com o valor true na requisição.< 32 AN
card.prefixes[]Este campo contém os prefixos (dados adicionais) retornados pelo SiTef.
keyNome do prefixo.< 1024 AN
valueValor do prefixo.< 1024 AN
details[]Este campo contém detalhamentos retornados pelo roteamento IPG
brandA bandeira do cartão. The card brand.< 1024 AN
brand_product_idID de produto da bandeira do cartão. The product ID of the brand.< 1024 AN
card_functionFunção do cartão. Card function.CREDIT,
DEBIT,
PREPAID,
VOUCHER,
UNDEFINED
commercialCardIndica se o cartao é corporativo ou nao-corporativo. Indicates whether it is a corporate or non-corporate card.CORPORATE,
NON_CORPORATE
issuer_countryO país da emissora do cartão. The country of the issuer.< 1024 AN
issuer_nameO nome da emissora do cartão. The name of the issuer.< 1024 AN

Roteamentos que permitem consulta de cartão.#

Cód.RoteamentoPossui consulta de cartão
1004VisaNet via SiTef (rede:4)
1005Redecard via SiTef (rede:5)
1018Standby (Excard) via SiTef (rede:18)
1019Edmcard via SiTef (rede:19)
1021Vero via SiTef (rede:21)
1026CCCWeb (Master/Visa/Amex) via SiTef (rede:26)
1029Softway via SiTef (rede:29)
1030Multicheque via SiTef (rede:30)
70Ticket via SiTef (rede:41)
430Senff via SiTef (rede:43)
1045Coopercred via SiTef (rede:45)
1047Sorocred via SiTef (rede:47)
1051Hipercard via SiTef (rede:51)
1052Tricard via SiTef (rede:52)
1054Policard via SiTef (rede:54)
1057CCC (Master/Visa) via SiTef (rede:57)
1059Telenet via SiTef (rede:59)
1061Brasilcard via SiTef (rede:61)
1064CCC (Amex) via SiTef (rede:64)
1068Banese via SiTef (rede:68)
1072Bigcard via SiTef (rede:72)
1077Valecard via SiTef (rede:77)
1081Supercard via SiTef (rede:81)
1182GetNet via SiTef (rede:82)
1086Marisa via SiTef (rede:86)
1087Maxicred via SiTef (rede:87)
1089Expansiva via SiTef (rede:89)
1091Leader II via SiTef (rede:91)
1093Cetelem via SiTef (rede:93)
1094Cabal via SiTef (rede:94)
1095Credsystem via SiTef (rede:95)
1096BBVA via SiTef (rede:96)
1102Check Check (Smart Shop) via SiTef (rede:102)
1103Dacasa via SiTef (rede:103)
1104Bradesco Private Label via SiTef (rede:104)
1105Platinum (Credimais) via SiTef (rede:105)
1111Tredenexx via SiTef (rede:111)
1113Credishop via SiTef (rede:113)
1115IBI via SiTef (rede:115)
1118Oboe via SiTef (rede:118)
1121Hot Card via SiTef (rede:121)
1122PAN via SiTef (rede:122)
1125Cielo via SiTef (rede:125)
1127Marisa Cartao Presente via SiTef (rede:127)
1128Cooplife via SiTef (rede:128)
1129BOD via SiTef (rede:129)
1144Accredito (ACSP) via SiTef (rede:144)
1149Fidelidade Mais via SiTef (rede:149)
160Orbitall via SiTef (rede:160)
1161iCards via SiTef (rede:161)
1165Banco Ge (Tivit) via SiTef (rede:165)
1169Banescard via SiTef (rede:169)
1181GetNet Lac via SiTef (rede:181)
1187Sicredi - nao usar, usar o bin via SiTef (rede:187)
1192AVISTA via SiTef (rede:192)
1193Algorix via SiTef (rede:193)
1194Amex EMV via SiTef (rede:194)
1006Amex EMV via SiTef (rede:194)
1201SmartNet via SiTef (rede:201)
1203Peela via SiTef (rede:203)
1206GlobalPayments via SiTef (rede:206)
1207Elavon via SiTef (rede:207)
218Hug via SiTef (rede:218)
225Fidelity via SiTef (rede:225)
1229Bin via SiTef (rede:229)
1236Conductor via SiTef (rede:236)
1249Riachuelo PL via SiTef (rede:249)
1257Bradescard via SiTef (rede:257)
1265Stone via SiTef (rede:265)
1266DM Card via SiTef (rede:266)
1271CardSE via SiTef (rede:271)
1279Sodexo via SiTef (rede:279)
1280Kredilig via SiTef (rede:280)
1283ConductorDUP via SiTef (rede:283)
1296Safra via SiTef (rede:296)
1297Rede Ticket via SiTef (rede:297)
1303SiPag via SiTef (rede:303)
1309ADIQ via SiTef (rede:309)
1313Via Certa Financiadora via SiTef (rede:313)