Serviço de Consulta de Cartões

A partir de um NIT de pré autorização 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

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

Recursos: /v1/preauthorizations/{nit}/cards
Método HTTP: POST

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

Formato da requisição: JSON
Formato da resposta: JSON
Parâmetros de cabeçalho:

Nome do Parâmetro	Descrição	Tipo	Tamanho	Obrigatório
`merchant_id`	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	AN	≤ 15	SIM
`merchant_key`	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	AN	≤ 80	SIM
`Content-Type`	Deve ser enviado com o valor "application/json".	AN	= 15	SIM

Exemplo de Consulta de cartão com envio de autorizadora

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456
7890abcdefghijklmnopqr /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.",
    "preauthorization":{
        "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"
        }
    }
}

Exemplo de Consulta de cartão sem envio de autorizadora

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456
7890abcdefghijklmnopqr/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.",
    "preauthorization":{
        "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"
        }
    }
}

Exemplo de Consulta de cartão Visa Checkout

Requisição:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123
4567890abcdefghijklmnopqr/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.",
    "preauthorization":{
        "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",
                "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"
        }
    }
}

Exemplo de 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/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456
7890abcdefghijklmnopqr/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"
    },
    "preauthorization": {
        "status": "NOV"
    }
}

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:

Nome do Parâmetro	Descrição	Tipo	Tamanho	Obrigatório
`authorizer_id`	Código da autorizadora no e-SiTef, conforme listado na lista de autorizadoras. Este campo só é obrigatório caso o campo "wallet_transaction_id" seja enviado.	N	≤ 3	NÃO
`number`	Número do cartão do comprador (PAN).	N	≤ 19	NÃO
`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.	AN	= 88	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.	AN	≤ 25	NÃO

Obs: Apesar de não obrigatório, recomenda-se o envio do authorizer_id para a consulta de cartão, principalmente para roteamentos via SiTef, a fim de comportamentos mais efetivos em relação ao roteamento cadastrado para a autorizadora.

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:

Nome do Parâmetro	Descrição	Tipo	Tamanho
`code`	Código de resposta do e-SiTef. Qualquer código diferente de ‘0’ significa falha. Para maiores informações, consulte o documento "Anexo A-2 – Codigos de Resposta".	N	≤ 4
`message`	Mensagem de resposta do e-SiTef.	AN	≤ 500
`status`	Status da transação de pré-autorização no e-SiTef.	AN	= 3
`authorizer_code`	Código de resposta do autorizador.	AN	≤ 10
`authorizer_message`	Mensagem de resposta do autorizador.	AN	≤ 500
`acquirer_name`	Nome do roteamento. Ex.: Cielo	AN	≤ 256
`authorizer_id`	Código da autorizadora.	N	≤ 3
`is_customer_id_required`	Indica a obrigatoriedade da coleta do documento do cliente.	T/F	≤ 5
`is_expiry_date_required`	Indica a obrigatoriedade da coleta da data de validade do cartão do comprador.	T/F	≤ 5
`is_installment_funding_enabled`	Indica se o parcelamento está habilitado.	T/F	≤ 5
`is_security_code_required`	Indica a obrigatoriedade da coleta do código de segurança.	T/F	≤ 5
`is_spot_sale_enabled`	Indica se o pagamento à vista está habilitado.	T/F	≤ 5
`is_with_interest_sale_enabled`	Indica se o pagamento com juros está habilitado.	T/F	≤ 5
`is_without_interest_sale_enabled`	Indica se o pagamento sem juros está habilitado.	T/F	≤ 5
`max_installments_with_interest`	Parcelamento máximo com juros.	N	≤ 2
`min_installments_with_interest`	Parcelamento mínimo com juros.	N	≤ 2
`visa_checkout_data`	Objeto com os dados retornados pela Visa Checkout.
`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.
`is_customer_postal_code_required`	Indica a obrigatoriedade da coleta do código postal do usuário (CEP no Brasil).	T/F	< 5
`key`	Nome do prefixo.	AN	≤ 1024
`value`	Valor do prefixo	AN	≤ 1024