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#
- Geração do boleto efetuado com sucesso.
- A Transação de pagamento permanecerá no status 'Processado'.
- 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:
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:
Ex resposta:
Web Checkout#
Criar transação#
Mais detalhes no tópico Criar transação
Ex:
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.