Pagamento
Interface de pagamentos que permite a loja realizar requisições de autorizações de venda
Detalhes da chamada#
- Recurso:
/v2/payments/ - Método HTTP:
POST - Formato da requisição:
JSON - Formato da resposta:
JSON - Parâmetros de cabeçalho:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
merchant_id | Código da loja no Carat. Os códigos de produção e certificação serão diferentes. | < 15 AN | SIM |
merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | < 80 AN | SIM |
Content-Type | Deve ser enviado com o valor application/json. | = 15 AN | SIM |
Exemplos#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
Pagamento Via Sitef - Token#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
Pagamento com captura posterior#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
Requisição de confirmação:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta de confirmação:
Pagamento sem envio do order_id#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
Pagamento de validação de conta - Zero Auth Dollar#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
Pagamento - 3DS#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
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
sandbox.ecomm-bin.fiserv.com.br
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:
Serviço de confirmação de pagamento#
Após criar e efetuar um pagamento pendente de confirmação, o lojista deve chamar o serviço de confirmação para confirmar ou desfazer o pagamento utilizando o mesmo NIT obtido na primeira etapa do fluxo.
Detalhes da chamada#
- Recurso:
/v1/payments/{nit} - Método HTTP:
PUT - Formato da requisição:
query string - Formato da resposta:
JSON - Parâmetros de cabeçalho:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
merchant_id | Código da loja no Carat. Os códigos de produção e certificação serão diferentes. | < 15 AN | SIM |
merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | < 80 AN | SIM |
Exemplo#
Abaixo estão exemplos de chamadas do serviço de confirmação de pagamento utilizando a ferramenta cURL.
Confirmação de pagamento com valor total#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
Confirmação de pagamento com valor parcial#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta:
Parâmetros de requisição#
Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de criação de transações:
| Parâmetro | Descrição | Formato | Obrigatório | |||
|---|---|---|---|---|---|---|
merchant_usn | Número sequencial único para cada pedido, criado pela loja. O NSU será utilizado em toda a comunicação com a loja, de forma a identificar o pedido. Como se trata de uma possível chave para acesso do lado da loja, apesar de ser opcional para o Carat, é fortemente recomendado que o campo seja formatado e enviado pela aplicação da loja. | < 12 N | NÃO | |||
order_id | Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade. Para as transações roteadas pela adquirente Bin, existe uma limitação de 20 caracteres. | < 40 AN | SIM | |||
installments | Número de parcelas. Envie ‘1’ para transações à vista. | < 2 N | SIM | |||
installment_type | Tipo de financiamento do parcelamento: valor 3 = parcelamento com juros da administradora do cartão. valor 4 = parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista). Valor 6 = parcelamento com juros da administradora (IATA). valor 7 = parcelamento realizado pela loja e sem juros (IATA). O parcelamento IATA é utilizado somente por empresas do seguimento de transporte aéreo. | < 2 N | SIM | |||
authorizer_id | Código da autorizadora no Carat. Saiba mais. | < 3 N | NÃO | |||
amount | Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto. | < 12 N | SIM | |||
soft_descriptor | Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais | < 25 AN | NÃO | |||
| card | Dados do cartão. | |||||
number | Número do cartão do comprador (PAN). Token gerado pela bandeira (DPAN) para pagamento com Token Bandeira. Saiba mais | < 19 N | SIM | |||
expiry_date | Data de vencimento do cartão no formato MMAA. Sua obrigatoriedade depende da adquirente escolhida. Na maioria dos casos, esse campo é obrigatório. | = 4 N | COND. | |||
security_code | Código de segurança. Este campo pode não ser obrigatório se a empresa possuir um acordo no contrato firmado com as redes adquirentes, somente para o pagamento de determinados seguimentos. Entretanto é possível configurar a obrigatoriedade do campo nas configurações da loja, consulte o suporte do Carat para mais informações. Importante: um pagamento com agendamento implica no armazenamento dos dados do cartão do comprador no ambiente do Carat. Porém, por questões de segurança, o código de segurança não pode ser armazenado. Por isso, os pagamentos agendados sempre serão executados sem o envio do código de segurança. | < 5 N | COND. | |||
holder | Nome do portador do cartão. | < 30 AN | NO. | |||
token | HASH de um cartão armazenado no Carat. Não é permitido enviar um número de cartão aberto (campo number) e um cartão armazenado (campo token) na mesma requisição. | = 88 AN | NÃO | |||
cryptogram | Criptograma gerado pela bandeira | = 28 AN | NÃO | |||
wallet_type | Campo que especifica se a transação é processada com PAN ou DPAN. Se “tipo” estiver vazio, o valor padrão é PAN (número de cartão não tokenizado). Se houver uma transação tokenizada, deverá enviar o valor “network_token”. | AN | NÃO | |||
| external_authentication | Este elemento recebe campos de resultados de autenticação MPI. | |||||
eci | Eletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão | < 3 N | NÃO | |||
xid | Identificador da transação de autenticação do dono do cartão, feita em serviço externo ao Carat | < 40 N | 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 | |||
| iata | Este elemento contém campos específicos de transações IATA. | |||||
departure_tax | Taxa de embarque em centavos. | < 12 N | SIM apenas para installment_type = 6 ou 7 | |||
| acquirer | Dados específicos necessários dependendo da adquirente/roteamento. | |||||
financing_plan | Código de plano de financiamento. Necessário apenas para pagamentos parcelados com juros roteados pela Via Certa Financiadora via SiTef. | < 4 N | NÃO | |||
special_code | Código de uso geral da Conductor/Renner. | < 6 N | NÃO | |||
mid | Código do estabelecimento da adquirente - Para roteamentos BIN, o MID a ser utilizado pelo estabelecimento é único. Este campo deve ser utilizado caso seja necessário selecionar um MID diferente do padrão. | < 15 AN | COND | |||
recurrency | Flag que define se o pagamento é ou não recorrente. Aceito para todos os roteamentos via SiTef | < 5 T/F | NÃO | |||
recurrency_tid | TID da primeira transação da recorrência. Identificador que diferencia a primeira recorrência das subsequentes. Só é utilizado quando for uma recorrência. | < 18 AN | NÃO | |||
recurrency_original_amount | Valor original da transação que originou a recorrência. Este valor deve ser informado em todas a recorrências subsequentes. Só é utilizado quando for uma recorrência. Campo utilizado somente no roteamento BIN, obrigatório quando for recorrência | < 18 AN | NÃO | |||
product_code | Código de produto. É obrigatório em roteamento via Marisa. | < 6 N | COND. | |||
terminal | Terminal SiTef que se deseja usar. Se não for enviado, o Carat gerará um terminal aleatório. | = 14 N | NÃO | |||
company_code | Código de empresa SiTef que se deseja usar. Se não for enviado, o Carat enviará o código de empresa cadastrado na loja. | = 8 N | NÃO | |||
authorization_number | Código de autorização. Obrigatório para autorizadora Bradescard Voucher. | < 6 AN | COND. | |||
| acquirer.vouchers_filter[] | Filtro de Vouchers - Escolha dos vouchers que não serão aceitos. Opções de "Vouchers": 01 - Alimentação, 02 - Refeição 03 - Cultura, 04 - Combustível, 05 - Benefício. Exemplo: Não se quer aceitar Vouchers: Cultura, Combustível, Benefício. Deve enviar: "vouchers_filter": [ "03", "04", "05" ] | |||||
| acquirer.prefixes | Elemento para envio de prefixos do SiTef, como CICLOS, CPLANO e VLRADD. Caso o prefixo enviado não seja suportado pelo cartão enviado, o Carat invalidará a transação, impedindo que se dê uma falsa impressão do uso de uma determinada funcionalidade. Exemplo: { "key" : "value" } -> { "CICLOS" : "01" } | |||||
key | Nome do prefixo. | < 1024 AN | NÃO | |||
value | Valor do prefixo. | < 1024 AN | NÃO | |||
| 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 | |||
| acquirer.card_on_file | É destinado ao envio de informações específicas como, por exemplo, autorização de armazenamento de cartão, confirmando que o dono do cartão autorizou o armazenamento do cartão. Saiba mais | |||||
usage | Identifica a utilização. Por exemplo, para autorização de armazenamento: authorized | < 11 AN | NÃO | |||
reason | Identifica o motivo. Por exemplo, para autorização de armazenamento: card | < 11 AN | NÃO | |||
| ATENÇÃO: Os parâmetros | ||||||
| additional_data | Elemento para envio de dados adicionais. | |||||
postpone_confirmation | Esse campo deve ser enviado com valor true caso se deseje um pagamento com confirmação tardia. | < 5 T/F | NÃO | |||
visitor_id | Identificador do visitante obtido no JavaScript | < 40 AN | NÃO | |||
description | Descrição do produto | < 100 AN | NÃO | |||
discount_amount | Valor de desconto do produto em centavos | < 10 N | NÃO | |||
discount_info | Informações de desconto. | < 500 AN | NÃO | |||
sku | Código de produto do item | < 100 AN | NÃO | |||
creation_date | Indica a data de publicação do produto no site da loja (Formato: DD/MM/AAAA) | = 10 AN | NÃO | |||
| additional_data.payer | Elemento para envio de dados referentes ao comprador. | |||||
name | Nome do cliente | < 100 AN | SIM | |||
surname | Sobrenome do cliente | < 100 AN | SIM | |||
email | Endereço de e-mail do cliente | < 100 AN | SIM | |||
born_date | Data de nascimento do cliente (formato : AAAA-MM-DDTHH:MM:SS) | = 19 AN | NÃO | |||
identification_number | Número de documento fiscal do cliente | < 100 AN | NÃO | |||
creation_date | Data de criação da conta ou cadastro do cliente no site (formato: DD/MM/AAAA ) | = 10 AN | NÃO | |||
is_new_client | Boolean indicando se o cliente está usando uma conta recém-criada nesta compra | < 5 T/F | NÃO | |||
is_vip_client | Boolean indicando se este é um cliente VIP ou comprador frequente. | < 5 T/F | NÃO | |||
additional_data.passengers[] | Informações relativas aos passageiros | |||||
name | Primeiro nome do passageiro | < 100 AN | SIM | |||
last_name | Sobrenome do passageiro | < 100 AN | SIM | |||
legal_document | Número do documento | < 100 AN | SIM | |||
legal_document_type | Tipo do documento (5 = passport, qualquer outro número = id) | < 8 AN | SIM | |||
birth_date | Data de nascimento do passageiro (formato: AAAA-MM-DDTHH:MM:SS) | < 17 AN | NÃO | |||
nationality | País de nascimento do passageiro, seguindo a ISO 3166-1 alfa-3 | = 3 AN | NÃO | |||
is_frequent_traveler | Flag de viajante frequente | < 5 T/F | NÃO | |||
is_with_special_needs | Flag de viajante com necessidades especiais | < 5 T/F | NÃO | |||
frequent_flyer_card | Tipo de programa de fidelidade | < 255 AN | NÃO | |||
customer_class | Categoria do programa de fidelidade | < 255 AN | NÃO | |||
additional_data.hotel_reservations[] | Informações relativas à reserva de hotel | |||||
hotel | Nome do hotel | < 100 AN | SIM | |||
category | Categoria do hotel | < 100 AN | NÃO | |||
additional_data.hotel_reservations[].address | Informações relativas ao endereço do hotel | |||||
street_name | Rua do hotel | < 255 AN | NÃO | |||
street_number | Número do hotel | < 255 AN | NÃO | |||
complement | Complemento do endereço hotel. | < 100 AN | NÃO | |||
city | Cidade do hotel | < 100 AN | NÃO | |||
state | Sigla do estado do hotel | < 100 AN | NÃO | |||
zip_code | CEP do hotel | < 100 AN | NÃO | |||
country | País do hotel, seguindo a ISO 3166-1 alfa-3. | = 3 AN | NÃO | |||
additional_data.hotel_reservations[].rooms[] | Informações relativas a quartos do hotel | |||||
number | Número do quarto | < 100 AN | NÃO | |||
code | Código do quarto | < 100 AN | NÃO | |||
type | Tipo do quarto | < 100 AN | NÃO | |||
check_in_date | Date e hora do entrada (formato: AAAA-MM-DDTHH:MM:SS) | < 17 AN | SIM | |||
check_out_date | Date e hora de saída (formato: AAAA-MM-DDTHH:MM:SS) | < 17 AN | NÃO | |||
number_of_guests | Número de pessoas | < 9999 N | NÃO | |||
board_basis | Regime de alimentação | < 100 AN | NÃO | |||
additional_data.hotel_reservations[].rooms[].guests[] | Informações relativas a hóspedes do quarto | |||||
name | Nome do hóspede | < 100 AN | SIM | |||
document | Número do documento do hóspede | < 8 AN | NÃO | |||
document_type | Documento usado pelo cliente:
| < 8 AN | NÃO | |||
birth_date | Data de nascimento do cliente (formato: AAAA-MM-DDTHH:MM:SS) | < 17 AN | NÃO | |||
nationality | Nacionalidade do hóspede, seguindo a ISO 3166-1 alfa-3. | = 3 AN | NÃO | |||
additional_data.events[] | Informações relativas a dados de um evento | |||||
name | Nome do evento | < 255 AN | SIM | |||
date | Date e hora do evento em UTC (formato AAAA-MM-DDTHH:MM:SS) | < 17 AN | SIM | |||
type | Tipo do evento:
| < 9 AN | SIM | |||
subtype | Detalhe do tipo do evento | < 255 AN | NÃO | |||
additional_data.events[].venue | Informações relativas a dados de local de um evento | |||||
name | Nome do local | < 255 AN | NÃO | |||
street_name | Nome da rua | < 255 AN | NÃO | |||
street_number | Número da rua | < 255 AN | NÃO | |||
city | Cidade do local | < 255 AN | NÃO | |||
state | Estado do local | < 255 AN | NÃO | |||
country | Pais do local, seguindo a ISO 3166-1 alfa-3. | = 3 AN | NÃO | |||
capacity | Capacidade do local | < 255 AN | NÃO | |||
additional_data.events[].tickets[] | Informações relativas aos ingressos de um evento | |||||
id | Identificador único do ticket. | < 255 AN | NÃO | |||
category | Categoria do ticket:
| < 10 AN | SIM | |||
section | Seção do ticket | < 255 AN | NÃO | |||
premium | Indicador de ticket premium | < 5 T/F | NÃO | |||
additional_data.events[].tickets[].ateendee | Informações relativas ao participante do evento | |||||
name | Nome do participante | < 255 AN | NÃO | |||
document | Documento do participante | < 100 AN | SIM | |||
document_type | Tipo de documento do participante:
| < 100 AN | NÃO | |||
birth_date | Data de nascimento do participante (formato: AAAA-MM-DDTHH:MM:SS) | < 17 AN | NÃO | |||
| additional_data.merchant | Elemento para envio de dados referentes ao lojista. | |||||
email | Endereço de e-mail do lojista. | < 1024 AN | NÃO | |||
| additional_data.extra_param.prefixes | Elemento para envio de prefixos do SiTef, como CICLOS, CPLANO e VLRADD. Caso o prefixo enviado não seja suportado pelo cartão enviado, o Carat invalidará a transação, impedindo que se dê uma falsa impressão do uso de uma determinada funcionalidade. Exemplo: { "key" : "value" } -> { "CICLOS" : "01" } | |||||
key | Nome do prefixo. | < 1024 AN | NÃO | |||
value | Valor do prefixo. | < 1024 AN | NÃO | |||
| additional_data.shipment.receiver_address | ||||||
street_name | Endereço de entrega. | < 255 AN | NÃO | |||
street_number | Número do endereço de entrega. | < 15 AN | NÃO | |||
complement | Complemento do endereço de entrega. | < 50 AN | NÃO | |||
zip_code | CEP do endereço de entrega. Ex.: 21241-140. | < 9 AN | NÃO | |||
city | Cidade do endereço de entrega. | < 50 AN | NÃO | |||
state | Estado do endereço de entrega. | = 2 AN | NÃO | |||
country | País do endereço de entrega seguindo a AN 3166-1. Ex.: BRA | = 3 AN | NÃO | |||
| additional_data.browser | ||||||
cookies_accepted | Identifica se o browser do cliente aceita cookies. Enviar true caso positivo. | < 5 T/F | NÃO | |||
email | E-mail registrado no browser do comprador. | < 100 AN | NÃO | |||
host_name | Nome do host onde o comprador estava antes de entrar no site da loja. | < 60 AN | NÃO | |||
agent | Nome do browser utilizado pelo comprador. Ex.: Chrome. | < 40 AN | NÃO | |||
| additional_data.items[] | ||||||
gift_category | Campo que avaliará os endereços de cobrança e entrega para diferentes cidades, estados ou países. Pode assumir os seguintes valores: OFF – Ignora a análise de risco para endereços divergentes.YES – Em caso de divergência entre endereços de cobrança e entrega, marca com risco pequeno.NO – Em caso de divergência entre endereços de cobrança e entrega, marca com risco alto. | < 3 AN | NÃO | |||
risk | Nível do risco do produto. Pode assumir os seguintes valores: LOW – O produto tem um histórico de poucos chargebacks.NORMAL – O produto tem um histórico de chargebacks considerado normal.HIGH – O produto tem um histórico de chargebacks acima da média. | < 6 AN | NÃO | |||
title | Nome do produto. | < 255 AN | NÃO | |||
quantity | Quantidade do produto a ser adquirido. | < 15 N | NÃO | |||
id | Código comerciante identificador do produto. | < 255 AN | NÃO | |||
unit_price | Preço unitário do produto em centavos. | < 15 N | NÃO | |||
| additional_data.items[].passenger | ||||||
email | E-mail do passageiro. | < 255 AN | NÃO | |||
legal_document | Id do passageiro a quem o bilhete foi emitido. | < 32 AN | NÃO | |||
name | Nome do passageiro. | < 120 AN | NÃO | |||
customer_class | Classificação da empresa aérea. Pode-se usar valores como Gold ou Platina. | < 32 AN | NÃO | |||
| additional_data.items[].passenger.phone | ||||||
ddi | Código do país do telefone do passageiro. Para pedidos fora dos E.U.A., é recomendável o envio deste campo. | < 3 N | NÃO | |||
ddd | Código da área do telefone do passageiro. | < 3 N | NÃO | |||
number | Número de telefone do passageiro. | < 9 N | NÃO | |||
| additional_data.shipment | ||||||
name | Nome do destinatário da entrega. | < 255 AN | NÃO | |||
| additional_data.shipment.phones[] | ||||||
ddi | Código do país do telefone do destinatário da entrega. Para pedidos fora dos E.U.A., é recomendável o envio deste campo. | < 3 N | NÃO | |||
ddd | Código da área do telefone do destinatário da entrega. | < 3 N | NÃO | |||
number | Número de telefone do destinatário da entrega. | < 9 N | NÃO | |||
additional_data.connections[] | Informações relativas às conexões de viagem | |||||
journey_type |
| < 7 AN | SIM | |||
origin_city | Cidade de origem. | < 100 AN | SIM, se transport_type=bus | |||
destination_city | Cidade de destino. | < 100 AN | SIM, se transport_type=bus | |||
from | Código aeroportuário IATA para o aeroporto de origem | = 3 AN | SIM, se transport_type=flight | |||
to | Código aeroportuário IATA para o aeroporto de destino. | = 3 AN | SIM, se transport_type=flight | |||
departure_date | Date e hora do embarque (formato: AAAA-MM-DDTHH:MM:SS) | < 17 AN | SIM | |||
class | Nome da classe (Ex: economy, business e first) | < 8 AN | NÃO | |||
class_code | Código da classe | < 20 AN | NÃO | |||
company | Nome da cia aérea | < 20 AN | NÃO | |||
additional_data.billing_data.address | Informações relativas à fatura | |||||
street_name | Rua da fatura do cliente com o banco | < 255 AN | NÃO | |||
street_number | Número da rua da fatura do cliente com o banco | < 255 AN | NÃO | |||
complement | Complemento do endereço de fatura. | < 100 AN | NÃO | |||
city | Cidade do titular | < 100 AN | NÃO | |||
state | Estado do titular | < 100 AN | NÃO | |||
zip_code | CEP do titular | < 100 AN | NÃO | |||
country | Código do país do titular, seguindo a ISO 3166-1 alfa-3 | = 3 AN | NÃO | |||
additional_data.travel | Informações relativas à passagem aérea | |||||
transport_type | Tipo de viagem (flight ou bus) | < 6 AN | SIM | |||
expiration_date | Data de expiração (formato: DD/MM/AAAA ) | = 10 AN | NÃO | |||
Na tabela abaixo está a descrição dos parâmetros adicionais que devem ser enviados num pagamento com análise de fraude:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
| additional_data | |||
anti_fraud | Habilita o serviço de análise de fraude. Valores permitidos:enabled_before_auth – a análise de fraude será realizada ANTES da autorização do pagamento. Caso a análise seja rejeitada, o pagamento não será iniciado.enabled_after_auth – a análise de fraude será realizada APÓS a autorização do pagamento. Caso a análise seja rejeitada, o pagamento que já foi autorizado será cancelado. | < 19 AN | SIM para análise de fraude |
journey_type | Tipo de viagem. Valores permitidos:ROUND_TRIP – ida e volta.OUTWARD – ida.RETURN – volta. | < 10 AN | NÃO |
Parâmetros de resposta#
Em caso de sucesso, o código de resposta HTTP será 201. 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 efetivação de pagamento:
| Parâmetro | Descrição | Formato |
|---|---|---|
code | Código de resposta do Carat. Qualquer código diferente de 0 significa falha. Saiba mais. | < 4 N |
message | Mensagem de resposta do Carat. | < 500 AN |
| payment | ||
authorizer_code | Código de resposta do autorizador. | < 10 AN |
authorizer_message | Mensagem de resposta do autorizador. | < 500 AN |
status | Status da transação de pagamento no Carat. Saiba mais. | = 3 AN |
nit | Identificador da transação de pagamento no Carat. | = 64 AN |
order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 N |
amount | Valor da compra especificado pela loja (em centavos) na criação da transação. | < 12 N |
sitef_usn | Número sequencial único da transação de pagamento no SiTef. | = 6 N |
esitef_usn | Número sequencial único da transação de pagamento no Carat. | = 15 N |
customer_receipt | Cupom (via cliente). | < 4000 AN |
merchant_receipt | Cupom (via estabelecimento). | < 4000 AN |
authorizer_id | Código da autorizadora utilizada na transação. | < 4 N |
acquirer_id | Código da adquirente utilizado na transação. | < 4 N |
acquirer_name | Nome da adquirente utilizado na transação. | < 100 AN |
authorizer_date | Data de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03 | = 16 D |
authorization_number | Número de autorização. | < 6 AN |
host_usn | NSU da autorizadora. | < 15 AN |
tid | ID da transação na adquirente. Este campo só é retornado em transações com adquirentes externas ao SiTef. | < 40 AN |
eci | Eletronic Commerce Indicator. | < 3 AN |
payment_date | Data de efetivação do pagamento no Carat no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03 | = 16 D |
issuer | Código da bandeira retornado pelo autorizador. | < 5 AN |
authorizer_merchant_id | Código de afiliação do lojista na autorizadora. | < 100 AN |
xid | Campo XID retornado em autenticações 3DS ou certos adquirentes. | < 40 AN |
cavv | Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão. | < 40 N |
recurrency_tid | Id de transação (TID) da bandeira, referente à primeira transação da recorrência. Só é retornado quando for uma recorrência. | < 16 AN |
terminal_id | Código do terminal utilizada na transação | < 8 AN |
payment_type | Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service | = 1 AN |
| payment.analysis | ||
status | Status da transação de pagamento no Carat. Saiba mais. | = 3 AN |
code | Código de resposta do Carat. Qualquer código diferente de 0 significa falha. Saiba mais. | < 4 N |
message | Mensagem de resposta do Carat. | < 500 AN |
Parâmetros de Card-On-File#
Card on File refere-se a transações que envolvem o armazenamento de informações de cartão de crédito para uso futuro. Essas transações indicam que um cartão foi armazenado de forma segura em um sistema, permitindo seu uso posterior sem a necessidade de inserir novamente os detalhes do cartão. A opção de armazenar o cartão oferece conveniência aos usuários, permitindo que eles efetuem pagamentos de forma rápida e fácil em transações futuras. Além disso, o armazenamento das informações do cartão também pode ser usado pelos emissores de cartões para análise de risco e prevenção de fraudes, melhorando a segurança das transações e aumentando a taxa de conversão.
Para operações de Card on File são necessários o envio dos seguintes parâmetros:
| acquirer.card_on_file | ||
|---|---|---|
usage | Identifica a utilização | - authorized - first - subsequent |
reason | Identifica o motivo | - card - recurring - cardholder - unscheduled |
Nota:
usageereasonsão informações complementares e por isso é possível consultar todas as combinações validas com detalhe de uso a seguir.
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 que o pagamento será realizado com um cartão armazenado previamente |
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 quando realiza um pagamento ou validação zero dollar. | 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 |
Recorrência#
Pagamentos recorrentes são transações de cartão de crédito que ocorrem de forma periódica, repetindo-se após um determinado período de tempo. Um exemplo comum é encontrado em assinaturas, em que o comprador deseja ser cobrado automaticamente, sem a necessidade de fornecer novamente os dados do cartão de crédito a cada transação. Nesse tipo de pagamento, o cliente autoriza previamente a realização de cobranças periódicas, estabelecendo as condições e o intervalo de tempo entre as transações. Isso proporciona comodidade tanto para o comprador, que não precisa se preocupar em fazer pagamentos repetidos manualmente, quanto para o vendedor, que mantém uma fonte constante de receita.
Para operações de recorrência são necessários o envio dos seguintes parâmetros:
Acquirer | ||
recurrency | Indica que esse pagamento faz parte de uma recorrência | - true - false |
recurrency_tid | TID da primeira transação que originou a recorrência. | |
recurrency_original_amount | Valor original da transação que originou a recorrência. Este valor deve ser informado em todas a recorrências subsequentes. Obrigatório somente para a ELO | |
Acquirer.card_on_file | ||
usage | Identifica a utilização. | - first - subsequent |
reason | Identifica o motivo. | - recurring |
Exemplo#
Chamada original
Para usar este exemplo e os demais, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Chamada:
Resposta:
O parametro recurency_tid da chamada anterior é usado nas chamadas seguintes. Observe, também, os parâmetros da estrutura card_on_file que mudam na primeira chamada da recorrência e nas chamadas subsequentes (Segunda em diante).
Primeiro pagamento de recorrência
Chamada:
Resposta:
Demais chamadas da recorrência
Chamada:
Resposta:
Campos de MCC Dinâmico#
Pode ser utilizado tanto para transação de pagamento ou de pré-autorização REST#
Parâmetros de requisição#
Adicionalmente aos campos mencionados, os campos abaixo são usados no cenário específico de MCC dinâmico da integração com a bin:
| Parâmetro | Descrição | Formato | Obrigatório | |||
|---|---|---|---|---|---|---|
soft_descriptor | Frase personalizada que será impressa na fatura do portador. Para informação referente ao MCC dinâmico, equivale ao nome do sublojista. | < 25 AN | SIM | |||
| additional_data | Elemento para envio de dados adicionais. | |||||
mcc | MCC do sublojista. | = 4 N | SIM | |||
subacquirer_merchant_id | Código do sublojista. Campo legado!!! Dar preferência ao additional_data.subacquirer_merchant.id | < 15 N | NÃO | |||
| additional_data.subacquirer_merchant | Elemento para envio de dados referentes ao lojista de uma subadquirente. | |||||
id | Código do sublojista. | < 15 N | SIM | |||
phone_number | Número de Telefone do sublojista. | < 14 AN | NÃO | |||
address | Endereço do sublojista. | < 48 AN | NÃO | |||
city | Cidade do sublojista. | < 13 AN | NÃO | |||
state | Estado do sublojista, em formato de sigla de dois dígitos (ex.: SP). | = 2 A | SIM | |||
country | País do sublojista. Seguir o padrão ISO 3166-1 alpha-2 (ex.: BR). | = 2 A | SIM | |||
zip_code | Código postal do sublojista. | < 9 AN | SIM | |||
identification_number | CNPJ do sublojista. | < 18 N | SIM | |||
payment_facilitator_id | Código do facilitador. | < 11 N | SIM | |||
Exemplo#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br
Resposta: