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.

CampoDescrição do campoFormatoObrigatório
codigoBeneficiarioCódigo do convênio da empresa (loja) no Citibank.= 20 NSim
codigoAgenciaBeneficiarioAgência da empresa no Citibank≤ 5 NSim
mensagemBeneficiarioMensagem do Beneficiário. Não utilizar caractere especial diferente de “/”, “-“ , “;” ou "@".≤ 40 NSim

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

CampoDescrição do campoFormatoObrigatório
quantidadeDiasCalculoVencimentoNúmero de dias para cálculo da data padrão de vencimento do boleto.≤ 2 NNão
mensagemReciboPagadorMensagem padrão exibida na área de recibo pagador do boleto. Obs.: até duas linhas com no máximo 40 caracteres.≤ 40 ANNão
mensagemFichaCompensacaoMensagem padrão exibida na áera de ficha de compensação do boleto. Obs.: até duas linhas com no máximo 40 caracteres.≤ 40 ANNã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

CampoDescrição
payment.boletoDados especificos do pagamento com boleto
digitable_lineLinha digitavel
urlUrl 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:

CampoDescriçãoFormatoObrigatório
additional_data.payer
nameNome do comprador.
Obs.: a concatenação de nome com o sobrenome não pode ultrapassar 255 caracteres.
< 200 ANSim
surnameSobrenome do comprador.
Obs.: a concatenação do nome com o sobrenome não pode ultrapassar 255 caracteres.
< 200 ANSim
additional_data.payer.address
street_nameEndereço do comprador.< 150 ANSim
street_numberNúmero do endereço do comprador.< 20 ANSim
complementComplemento do endereço do comprador.< 100 ANNão
zip_codeCEP do endereço do comprador.< 8 NSim
cityCidade do endereço do comprador.< 50 ANNão
stateEstado do endereço do comprador.= 2 ANNão
countryPaís do endereço do comprador seguindo a AN 3166-1. Ex.: BRA= 3 ANNão
additional_data.boleto
assignor_codeCódigo do Convênio no Banco= 20 NNão
bank_issuer_codeNuméro agência de relacionamento/convênio< 7 ANNão
boleto_numberCódigo de identificação do boleto. Caso não seja enviado o banco deve gerar um< 14 NNão
your_numberNúmero utilizado e controlado pelo Cliente, para identificar o título de cobrança.< 11 ANNão
expiration_dateData 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 ANNão
issue_dateData de emissão do boleto no formato dd/mm/aaaa.
Obs.: Caso não seja enviada, será gerada baseada como a data atual
< 10 ANNão
specie_typeCódigo adotado para identificar o tipo de título de cobrança:
01 - Cheque
02 - Duplicata Mercantil
03 - Duplicata Mercantil p/ Indicação
= 02 NSim
fine_dateData a partir da qual a multa deverá ser cobrada. Na ausência, será considerada a data de vencimento.= 10 ANNão
fine_amountValor em centavos da multa por atraso no pagamento.< 12 ANNão
fine_percentagePercentual de multa a ser aplicado sobre o valor do Título, por atraso no pagamento.< 12 NNão
company_identificationCampo destinado para uso da Empresa Beneficiário para identificação do Título.< 25 ANNão
iof_amountValor do IOF a ser recolhido.< 12 NNão
assignorNome do beneficiário< 40 ANNão
additional_data.payer.assignor_documentDocumento do beneficiário. Obs: Caso não seja enviado, será utilizado documento configurado na loja
typeTipo do documentoCPF ou CPNJNão
numberNúemro do documento< 14 NNão
additional_data.payer.assignor_addressEndereço do beneficiário. Obs: Caso não seja enviado, será utilizado o endereço configurado na loja
street_nameEndereço do beneficiário.< 150 ANSim
street_numberNúmero do endereço do beneficiário.< 20 ANSim
complementComplemento do endereço do beneficiário.< 100 ANNão
zip_codeCEP do endereço do beneficiário.< 8 NSim
cityCidade do endereço do beneficiário.< 50 ANNão
stateEstado do endereço do beneficiário.= 2 ANNão
additional_data.boleto.instructions[]
messageTexto 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 NNão
additional_data.boleto.receipt_messages[]
messageTexto 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 NNão
additional_data.boleto.payment
allowed_quantityQuantidade de pagamento possíveis< 2 NNão
typeIdentificação do tipo de pagamento< 35 ANSim
minimum_amountValor mínimo admissível para pagamento.< 12 NNão
maximum_amountValor máximo admissível para pagamento.< 12 NNão
minimum_percentageValor do percentual mínimo admissível para pagamento.< 12 NNão
maximum_percentageValor do percentual máximo admissível para pagamento.< 12 NNã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.