Serviço de efetivação de pagamento
Após consumir o serviço de criação de transação e obter um NIT, é possível prosseguir para a próxima etapa do fluxo: a chamada ao serviço de efetivação de pagamento. Esta operação deve ser consumida também em fluxos de pagamento com agendamento. Nesse caso, o Carat garante que o agendamento só será ativado caso o pagamento seja confirmado.
Detalhes da chamada#
- Recurso:
/v1/payments/{nit} - 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#
Abaixo estão alguns exemplos de chamada do serviço de efetivação de pagamento utilizando a ferramenta cURL.
Pagamento com captura automática#
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 confirmação tardia#
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 agendamento#
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 cartão armazenado#
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 prefixos#
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.
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:
Códigos de resposta
Veja a referencia no Códigos da API - códigos de resposta
Parâmetros de requisição#
Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de efetivação de pagamento:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
authorizer_id | Código da autorizadora no Carat. Saiba mais. Caso este campo não tenha sido enviado na etapa de criação da transação, ele passa a ser obrigatório ao consumir o serviço de efetivação do pagamento. | < 3 N | COND. |
customer_postal_code | Código postal (CEP no Brasil) do usuário. Este deve ser enviado para transações roteadas iCards via SiTef, caso a coleta deste for indicada no serviço de consulta de cartão pelo campo is_customer_postal_code_required. | < 8 N | COND. |
mcc | O MCC (Merchant Category Code) é um código que classifica um negócio pelo tipo de bens ou produtos fornecidos. | < 4 N | NÃO |
subacquirer_merchant_id | Identificação da loja na subadquirente. | < 22 N | 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 |
cryptogram | Criptograma gerado pela bandeira. | = 28 A | Sim para pagamentos com token bandeira |
expiry_date | Data de vencimento do cartão no formato MMAA. Sua obrigatoriedade depende do adquirente escolhido. 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 | COND. |
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 |
wallet_transaction_id | ID de uma transação de carteiras digitais. Por enquanto, essa funcionalidade está disponível apenas para as autorizadoras Visa Checkout, VEE (via CardSE-SiTef) e Google Pay. Não é permitido enviar um número de cartão aberto (campo number), um cartão armazenado (campo token) e um wallet_transaction_id na mesma requisição. | < 25 AN | NÃO |
initial_wallet_transaction_id | Informa se o Wallet ID (wallet_transaction_id) está sendo utilizado pela primeira vez. Se for a primeira vez, enviar true, caso contrário enviar false. | < 5 T/F | 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. | ||
version | Versão do 3DS utilizado no processo de autenticação (atualmente só está sendo aceito versão 2). | < 1 AN | NÃO |
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 |
reference_id | Identificador da transação de autenticação do dono do cartão, feita em serviço externo ao Carat (No nosso Web Checkout o reference_id é referenciado pelo ds.transId no retorno da autenticação do 3DS ) | < 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 |
| 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 |
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. Campo utilizado somente no roteamento e.Rede REST para as bandeiras Visa e Mastercard e roteamento GetnetWS. | < 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. | < 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
terminalecompany_codedeverão ser usados somente para roteamentos via SiTef e devem ser enviados simultaneamente.
É necessário também solicitar à equipe de atendimento do Carat a permissão Permite envio de Empresa e Terminal Sitef via REST.
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 do adquirente utilizado na transação. | < 4 N |
acquirer_name | Nome do 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. Ressalva para efetivação de pagamentos PIX Saiba mais. | < 15 AN |
tid | ID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef. | < 40 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 |
balance | Saldo disponível após pagamentos com cartões tipo Gift. | < 12 N |
recurrency_tid | Id de transação (TID) da bandeira, referente à primeira transação da recorrência. Só é retornado quando for uma recorrência. | |
retryable_code | Indicador de reversibilidade de uma transação cuja autorização foi negada pela autorizadora. Esse campo será retornado na resposta da requisição de pagamento com cartão e deve ser levado em consideração no mecanismo de retentativa de transação da loja virtual. Códigos válidos:01 – Transação negada reversível, retente mais tarde.02 – Transação negada irreversível, não retente. | = 2 N |
| payment.analysis | ||
code | Código de resposta da operação de análise de fraude. | < 4 N |
message | Mensagem de resposta da operação de análise de fraude. | < 200 AN |
status | Status da transação de análise de fraude do Carat. Este campo pode assumir os seguintes valores:NOV – Nova.EXP – Expirada.ACC – AceitaREJ – RejeitadaREV – Em revisãoINV – Inválida | = 3 AN |
| schedule | ||
status | Status do agendamento no Carat. Saiba mais. | = 3 AN |
sid | Identificador da transação de agendamento no Carat. | = 64 AN |
schedule_usn | Número sequencial único do agendamento no Carat. | = 15 N |
authorizer_id | Código da autorizadora a ser utilizada nos pagamentos agendados. Nas operações com cartão tokenizado, se a autorizadora não for informada, será usado o código da autorizadora usado no armazenamento do cartão. | = 4 N |
amount | Valor dos pagamentos agendados especificado pela loja (em centavos) na criação da transação. | < 12 N |
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 |
initial_date | Data de execução do primeiro pagamento agendado no formato DD/MM/AAAA. | = 10 D |
next_date | Data de execução do próximo pagamento agendado no formato DD/MM/AAAA. | = 10 D |
number_of_times | Número total de pagamentos agendados. | < 3 N |
installments | Número de parcelas a ser utilizado nos pagamentos agendados. | < 2 N |
installment_type | Tipo de financiamento a ser utilizado nos pagamentos agendados. | < 2 N |
soft_descriptor | Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. | < 30 AN |
show_times_invoice | Para agendamentos por tempo finito, caso esse campo tenha valor true acrescenta ao final do campo soft_descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12). | < 5 T/F |
terminal_id | Código do terminal utilizada na transação | < 8 AN |
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 |
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 |
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: