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âmetroDescriçãoFormatoObrigatório
merchant_idCódigo da loja no Carat. Os códigos de produção e certificação serão diferentes.< 15 ANSIM
merchant_keyChave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes.< 80 ANSIM
Content-TypeDeve ser enviado com o valor application/json.= 15 ANSIM

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

curl
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"number":"5555555555555555",
"expiry_date":"1222",
"security_code":"123"
}
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "Transacao OK",
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "13034649671",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "13/07/2017T15:52",
"authorization_number": "132030",
"merchant_usn": "13034649671",
"esitef_usn": "170713097340300",
"sitef_usn": "132030",
"host_usn": "999132030",
"payment_date": "13/07/2017T15:52",
"amount": "1000",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005"
}
}

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

curl
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"number":"5555555555555555",
"expiry_date":"1222",
"security_code":"123"
}
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "Transacao OK",
"status": "PPC",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "13035748930",
"customer_receipt": "==== CUPOM COMPRADOR ====",
"merchant_receipt": "==== CUPOM ESTABELECIMENTO ====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "13/07/2017T15:58",
"authorization_number": "132031",
"merchant_usn": "13035748930",
"esitef_usn": "170713097340340",
"sitef_usn": "132031",
"host_usn": "999132031 ",
"payment_date": "13/07/2017T15:58",
"amount": "1000",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005"
}
}

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

curl
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"number":"5555555555555555",
"expiry_date":"1222",
"security_code":"123"
}
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "Transacao OK",
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "13040222890",
"customer_receipt": "==== CUPOM COMPRADOR ====",
"merchant_receipt": "==== CUPOM ESTABELECIMENTO ====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "13/07/2017T16:03",
"authorization_number": "132032",
"merchant_usn": "13040222890",
"esitef_usn": "170713097340360",
"sitef_usn": "132032",
"host_usn": "999132032 ",
"payment_date": "13/07/2017T16:03",
"amount": "1000",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005"
},
"schedule": {
"status": "ATV",
"sid": "qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
"schedule_usn": "170713000000020",
"amount": "900",
"initial_date": "03/08/2017",
"next_date": "03/08/2017",
"number_of_times": "3",
"soft_descriptor": "Assinatura",
"show_times_invoice": "false"
}
}

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

curl
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"token":"g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ=="
}
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "Transacao OK",
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "13034649671",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "13/07/2017T15:52",
"authorization_number": "132030",
"merchant_usn": "13034649671",
"esitef_usn": "170713097340300",
"sitef_usn": "132030",
"host_usn": "999132030",
"payment_date": "13/07/2017T15:52",
"amount": "1000",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005"
}
}

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

curl
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card":{
"expiry_date":"1222",
"security_code":"123",
"number":"5555555555555555"
},
"acquirer":{
"prefixes":{
"TRAT":"1"
}
}
}
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "Transacao OK",
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "21105507366",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "21/11/2017T10:55",
"authorization_number": "211981",
"merchant_usn": "21105507366",
"esitef_usn": "171121108905100",
"sitef_usn": "211981",
"host_usn": "999211981 ",
"amount": "1000",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"payment_date": "21/11/2017T10:55"
}
}

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

curl
--request POST 'https://{{url}}/e-sitef/api/v1/payments/150533212ef1d2082ccff166fd2fb8d98ae645a541ad8ef54225c320bb0587a6' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
"amount": 3000,
"discount": 0,
"installments": 1,
"installment_type": 4,
"authorizer_id": "2",
"subtotal": 3000,
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555",
"cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
"wallet_type": "network_token"
}
}'
--verbose

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "CON",
"nit": "7aef0962f2d2ec05c4cd35fd0d91a11fb4a5ce77e9dff69bbb5fc0992d0bc017",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "27/12/2022T17:06",
"authorization_number": "276147",
"esitef_usn": "221227000216620",
"sitef_usn": "276147",
"host_usn": "999276147 ",
"amount": "3000",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"terminal_id": "ES000023",
"payment_date": "27/12/2022T17:06"
}
}

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âmetroDescriçãoFormatoObrigatório
authorizer_idCó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 NCOND.
customer_postal_codeCó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 NCOND.
mccO MCC (Merchant Category Code) é um código que classifica um negócio pelo tipo de bens ou produtos fornecidos.< 4 NNÃO
subacquirer_merchant_idIdentificação da loja na subadquirente.< 22 NNÃO
cardDados do cartão.
numberNúmero do cartão do comprador (PAN).

Token gerado pela bandeira (DPAN) para pagamento com Token Bandeira. Saiba mais
< 19 NSIM
cryptogramCriptograma gerado pela bandeira.= 28 ASim para pagamentos com token bandeira
expiry_dateData de vencimento do cartão no formato MMAA. Sua obrigatoriedade depende do adquirente escolhido. Na maioria dos casos, esse campo é obrigatório.= 4 NCOND.
security_codeCó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 NCOND.
holderNome do portador do cartão. < 30 ANCOND.
tokenHASH 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 ANNÃO
wallet_transaction_idID 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 ANNÃO
initial_wallet_transaction_idInforma 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/FNÃO
wallet_typeCampo 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”.ANNÃO
external_authenticationEste elemento recebe campos de resultados de autenticação MPI.
versionVersão do 3DS utilizado no processo de autenticação (atualmente só está sendo aceito versão 2).< 1 ANNÃO
eciEletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão< 3 NNÃO
reference_idIdentificador 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 NNÃO
cavvCardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.< 40 NNÃO
acquirerDados específicos necessários dependendo da adquirente/roteamento.
financing_planCódigo de plano de financiamento. Necessário apenas para pagamentos parcelados com juros roteados pela Via Certa Financiadora via SiTef.< 4 NNÃO
special_codeCódigo de uso geral da Conductor/Renner.< 6 NNÃO
recurrencyFlag que define se o pagamento é ou não recorrente. Aceito para todos os roteamentos via SiTef< 5 T/FNÃO
recurrency_tidTID 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 ANNÃO
recurrency_original_amountValor 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 ANNÃO
product_codeCódigo de produto.
É obrigatório em roteamento via Marisa.
< 6 NCOND.
terminalTerminal SiTef que se deseja usar. Se não for enviado, o Carat gerará um terminal aleatório.= 14 NNÃO
company_codeCó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 NNÃO
authorization_numberCódigo de autorização. Obrigatório para autorizadora Bradescard Voucher.< 6 ANCOND.
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.prefixesElemento 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" }
keyNome do prefixo.< 1024 ANNÃO
valueValor do prefixo.< 1024 ANNÃ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_codecódigo de estabelecimento BIN/Sipag< 51 ANNÃO
submerchant_amountvalor de transação referente ao estabelecimento< 12 NNÃ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
usageIdentifica a utilização.
Por exemplo, para autorização de armazenamento: authorized
< 11 ANNÃO
reasonIdentifica o motivo.
Por exemplo, para autorização de armazenamento: card
< 11 ANNÃO

ATENÇÃO: Os parâmetros terminal e company_code deverã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âmetroDescriçãoFormato
codeCódigo de resposta do Carat. Qualquer código diferente de 0 significa falha. Saiba mais.< 4 N
messageMensagem de resposta do Carat.< 500 AN
payment
authorizer_codeCódigo de resposta do autorizador.< 10 AN
authorizer_messageMensagem de resposta do autorizador.< 500 AN
statusStatus da transação de pagamento no Carat. Saiba mais.= 3 AN
nitIdentificador da transação de pagamento no Carat.= 64 AN
order_idCódigo de pedido enviado pela loja na criação da transação.< 40 AN
merchant_usnNúmero sequencial único enviado pela loja na criação da transação.< 12 N
amountValor da compra especificado pela loja (em centavos) na criação da transação.< 12 N
sitef_usnNúmero sequencial único da transação de pagamento no SiTef.= 6 N
esitef_usnNúmero sequencial único da transação de pagamento no Carat.= 15 N
customer_receiptCupom (via cliente).< 4000 AN
merchant_receiptCupom (via estabelecimento).< 4000 AN
authorizer_idCódigo da autorizadora utilizada na transação.< 4 N
acquirer_idCódigo do adquirente utilizado na transação.< 4 N
acquirer_nameNome do adquirente utilizado na transação.< 100 AN
authorizer_dateData de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03= 16 D
authorization_numberNúmero de autorização.< 6 AN
host_usnNSU da autorizadora.
Ressalva para efetivação de pagamentos PIX Saiba mais.
< 15 AN
tidID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef.< 40 AN
payment_dateData de efetivação do pagamento no Carat no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03= 16 D
issuerCódigo da bandeira retornado pelo autorizador.< 5 AN
authorizer_merchant_idCódigo de afiliação do lojista na autorizadora.< 100 AN
xidCampo XID retornado em autenticações 3DS ou certos adquirentes.< 40 AN
balanceSaldo disponível após pagamentos com cartões tipo Gift.< 12 N
recurrency_tidId de transação (TID) da bandeira, referente à primeira transação da recorrência. Só é retornado quando for uma recorrência.
retryable_codeIndicador 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
codeCódigo de resposta da operação de análise de fraude.< 4 N
messageMensagem de resposta da operação de análise de fraude.< 200 AN
statusStatus da transação de análise de fraude do Carat. Este campo pode assumir os seguintes valores:
NOV – Nova.
EXP – Expirada.
ACC – Aceita
REJ – Rejeitada
REV – Em revisão
INV – Inválida
= 3 AN
schedule
statusStatus do agendamento no Carat. Saiba mais.= 3 AN
sidIdentificador da transação de agendamento no Carat.= 64 AN
schedule_usnNúmero sequencial único do agendamento no Carat.= 15 N
authorizer_idCó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
amountValor dos pagamentos agendados especificado pela loja (em centavos) na criação da transação.< 12 N
order_idCódigo de pedido enviado pela loja na criação da transação.< 40 AN
merchant_usnNúmero sequencial único enviado pela loja na criação da transação.< 12 N
initial_dateData de execução do primeiro pagamento agendado no formato DD/MM/AAAA.= 10 D
next_dateData de execução do próximo pagamento agendado no formato DD/MM/AAAA.= 10 D
number_of_timesNúmero total de pagamentos agendados.< 3 N
installmentsNúmero de parcelas a ser utilizado nos pagamentos agendados.< 2 N
installment_typeTipo de financiamento a ser utilizado nos pagamentos agendados.< 2 N
soft_descriptorTexto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador.< 30 AN
show_times_invoicePara 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_idCódigo do terminal utilizada na transação< 8 AN
recurrency_tidId de transação (TID) da bandeira, referente à primeira transação da recorrência. Só é retornado quando for uma recorrência. < 16 AN
payment_typeTipo 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
usageIdentifica a utilização- authorized
- first
- subsequent
reasonIdentifica o motivo- card
- recurring
- cardholder
- unscheduled

Nota: usage e reason sã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:

usageSignificado
firstIndica primeira ocorrência
subsequentIndica que o pagamento será realizado com um cartão armazenado previamente
authorizedPara uso junto com o parametro reason=card, indicando que o usuário autorizou o armazenamento do cartão
reasonSignificado
cardholderCompras subsequentes disparadas pelo titular do cartão
unscheduledCompra recorrente sem agendamento
recurringCompra recorrente agendada
installmentParcelamento através de recorrencia
cardPara 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)

SiglaSignificado
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#

usagereasonSignificadoMIT/CIT?
authorizedcardIndica que o usuário autorizou o armazenamento do cartão quando realiza um pagamento ou validação zero dollar.CIT
firstunscheduledIndica um pagamento avulsoMIT
firstrecurringIndica a primeira a primeira ocorrência de uma recorrênciaMIT
subsequentrecurringIndica as ocorrências subsequentes de uma recorrênciaMIT
subsequentcardholderIndica um pagamento feito pelo usuário com o cartão já armazenadoCIT
subsequentunscheduledIndica uma ocorrência subsequente não agendada iniciada pelo lojistaMIT
subsequentinstallmentIndica parcelamento por recorrênciaMIT

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
recurrencyIndica que esse pagamento faz parte de uma recorrência- true
- false
recurrency_tidTID da primeira transação que originou a recorrência.
recurrency_original_amountValor 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
usageIdentifica a utilização.- first
- subsequent
reasonIdentifica 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:

curl --location 'https://{{url}}/e-sitef/api/v2/payments/'
--header 'Content-Type: application/json'
--header 'merchant_id: xxxxxxxxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxxxxxxxxx'
--data '{
"merchant_usn": "12050620649",
"order_id":"1686661308079",
"installments": "1",
"installment_type": "4",
"authorizer_id": "41",
"amount": "1100",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555",
"cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
"wallet_type": "network_token"
},
"acquirer": {
"card_on_file": {
"usage": "authorized",
"reason": "card"
}
}
}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "APROVADA",
"status": "CON",
"nit": "402b901d6e3a013467a466c954b8e1634e57ea297983ae9b064e75742cae6538",
"order_id": "1686661308079",
"customer_receipt": " ==== customer recepitp =====",
"merchant_receipt": " ==== merchant receipt =====",
"authorizer_id": "41",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "13/06/2023T10:01",
"authorization_number": "500335",
"merchant_usn": "12050620649",
"esitef_usn": "230613015919750",
"sitef_usn": "500335",
"host_usn": "006500335 ",
"amount": "1100",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000000",
"terminal_id": "ES000005",
"payment_date": "13/06/2023T10:01",
"recurrency_tid": "999988887777666"
}
}

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:

curl --location 'https://{{url}}/e-sitef/api/v2/payments/'
--header 'Content-Type: application/json'
--header 'merchant_id: xxxxxxxxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxxxxxxxxx'
--data '{
"merchant_usn": "12050620649",
"order_id":"1686665131999",
"installments": "1",
"installment_type": "4",
"authorizer_id": "41",
"amount": "1100",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555",
"cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
"wallet_type": "network_token"
},
"acquirer": {
"card_on_file": {
"usage": "first",
"reason": "recurring"
},
"recurrency": "true",
"recurrency_tid": "999988887777666",
"recurrency_original_amount": "1100"
}
}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "APROVADA",
"status": "CON",
"nit": "599b99407d094e9e7f9a13fa6de2b492e7f7f251dca1db17893a94d1fc8d1690",
"order_id": "1686665131999",
"customer_receipt": " ==== customer receipt ====",
"merchant_receipt": " ==== merchant receipt ====",
"authorizer_id": "41",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "13/06/2023T11:05",
"authorization_number": "500337",
"merchant_usn": "12050620649",
"esitef_usn": "230613015921370",
"sitef_usn": "500337",
"host_usn": "006500337 ",
"amount": "1100",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000000",
"terminal_id": "ES000005",
"payment_date": "13/06/2023T11:05"
}
}

Demais chamadas da recorrência

Chamada:

curl --location 'https://{{url}}/e-sitef/api/v2/payments/'
--header 'Content-Type: application/json'
--header 'merchant_id: xxxxxxxxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxxxxxxxxx'
--data '{
"merchant_usn": "12050620649",
"order_id":"1686665569405",
"installments": "1",
"installment_type": "4",
"authorizer_id": "41",
"amount": "1100",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555",
"cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
"wallet_type": "network_token"
},
"acquirer": {
"card_on_file": {
"usage": "subsequent",
"reason": "recurring"
},
"recurrency": "true",
"recurrency_tid": "999988887777666",
"recurrency_original_amount": "1100"
}
}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "APROVADA",
"status": "CON",
"nit": "396fce49041532b55d37898039225b6eaed936d1f331232e770475b3ce988809",
"order_id": "1686665569405",
"customer_receipt": " ==== customer receipt ==== ",
"merchant_receipt": " ==== merchant receipt ==== ",
"authorizer_id": "41",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "13/06/2023T11:12",
"authorization_number": "500338",
"merchant_usn": "12050620649",
"esitef_usn": "230613015921490",
"sitef_usn": "500338",
"host_usn": "006500338 ",
"amount": "1100",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000000",
"terminal_id": "ES000005",
"payment_date": "13/06/2023T11:12"
}
}