Bin

Neste item serão apresentadas caracteristicas especificas para o roteamento Bin via SiTef.

Pagamento REST#

Efetivação de Pagamento#

A seguir, são listados os parâmetros com dados específicos para a transação via Bin que o aplicativo da loja virtual pode enviar no serviço de efetivação de pagamento REST:

Parâmetro	Descrição	Formato	Obrigatório
external_authentication
`ucaf_sli`	Contêm o UCAF (Universal Cardholder Authentication Field), que corresponde ao último dígito do SLI (Security Level Indicator) do Mastercard Secure Code (para bandeira MasterCard).	= 1 N	NÃO
`version`	Versão do 3DS (`1` ou `2`).	= 1 N	NÃO
`reference_id`	Identificador do Directory Server para transações 3DS 2.0.	< 36 AN	NÃO
`tavv`	Criptograma de transação tokenizada DSRP-UCAF.	< 40 AN	NÃO
`cavv`	Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.	< 40 N	NÃO

Parâmetros de Card-On-File#

Os parâmetros usage e reason são usados nas operações de pagamento simples e nas operações de efetivação de pagamento geralmente envolvendo cartão tokenizado. A combinação deles dá a adquirente mais informações para garantir um maior número de aprovações.

Definições#

Para os parâmetros usage e reason, dentro de acquirer.card_on_file, são aceitos os seguintes valores:

`usage`	Significado
`first`	Indica primeira ocorrência
`subsequent`	Indica demais ocorrências da recorrência
`authorized`	Para uso junto com o parametro `reason=card`, indicando que o usuário autorizou o armazenamento do cartão

`reason`	Significado
`cardholder`	Compras subsequentes disparadas pelo titular do cartão
`unscheduled`	Compra recorrente sem agendamento
`recurring`	Compra recorrente agendada
`installment`	Parcelamento através de recorrencia
`card`	Para uso junto com o parametro `usage=authorized`, indicando que o usuário autorizou o armazenamento do cartão

MIT e CIT#

Existem dois tipos de transações de card-on-file: CIT (Iniciadas pelo titular do cartão) e MIT (Iniciadas pelo lojista)

Sigla	Significado
CIT	É qualquer transação onde o titular do cartão participa ativamente da transação, seja via terminal da loja ou através da experiência online de pagamento
MIT	É uma transação subsequente com credenciais já armazenadas, para a qual o titular do cartão deu consentimento prévio ao comerciante para armazenar credenciais de pagamento para uso futuro, sem seu envolvimento ativo. Tal seria o caso da cobrança automática de serviços de assinatura, para citar um exemplo.

Combinações válidas#

`usage`	`reason`	Significado	MIT/CIT?
`authorized`	`card`	Indica que o usuário autorizou o armazenamento do cartão	CIT
`first`	`unscheduled`	Indica um pagamento avulso	MIT
`first`	`recurring`	Indica a primeira a primeira ocorrência de uma recorrência	MIT
`subsequent`	`recurring`	Indica as ocorrências subsequentes de uma recorrência	MIT
`subsequent`	`cardholder`	Indica um pagamento feito pelo usuário com o cartão já armazenado	CIT
`subsequent`	`unscheduled`	Indica uma ocorrência subsequente não agendada iniciada pelo lojista	MIT
`subsequent`	`installment`	Indica parcelamento por recorrência	MIT

Pagamento Split#

O roteamento Bin via SiTef permite o Split de Pagamento, para direcionar partes do valor para até 5 estabelecimentos adicionais. Para esta modalidade, deve ser preenchido o parâmetro acquirer.submerchant_split.

Parâmetro	Descrição	Formato	Obrigatório
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_code`	código de estabelecimento BIN/Sipag	< 51 AN	NÃO
`submerchant_amount`	valor de transação referente ao estabelecimento	< 12 N	NÃO

O exemplo abaixo apresenta o seguinte cenário:

Loja principal que utiliza as credenciais merchant_id e merchant_key no Carat, iniciando a criação de transação de valor total 130 reais;
- Loja identificada com o código de estabelecimento empresa01 na adquirente, com valor direcionado de 10 reais;
- Loja identificada com o código de estabelecimento empresa02 na adquirente, com valor direcionado de 20 reais;
- Loja identificada com o código de estabelecimento empresa03 na adquirente, com valor direcionado de 20 reais;
- Loja identificada com o código de estabelecimento empresa04 na adquirente, com valor direcionado de 30 reais;
- Loja identificada com o código de estabelecimento empresa05 na adquirente, com valor direcionado de 30 reais;

Assim, indiretamente o valor direcionado para a loja principal seria de 20 reais (130 - 10 - 20 - 20 - 30 -30 = 20).

Resumindo, o valor direcionado para a loja principal não deve ser listado no parâmetro acquirer.submerchant_split.

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"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   },
   "acquirer":{
      "submerchant_split":[
         {
            "submerchant_code":"empresa01",
            "submerchant_amount":"1000"
         },
         {
            "submerchant_code":"empresa02",
            "submerchant_amount":"2000"
         },
         {
            "submerchant_code":"empresa03",
            "submerchant_amount":"2000"
         },
         {
            "submerchant_code":"empresa04",
            "submerchant_amount":"3000"
         },
         {
            "submerchant_code":"empresa05",
            "submerchant_amount":"3000"
         }
      ]
   }
}
--verbose

Resposta:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "APROVADA",
    "status": "CON",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "authorizer_id": "1",
    "acquirer_id": "229",
    "acquirer_name": "Bin",
    "authorizer_date": "29/03/2019T13:26",
    "authorization_number": "000058",
    "merchant_usn": "20180809",
    "esitef_usn": "190329026585100",
    "sitef_usn": "000058",
    "host_usn": "003000058   ",
    "amount": "13000",
    "payment_type": "C",
    "issuer": "1",
    "authorizer_merchant_id": "000000000000000",
    "payment_date": "29/03/2019T13:26"
  }
}

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âmetro	Descrição	Formato	Obrigatório
`card`
`number`	Token gerado pela bandeira (DPAN)	≤ 19 N	Sim
`cryptogram`	Criptograma gerado pela bandeira.	= 28 A	Sim para pagamentos com token bandeira
`wallet_type`	Campo que especifica se a transação é processada com PAN ou DPAN. Se houver uma transação tokenizada, deverá enviar o valor “network_token”.	AN	Sim 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
--request POST "https://{{url}}/e-sitef/api/v2/payments/"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"1709151775",
   "order_id":"0001709151774770",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"100",
   "soft_descriptor": "Empresa Aluguel de carros XYZ",
    "card":{
      "number":"555555555555555",
      "expiry_date":"1227",
      "security_code":"157",
      "cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
      "wallet_type": "network_token"
   }
}
--verbose

Parâmetros de resposta

Parâmetro	Descrição	Formato
`card`
`par`	A EMVCo introduziu o PAR (Payment Account Reference) para fornecer uma abordagem alinhada ao setor, projetada para ajudar a vincular todas as transações associadas a uma conta específica, baseado em token, sem usar o PAN como mecanismo de ligação.	< 32
`suffix`	Últimos quatro dígitos do PAN, devolvido pelas bandeiras Visa e Mastercard em transações realizadas com DPAN (Token bandeira).	= 4

Resposta Pagamento:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "TRANSACAO APROVADA",
        "status": "CON",
        "nit": "1854a5dac2033afc012c4ed807183bf77f6179a75c79ec81c770a0bde8aef583",
        "order_id": "0001709151774770",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin (Via Servicos TEF)",
        "authorizer_date": "28/02/2024T17:22",
        "authorization_number": "226596",
        "merchant_usn": "1709151775",
        "esitef_usn": "240228062687260",
        "sitef_usn": "816339",
        "host_usn": "43734572890",
        "amount": "100",
        "payment_type": "C",
        "terminal_id": "ES000001",
        "card_par": "hI3C1LmpTY46qNx4YlsyOvbRQBg3o",
        "payment_date": "28/02/2024T17:22",
        "recurrency_tid": "055950827503911"
    },
    "card": {
        "par": "hI3C1LmpTY46qNx4YlsyOvbRQBg3o",
        "suffix": "0042"
    }
}

Requisição Pré-Autorização:

curl
--request POST "https://{{url}}/e-sitef/api/v2/preauthorizations/"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"1709151775",
   "order_id":"0001709151774770",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"100",
   "soft_descriptor": "Empresa Aluguel de carros XYZ",
    "card":{
      "number":"555555555555555",
      "expiry_date":"1227",
      "security_code":"157",
      "cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
      "wallet_type": "network_token"
   }
}
--verbose

Resposta Pré-Autorização:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "card": {
        "par": "A80pcFJxz0FgEK6qDggFpM5KUl2Jf",
        "suffix": "0042"
    },
    "pre_authorization": {
        "authorizer_code": "000",
        "authorizer_message": "TRANSACAO APROVADA",
        "status": "CON",
        "nit": "74e3fa7509d683c73240e4868ec7b75b14170547567b809f6f2698f234ab8f4f",
        "order_id": "0001709151682784",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "2651",
        "acquirer_name": "Bin (Via Servicos TEF)",
        "authorizer_date": "28/02/2024T17:21",
        "authorization_number": "242440",
        "merchant_usn": "1709151683",
        "esitef_usn": "240228062687254",
        "sitef_usn": "304331",
        "host_usn": "43734572891",
        "amount": "100",
        "payment_type": "C",
        "terminal_id": "ES000001",
        "card_par": "A80pcFJxz0FgEK6qDggFpM5KUl2Jf",
        "recurrency_tid": "969452034274685"
    }
}

Home