Serviço de consulta de cartão

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:

O lojista cria uma transação no e-SiTef 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).
O lojista envia o NIT obtido na etapa anterior e os dados do cartão a ser consultado. Com isso, o e-SiTef retorna dados sobre as capacidades do cartão enviado.
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âmetro	Descrição	Formato	Obrigatório
`merchant_id`	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
`merchant_key`	Chave de autenticação da loja no e-SiTef. 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

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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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":"Redecard",
      "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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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":"Redecard",
      "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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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":"Redecard",
      "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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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"
    }
  ]
}

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âmetro	Descrição	Formato	Obrigatório
`authorizer_id`	Código da autorizadora no e-SiTef. Saiba mais. Este campo só é obrigatório caso o campo `wallet_transaction_id` seja enviado. Se esse campo não é enviado, o e-SiTef assume que se trata de um cartão de crédito	< 3 N	COND.
`routing_id`	Código do roteamento no e-SiTef. Este campo só é obrigatório para obter dados adicionais pela IPG.	< 3 N	COND.
	card
`number`	Número do cartão do comprador (PAN).	< 19 N	SIM
`token`	HASH de um cartão armazenado no e-SiTef. 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 AN	NÃO
`wallet_transaction_id`	ID 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 AN	NÃO
`do_par_inquiry`	Informa 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 A	NÃ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âmetro	Descrição	Formato
`code`	Código de resposta do e-SiTef. Qualquer código diferente de `0` significa falha. Saiba mais.	< 4 N
`message`	Mensagem de resposta do e-SiTef.	< 500 AN
	payment
`status`	Status da transação de pagamento no e-SiTef. Saiba mais.	= 3 AN
	card
`authorizer_code`	Código de resposta do autorizador.	< 10 AN
`authorizer_message`	Mensagem de resposta do autorizador.	< 500 AN
`acquirer_name`	Nome do roteamento. Ex.: Cielo	< 256 AN
`authorizer_id`	Código da autorizadora (utilizar este ID ao realizar o pagamento).	< 3 N
`is_customer_id_required`	Indica a obrigatoriedade da coleta do documento do cliente.	< 5 T/F
`is_expiry_date_required`	Indica a obrigatoriedade da coleta da data de validade do cartão do comprador.	< 5 T/F
`is_installment_funding_enabled`	Indica se o parcelamento está habilitado.	< 5 T/F
`is_security_code_required`	Indica a obrigatoriedade da coleta do código de segurança.	< 5 T/F
`is_spot_sale_enabled`	Indica se o pagamento à vista está habilitado.	< 5 T/F
`is_with_interest_sale_enabled`	Indica se o pagamento com juros está habilitado.	< 5 T/F
`is_without_interest_sale_enabled`	Indica se o pagamento sem juros está habilitado.	< 5 T/F
`max_installments_with_interest`	Parcelamento máximo com juros.	< 2 N
`min_installments_with_interest`	Parcelamento mínimo com juros.	< 2 N
`visa_checkout_data`	Objeto com os dados retornados pela Visa Checkout.	O
`financing_plan_list`	Objeto 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_required`	Indica a obrigatoriedade da coleta do código postal do usuário (CEP no Brasil).	< 5 T/F
`par`	Valor 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.
key	Nome do prefixo.	< 1024 AN
value	Valor do prefixo.	< 1024 AN
details[]	Este campo contém detalhamentos retornados pelo roteamento IPG
brand	A bandeira do cartão. The card brand.	< 1024 AN
brand_product_id	ID de produto da bandeira do cartão. The product ID of the brand.	< 1024 AN
card_function	Função do cartão. Card function.	CREDIT, DEBIT, PREPAID, VOUCHER, UNDEFINED
commercialCard	Indica se o cartao é corporativo ou nao-corporativo. Indicates whether it is a corporate or non-corporate card.	CORPORATE, NON_CORPORATE
issuer_country	O país da emissora do cartão. The country of the issuer.	< 1024 AN
issuer_name	O nome da emissora do cartão. The name of the issuer.	< 1024 AN

Roteamentos que permitem consulta de cartão.

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