Serviço de efetivação de pagamento com múltiplos meios 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.
Isso pode ser feito informando apenas um meio de pagamento (veja o documento "Serviço de efetivação de pagamento") ou 2 (dois) meios de pagamento.
Neste capítulo, trataremos dos pagamentos que são feitos com 2 (dois) meios de pagamento, o qual chamamos de Pagamento com múltiplos meios de pagamento.
Para usar esta funcionalidade, entre em contato com o nosso suporte e solicite a ativação da mesma em sua loja.
Fluxo
O fluxo de um pagamento com múltiplos meios de pagamento possui diferenças importantes quando o comparamos com o pagamento tradicional.
A primeira diferença é que temos duas transações para uma mesma chamada e cada uma delas é usada para efetuar o pagamento de um dos meios de pagamento informados. A primeira transação é criada na chamada de criação de transação no e-SiTef e a segunda transação é criada indiretamente na chamada de pagamento com múltiplos meios de pagamento.
A segunda diferença é que, por causa disso, alguns dados da primeira transação são modificados durante a efetivação do pagamento. Inicialmente, a primeira transação possui o valor total da compra, as parcelas e o tipo de financiamento próprios. Quando a chamada de pagamento com múltiplos pagamentos é feita, seu valor é alterado para ser igual ao do primeiro meio de pagamento e o mesmo ocorre com as parcelas e o tipo de financiamento, caso estes sejam informados na requisição. Já a segunda transação terá o valor, as parcelas e o tipo de financiamento informados pelo segundo meio de pagamento. Mas, no caso da segunda transação não informar dados de parcelamento e tipo de financiamento, ela herdará essas configurações da primeira transação original. A soma dos valores da primeira e da segunda transações deve ser igual ao valor informado na criação da primeira transação no e-SiTef.
A terceira diferença é que a resposta de múltiplos pagamentos é composta pelas respostas de cada uma das transações. Sendo assim, haverá situações em que a resposta de uma transação afetará a resposta da outra.
A seguir, iremos abordar os cenários previstos no e-SiTef com mais detalhes.
Fluxo de pagamento com confirmação automática
O fluxo de pagamento com confirmação automática nos pagamentos com múltiplos meios de pagamentos possui uma peculiaridade que é dividir o pagamento em 3 (três) etapas: atualização/inicialização das transações; pagamentos; confirmações.
Em caso de falha em qualquer uma das transações, o e-SiTef não prossegue para a etapa seguinte e faz tratamentos que serão explicados a seguir nos casos de falhas.
Caso de sucesso
Caso de falha no pagamento da primeira transação
Quando o primeiro pagamento falha, a segunda transação será cancelada e não será disparada para a Autorizadora. Uma ocorrência é gerada para a equipe de suporte do e-SiTef e o lojista, caso deseje, pode entrar em contato.
Exemplo de resposta
{
"code": "1013",
"message": "Error processing multiple payment methods",
"payments": [
{
"authorizer_code": "014",
"authorizer_message": "14 Cartao Inval.",
"status": "NEG",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "1609964926966",
"authorizer_id": "1",
"acquirer_id": "5",
"acquirer_name": "Redecard",
"authorizer_date": "06/01/2021T17:28",
"authorization_number": "080384",
"merchant_usn": "16114726760",
"esitef_usn": "210106064204400",
"sitef_usn": "606060",
"host_usn": "707070",
"amount": "1254785",
"payment_type": "C",
"issuer": "1",
"authorizer_merchant_id": "00000005",
"terminal_id": "ES000036"
},
{
"status": "CAN"
}
]
}
Caso de falha no pagamento da segunda transação
Quando o segundo pagamento falha, a primeira transação será desfeita. Uma ocorrência é gerada para a equipe de suporte do e-SiTef e o lojista, caso deseje, pode entrar em contato.
Exemplo de resposta
{
"code": "1013",
"message": "Error processing multiple payment methods",
"payments": [
{
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "PPN",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "25053142469",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id": "1",
"acquirer_id": "5",
"acquirer_name": "Redecard",
"authorizer_date": "25/03/2020T17:31",
"authorization_number": "252490",
"merchant_usn": "25053142469",
"esitef_usn": "200325048537130",
"sitef_usn": "252490",
"host_usn": "999252490 ",
"amount": "100",
"payment_type": "C",
"issuer": "1",
"authorizer_merchant_id": "000000000000005",
"payment_date": "25/03/2020T17:31"
},
{
"authorizer_code": "255",
"authorizer_message": "(2)Cartao invalido",
"status": "NEG",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "25053142469",
"authorizer_id": "2",
"acquirer_name": "REDE",
"merchant_usn": "25053142469",
"esitef_usn": "200325048537140"
}
]
}
Caso de falha na confirmação da primeira transação
Quando a primeira confirmação falha, a segunda transação será desfeita. Uma ocorrência é gerada para a equipe de suporte do e-SiTef e o lojista, caso deseje, pode entrar em contato.
Exemplo de resposta
{
"code": "1013",
"message": "Error processing multiple payment methods",
"payments": [
{
"authorizer_code": "200",
"authorizer_message": "Success. [Cód.: 00]",
"status": "PEN",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "1609965604696",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "202",
"acquirer_name": "e.Rede REST",
"authorizer_date": "06/01/2021T17:40",
"authorization_number": "177013",
"merchant_usn": "16114726760",
"esitef_usn": "210106064204470",
"host_usn": "304123216",
"tid": "210106064204470",
"amount": "47",
"payment_type": "C",
"payment_date": "06/01/2021T17:40"
},
{
"authorizer_code": "200",
"authorizer_message": "Success. [Cód.: 00]",
"status": "PPN",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "1609965604696",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "202",
"acquirer_name": "e.Rede REST",
"authorizer_date": "06/01/2021T17:40",
"authorization_number": "962291",
"merchant_usn": "16114726760",
"esitef_usn": "210106064204480",
"host_usn": "487097429",
"tid": "210106064204480",
"amount": "510",
"payment_type": "C",
"payment_date": "06/01/2021T17:40"
}
]
}
Caso de falha na confirmação da segunda transação
Quando a segunda confirmação falha, a primeira transação já está confirmada e o cancelamento, caso seja desejado, deve ser feito manualmente, seja usando o cancelamento REST ou o Portal do Lojista. Uma ocorrência é gerada para a equipe de suporte do e-SiTef e o lojista, caso deseje, pode entrar em contato.
Exemplo de resposta
{
"code": "1013",
"message": "Error processing multiple payment methods",
"payments": [
{
"authorizer_code": "200",
"authorizer_message": "Function performed error-free [Cód.: 00]",
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "20030404545",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "414",
"acquirer_name": "IPG",
"authorizer_date": "25/03/2020T17:48",
"authorization_number": "488040",
"merchant_usn": "20030404545",
"esitef_usn": "200325048537190",
"host_usn": "572994560",
"tid": "SIM64194442",
"amount": "102",
"payment_type": "C",
"payment_date": "25/03/2020T17:48"
},
{
"authorizer_code": "200",
"authorizer_message": "Function performed error-free [Cód.: 00]",
"status": "PEN",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "20030404545",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "414",
"acquirer_name": "IPG",
"authorizer_date": "25/03/2020T17:48",
"authorization_number": "454463",
"merchant_usn": "20030404545",
"esitef_usn": "200325048537200",
"host_usn": "108829897",
"tid": "SIM45823552",
"amount": "103",
"payment_type": "C",
"payment_date": "25/03/2020T17:48"
}
]
}
Fluxo de pagamento com confirmação tardia
O fluxo de pagamento com confirmação tardia nos pagamentos com múltiplos meios de pagamentos possui uma peculiaridade que é dividir o pagamento em 2 (duas) fases: atualização/inicialização das transações; pagamentos.
Em caso de falha em qualquer uma das transações, o e-SiTef não prossegue para a etapa seguinte e faz tratamentos que serão explicados a seguir nos casos de falhas.
Caso de sucesso
Caso de falha no pagamento da primeira transação
Quando o primeiro pagamento falha, a segunda transação será cancelada e não será disparada para a Autorizadora.
Exemplo de resposta
{
"code": "1013",
"message": "Error processing multiple payment methods",
"payments": [
{
"authorizer_code": "19",
"authorizer_message": "19 Refaca Trans.",
"status": "NEG",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "25052428543",
"authorizer_id": "1",
"acquirer_id": "5",
"acquirer_name": "Redecard",
"authorizer_date": "25/03/2020T17:24",
"authorization_number": "080384",
"merchant_usn": "25052428543",
"esitef_usn": "200325048537090",
"sitef_usn": "606060",
"host_usn": "707070",
"amount": "1254784",
"payment_type": "C",
"issuer": "1",
"authorizer_merchant_id": "00000005"
},
{
"status": "CAN"
}
]
}
Caso de falha no pagamento da segunda transação
Quando o segundo pagamento falha, a primeira transação será desfeita.
Exemplo de resposta
{
"code": "1013",
"message": "Error processing multiple payment methods",
"payments": [
{
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "PPN",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "25053142469",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id": "1",
"acquirer_id": "5",
"acquirer_name": "Redecard",
"authorizer_date": "25/03/2020T17:31",
"authorization_number": "252490",
"merchant_usn": "25053142469",
"esitef_usn": "200325048537130",
"sitef_usn": "252490",
"host_usn": "999252490 ",
"amount": "100",
"payment_type": "C",
"issuer": "1",
"authorizer_merchant_id": "000000000000005",
"payment_date": "25/03/2020T17:31"
},
{
"authorizer_code": "255",
"authorizer_message": "(2)Cartao invalido",
"status": "NEG",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "25053142469",
"authorizer_id": "2",
"acquirer_name": "REDE",
"merchant_usn": "25053142469",
"esitef_usn": "200325048537140"
}
]
}
Detalhes da chamada
- Recurso:
/v1/payments/multiple/{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 e-SiTef. Os códigos de produção e certificação serão diferentes. | < 15 AN | SIM |
merchant_key | Chave de autenticação da loja no e-SiTef. 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
Requisição:
curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/multiple/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"multiple_payment_methods": [
{
"number": "45518201234512345",
"expiry_date": "1222",
"security_code": "123",
"authorizer_id": "218",
"installments": "1",
"installment_type": "4",
"amount": "512"
},
{
"number": "45518201234512345",
"expiry_date": "1222",
"security_code": "123",
"authorizer_id": "218",
"installments": "1",
"installment_type": "4",
"amount": "510"
}
]
}
--verbose
Resposta:
{
"code": "0",
"message": "OK. Transaction successful.",
"payments": [
{
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "PPC",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "20125445982",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id": "1",
"acquirer_id": "5",
"acquirer_name": "Redecard",
"authorizer_date": "20/03/2020T14:32",
"authorization_number": "202650",
"merchant_usn": "16013439434",
"esitef_usn": "200320048363850",
"sitef_usn": "202650",
"host_usn": "999202650 ",
"amount": "512",
"payment_type": "C",
"issuer": "1",
"authorizer_merchant_id": "000000000000005",
"payment_date": "20/03/2020T14:32"
},
{
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "PPC",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "20125445982",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "5",
"acquirer_name": "Redecard",
"authorizer_date": "20/03/2020T14:32",
"authorization_number": "202651",
"merchant_usn": "16013439434",
"esitef_usn": "200320048363860",
"sitef_usn": "202651",
"host_usn": "999202651 ",
"amount": "510",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"payment_date": "20/03/2020T14:32"
}
]
}
Pagamento com cartão armazenado
Requisição:
curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"multiple_payment_methods": [
{
"token": "g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ==",
"authorizer_id": "1",
"installments": "1",
"installment_type": "4",
"amount": "512",
"security_code": "123"
},
{
"token": "g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ==",
"authorizer_id": "2",
"installments": "1",
"installment_type": "3",
"amount": "510",
"security_code": "321"
}
]
}
--verbose
Resposta:
{
"code": "0",
"message": "OK. Transaction successful.",
"payments": [
{
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "PPC",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "20125445982",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id": "1",
"acquirer_id": "5",
"acquirer_name": "Redecard",
"authorizer_date": "20/03/2020T14:32",
"authorization_number": "202650",
"merchant_usn": "16013439434",
"esitef_usn": "200320048363850",
"sitef_usn": "202650",
"host_usn": "999202650 ",
"amount": "512",
"payment_type": "C",
"issuer": "1",
"authorizer_merchant_id": "000000000000005",
"payment_date": "20/03/2020T14:32"
},
{
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "PPC",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "20125445982",
"customer_receipt":"====CUPOM COMPRADOR====",
"merchant_receipt":"====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "5",
"acquirer_name": "Redecard",
"authorizer_date": "20/03/2020T14:32",
"authorization_number": "202651",
"merchant_usn": "16013439434",
"esitef_usn": "200320048363860",
"sitef_usn": "202651",
"host_usn": "999202651 ",
"amount": "510",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"payment_date": "20/03/2020T14:32"
}
]
}
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 com múltiplos meios de pagamento:
Parâmetro | Descrição | Formato | Obrigatório |
---|---|---|---|
multiple_payment_methods[] | Consiste em um array para pagamentos com múltiplos meios de pagamento em que cada item representa um meio de pagamento. Devem ser informados exatamente 2 (dois) itens, os quais são compostos pelos campos descritos abaixo. | ||
authorizer_id | Código da autorizadora no e-SiTef. 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 | SIM |
installments | Número de parcelas. Caso não seja informado, será usado o valor passado na inicialização da transação no e-SiTef. | < 2 N | NÃO |
installment_type | Tipo de financiamento. Caso não seja informado, será usado o valor passado na inicialização da transação no e-SiTef. | < 2 N | NÃO |
amount | Valor da compra especificado pela loja para este meio de pagamento (em centavos). | < 12 N | SIM |
number | Número do cartão do comprador (PAN). | < 19 N | SIM |
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. |
token | HASH de um cartão armazenado no e-SiTef. 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 |
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. Importante: um pagamento com agendamento implica no armazenamento dos dados do cartão do comprador no ambiente do e-SiTef. 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. |
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 e-SiTef para a operação de múltiplos meios de pagamento. Qualquer código diferente de 0 significa falha. Saiba mais. | < 4 N |
message | Mensagem de resposta do e-SiTef para a operação de múltiplos meios de pagamento. | < 500 AN |
payments[] | Consiste em um array para pagamentos com múltiplos meios de pagamento no qual cada item representa a resposta correspondente a um dos meios de pagamentos. Os itens são compostos pelos campos descritos abaixo. | |
code | Código de resposta do e-SiTef para a operação de pagamento de um dos meios de pagamento. Qualquer código diferente de 0 significa falha. Saiba mais. | < 4 N |
message | Mensagem de resposta do e-SiTef para a operação de pagamento de um dos meios de pagamento. | < 500 AN |
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 e-SiTef. Saiba mais. | = 3 AN |
nit | Identificador da transação de pagamento no e-SiTef. | = 64 AN |
order_id | Código de pedido enviado pela loja na criação da transação. | < 20 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 para este meio de pagamento (em centavos). | < 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 e-SiTef. | = 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. | < 15 AN |
tid | ID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef. | < 40 AN |
eci | Eletronic Commerce Indicator (indicador do nível de segurança da transação do pagamento via Cielo e-Commerce). | < 3 AN |
payment_date | Data de efetivação do pagamento no e-SiTef 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 |
authentication_url | URL de autenticação retornada em fluxos de pagamento com autenticação. Disponível apenas para Cielo e-Commerce. | < 56 AN |
balance | Saldo disponível após pagamentos com cartões tipo Gift. | < 12 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 e-SiTef. Este campo pode assumir os seguintes valores:NOV – Nova.EXP – Expirada.ACC – AceitaREJ – RejeitadaREV – Em revisãoINV – Inválida | = 3 AN |