Boleto Citibank

O Carat permite pagamentos de boletos pelo Citibank.

Nesta página será usada a nomenclatura "Citibank" para referenciar o roteamento no Carat.

Interfaces Carat suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento Citibank:

• Pagamento REST
• Pagamento HTML
• Reimpressão de Boletos

Credenciais necessárias

A loja deve obter com o Citibank as credenciais listadas abaixo, e repassá-las à Software Express.

Campo	Descrição do campo	Formato	Obrigatório
codigoBeneficiario	Código do convênio da empresa (loja) no Citibank.	= 20 N	Sim
codigoAgenciaBeneficiario	Agência da empresa no Citibank	≤ 5 N	Sim
mensagemBeneficiario	Mensagem do Beneficiário. Não utilizar caractere especial diferente de “/”, “-“ , “;” ou "@".	≤ 40 N	Sim

A loja também, pode solicitar a configuração de alguns parâmetros de boleto com valores padrão junto à Software Express.

Campo	Descrição do campo	Formato	Obrigatório
quantidadeDiasCalculoVencimento	Número de dias para cálculo da data padrão de vencimento do boleto.	≤ 2 N	Não
mensagemReciboPagador	Mensagem padrão exibida na área de recibo pagador do boleto. Obs.: até duas linhas com no máximo 40 caracteres.	≤ 40 AN	Não
mensagemFichaCompensacao	Mensagem padrão exibida na áera de ficha de compensação do boleto. Obs.: até duas linhas com no máximo 40 caracteres.	≤ 40 AN	Não

Fluxo de Pagamento com Citibank

1. Geração do boleto efetuado com sucesso.
2. A Transação de pagamento permanecerá no status 'Processado'.
3. O lojista receberá do Citibank um arquivo com os dados dos boletos e situação, informando se foram pagos.

Pagamento REST

O pagamento de boleto segue o fluxo normal de pagamento

Criar transação

Mais detalhes no tópico Criar transação

Ex:

{

"merchant_usn": "7112400307",

"order_id": "07112400307",

"amount": "2400",

"installments": "1",

"installment_type": "4",

"authorizer_id": "2601",

"additional_data": {

"payer": {

"name": "Steve",

"surname": "Harris",

"address": {

"zip_code": "01307001",

"street_number": "35",

"street_name": "Avenida Paulista",

"complement": "Ap 10",

"district": "bela vista",

"city": "São Paulo",

"state": "SP",

"country": "BR"

},

"documents": [

{

"type": "CPF",

"number": "60861648005"

}

]

},

"boleto": {

"assignor_code": "99999999999999999999",

"your_number": "1646940087",

"expiration_date": "20/03/2022",

"issue_date": "10/03/2022",

"specie_type": "01",

"company_identification": "identificacao_empresa",

"assignor": "XPTO COMPUTADORES DO BRASIL LTDA",

"assignor_document": {

"type": "CNPJ",

"number": "72381189000110"

},

"assignor_address": {

"zip_code": "01307001",

"street_number": "999",

"street_name": "Avenida YYZ",

"complement": "Ap 3000",

"district": "bela vista",

"city": "São Paulo",

"state": "SP",

"country": "BR"

},

"instructions": [

{

"message": "ficha_compensacao msg1"

},

{

"message": "ficha_compensacao msg2"

}

],

"receipt_messages": [

{

"message": "recibo msg1"

},

{

"message": "recibo msg2"

}

]

}

}

}

Efetivar transação

Mais detalhes no tópico Efetivar transação

A resposta do efetivar pagamento devolve alguns dados exclusivos do pagamento de boleto

Campo	Descrição
payment.boleto	Dados especificos do pagamento com boleto
digitable_line	Linha digitavel
url	Url para visualização do boleto

Ex requisição:

{

"authorizer_id": "2601"

}

Ex resposta:

{

"code": "0",

"message": "OK. Transaction successful.",

"payment": {

"authorizer_message": "OK",

"status": "PRO",

"nit": "9901701cc1631cf6fc71a38b0a6e8dba8b8130f2ad1c3109643753223dba312b",

"order_id": "07112400307",

"authorizer_id": "2601",

"acquirer_id": "2601",

"acquirer_name": "Boleto Citibank",

"merchant_usn": "7112400307",

"esitef_usn": "220310093364750",

"amount": "2400",

"payment_type": "B",

"payment_date": "10/03/2022T16:29",

"boleto": {

"digitable_line": "47720953885052730207262219741330432820197130661",

"url": "https://{{url}}/e-sitef/reissue.se?nit=9901701cc1631cf6fc71a38b0a6e8dba8b8130f2ad1c3109643753223dba312b"

}

}

}

Web Checkout

Criar transação

Mais detalhes no tópico Criar transação

Ex:

{

"merchant_id": "BOLETOCITI",

"merchant_usn": "7112400307",

"order_id": "07112400307",

"amount": "2400",

"installments": "1",

"installment_type": "4",

"authorizer_id": "2601",

"additional_data": {

"payer": {

"name": "Steve",

"surname": "Harris",

"address": {

"zip_code": "01307001",

"street_number": "35",

"street_name": "Avenida Paulista",

"complement": "Ap 10",

"district": "bela vista",

"city": "São Paulo",

"state": "SP",

"country": "BR"

},

"documents": [

{

"type": "CPF",

"number": "60861648005"

}

]

},

"boleto": {

"assignor_code": "99999999999999999999",

"your_number": "1646940087",

"expiration_date": "17/08/2022",

"issue_date": "10/03/2022",

"specie_type": "01",

"company_identification": "identificacao_empresa",

"assignor": "XPTO COMPUTADORES DO BRASIL LTDA",

"assignor_document": {

"type": "CNPJ",

"number": "72381189000110"

},

"assignor_address": {

"zip_code": "01307001",

"street_number": "999",

"street_name": "Avenida YYZ",

"complement": "Ap 3000",

"district": "bela vista",

"city": "São Paulo",

"state": "SP",

"country": "BR"

},

"instructions": [

{

"message": "ficha_compensacao msg1"

},

{

"message": "ficha_compensacao msg2"

}

],

"receipt_messages": [

{

"message": "recibo msg1"

},

{

"message": "recibo msg2"

}

]

}

}

}

Dados opcionais no Web Checkout

Caso não sejam enviados os dados de Nome, Documento e Endereço do comprador, será exibido um fomulário para o comprador preencher.

Dados necessários

Para que um pagamento via boleto bancário seja feito pelo usuário, é necessário que a loja envie para o Carat as seguintes informações dentro do objeto additional_data na criação da transação:

Campo	Descrição	Formato	Obrigatório
additional_data.payer
name	Nome do comprador. Obs.: a concatenação de nome com o sobrenome não pode ultrapassar 255 caracteres.	< 200 AN	Sim
surname	Sobrenome do comprador. Obs.: a concatenação do nome com o sobrenome não pode ultrapassar 255 caracteres.	< 200 AN	Sim
additional_data.payer.address
street_name	Endereço do comprador.	< 150 AN	Sim
street_number	Número do endereço do comprador.	< 20 AN	Sim
complement	Complemento do endereço do comprador.	< 100 AN	Não
zip_code	CEP do endereço do comprador.	< 8 N	Sim
city	Cidade do endereço do comprador.	< 50 AN	Não
state	Estado do endereço do comprador.	= 2 AN	Não
country	País do endereço do comprador seguindo a AN 3166-1. Ex.: BRA	= 3 AN	Não
additional_data.boleto
assignor_code	Código do Convênio no Banco	= 20 N	Não
bank_issuer_code	Numéro agência de relacionamento/convênio	< 7 AN	Não
boleto_number	Código de identificação do boleto. Caso não seja enviado o banco deve gerar um	< 14 N	Não
your_number	Número utilizado e controlado pelo Cliente, para identificar o título de cobrança.	< 11 AN	Não
expiration_date	Data de vencimento do boleto no formato dd/mm/aaaa. Obs.: Caso não seja enviada, será gerada baseada na configuração padrão da autorizadora	< 10 AN	Não
issue_date	Data de emissão do boleto no formato dd/mm/aaaa. Obs.: Caso não seja enviada, será gerada baseada como a data atual	< 10 AN	Não
specie_type	Código adotado para identificar o tipo de título de cobrança: 01 - Cheque 02 - Duplicata Mercantil 03 - Duplicata Mercantil p/ Indicação	= 02 N	Sim
fine_date	Data a partir da qual a multa deverá ser cobrada. Na ausência, será considerada a data de vencimento.	= 10 AN	Não
fine_amount	Valor em centavos da multa por atraso no pagamento.	< 12 AN	Não
fine_percentage	Percentual de multa a ser aplicado sobre o valor do Título, por atraso no pagamento.	< 12 N	Não
company_identification	Campo destinado para uso da Empresa Beneficiário para identificação do Título.	< 25 AN	Não
iof_amount	Valor do IOF a ser recolhido.	< 12 N	Não
assignor	Nome do beneficiário	< 40 AN	Não
additional_data.payer.assignor_document	Documento do beneficiário. Obs: Caso não seja enviado, será utilizado documento configurado na loja
type	Tipo do documento	CPF ou CPNJ	Não
number	Núemro do documento	< 14 N	Não
additional_data.payer.assignor_address	Endereço do beneficiário. Obs: Caso não seja enviado, será utilizado o endereço configurado na loja
street_name	Endereço do beneficiário.	< 150 AN	Sim
street_number	Número do endereço do beneficiário.	< 20 AN	Sim
complement	Complemento do endereço do beneficiário.	< 100 AN	Não
zip_code	CEP do endereço do beneficiário.	< 8 N	Sim
city	Cidade do endereço do beneficiário.	< 50 AN	Não
state	Estado do endereço do beneficiário.	= 2 AN	Não
additional_data.boleto.instructions[]
message	Texto de observações destinado ao envio de mensagens livres, a serem impressas no campo instruções da Ficha de Compensação Obs.: Caso não seja enviada, será utilizada a configuração padrão da autorizadora	< 40 N	Não
additional_data.boleto.receipt_messages[]
message	Texto de observações destinado ao envio de mensagens livres, a serem impressas na parte Recibo do Pagador do boleto Obs.: Caso não seja enviada, será utilizada a configuração padrão da autorizadora	< 40 N	Não
additional_data.boleto.payment
allowed_quantity	Quantidade de pagamento possíveis	< 2 N	Não
type	Identificação do tipo de pagamento	< 35 AN	Sim
minimum_amount	Valor mínimo admissível para pagamento.	< 12 N	Não
maximum_amount	Valor máximo admissível para pagamento.	< 12 N	Não
minimum_percentage	Valor do percentual mínimo admissível para pagamento.	< 12 N	Não
maximum_percentage	Valor do percentual máximo admissível para pagamento.	< 12 N	Não

Reimpressão de boletos

É possível disponibilizar aos compradores a Reimpressão de boletos do Citibank.

Esta funcionalidade está disponível através da URL:

Ambiente de Produção
https://esitef-ec.softwareexpress.com.br/e-sitef/reissue.se?nit=XXX
Ambiente de Homologação
https://{{url}}/e-sitef-hml/reissue.se?nit=XXX

Deve-se informar como parâmetro do GET o nit utilizado da transação original de pagamento, feita via Boleto Citibank. O acesso a esta URL permite a visualização do boleto.

Caso a transação de pagamento não esteja no estado esperado, é apresentada uma mensagem de erro.

Atenção

Nunca deve ser usado o IP ao invés do domínio esitef-ec.softwareexpress.com.br (ou esitef- homologacao.softwareexpress.com.br para ambiente de homologação). O IP pode mudar a qualquer instante e sem aviso prévio, logo é importante sempre utilizar o domínio para acessar o Carat.