Realização de uma transação

Esta operação provê um mecanismo unificado para execução de transações financeiras no Cielo Conecta, contemplando tanto a realização de pagamentos em diferentes modalidades quanto a reversão dessas transações por meio de estorno ou cancelamento.

A finalidade desta operação é permitir que a aplicação cliente execute transações financeiras, abrangendo pagamentos e cancelamentos de transações previamente realizadas e confirmadas.

Seu objetivo é garantir integridade operacional, rastreabilidade e conciliação entre o sistema de Automação Comercial e o Cielo Conecta, por meio do controle de identificadores e da confirmação das transações conforme configuração definida na inicialização.

As transações suportadas são:

Operação de pagamento:
- Débito;
- Crédito à vista;
- Crédito parcelado;
- Voucher;
Operação de estorno ou cancelamento.

Operação de pagamento

Realiza transações de pagamento em qualquer modalidade suportada, gerando identificadores internos e externos para controle, conciliação e auditoria.

Campos obrigatórios

Oper: tipo da operação. Valor fixo 5;
TransactionType: modalidade do pagamento;
Amount: valor da transação (em centavos/unidade mínima);
MerchantOrderId: identificador gerado pela Automação Comercial.

Regras de identificadores e persistência

MerchantOrderId deve ser único por pagamento;
- Garante rastreabilidade e idempotência;
- Deve ser controlado pelo sistema da aplicação;
PaymentId é retornado na resposta da operação
- Representa o identificador oficial da transação no Cielo Conecta
- Deve ser armazenado e associado ao MerchantOrderId

Exemplo de requisição

[
  {
    "TransactionType": "01",
    "Installments": "1",
    "Amount": "75000",
    "MerchantOrderId": "123456789012345",
    "Oper": "005"
  }
]

Operação de estorno ou cancelamento

Responsável por reverter uma transação de pagamento previamente realizada e confirmada, utilizando identificadores internos (da Automação Comercial - MerchantOrderID) ou externos (do Cielo Conecta - PaymentId).

Formas de cancelamento

A API Client Conecta disponibiliza a operação de cancelar ou estornar de duas maneiras:

Por identificador do Cielo Conecta:

RefundPaymentId: corresponde a identificação da transação de pagamento.

Por identificador da Automação Comercial:

RefundMerchantOrderId: corresponde a identificação da transação de pagamento pelo software de Automação Comercial;
RefundDatetime: data e hora da transação de pagamento original realizada;
RefundNSU: número de identificação da transação de pagamento original realizada;
RefundAuthorizationCode: código de autorização da transação de pagamento original realizada.

Regras de identificadores e persistência

MerchantOrderId deve ser único para cada estorno/cancelamento;
- Evita múltiplas reversões da mesma transação;
PaymentId será retornado para a operação de estorno/cancelamento;
- Deve ser armazenado e vinculado à transação original.

Ação recomendada: armazenar o PaymentId e relacioná-lo ao MerchantOrderId da operação de estorno/cancelamento, vinculando também à transação original (RefundPaymentId ⇄ RefundMerchantOrderId).

Exemplo de requisição

[
  {
    "TransactionType": "50",
    "Installments": "1",
    "Amount": "75000",
    "MerchantOrderId": "123456789012345",
    "RefundPaymentId": "abb385f9-f605-4adb-83b0-a8a9efeec430",
    "Oper": "005"
  }
]

⚠️
Atenção
Após a execução do pagamento ou do cancelamento, a transação deve ser confirmada pela Automação Comercial para sua conclusão no Cielo Conecta.

A necessidade de confirmação depende da configuração realizada na inicialização;

Caso a confirmação não seja automática, deve ser executada a operação de confirmação.

Parâmetros de entrada

Campo	Tipo	Formato	Presença	Descrição
`Oper`	string	N..3	M	Código da operação: fixo “5” (`CFL_OPER_TRANSACTION`)
`TransactionType`	string	N2	M	Tipo da transação a ser realizada: “01” = “Crédito a vista”; “02” = “Débito”; “03” = “Crédito parcelado sem juros”; “04” = “Crédito parcelado com juros”; “30” = “Voucher”; “50” = “Cancelamento de crédito”; “51” = “Cancelamento de débito”; “52” = “Cancelamento de voucher”.
`Amount`	string	N..12	M	Valor da transação a ser realizada.
`Installments`	string	N..2	O	Número de parcelas: “01” a “99”; Se não informado, assume o valor “01”.
`MerchantOrderId`	string	N15	M	Chave única de identificação da transação, de controle da Automação Comercial.
`RefundPaymentId`	string	A36	O	Chave única de identificação da transação a ser cancelada no Cielo Conecta. Campo mandatório para realizar transações de cancelamento: `TransactionType` = “5x”. Na utilização deste campo, não é necessário a informação dos demais campos para o cancelamento: `RefundMerchantOrderId`, `RefundDatetime`, `RefundNSU` e `RefundAuthorizationCode`.
`RefundMerchantOrderId`	string	N15	O	Chave única de identificação, de controle da Automação Comercial, da transação a ser cancelada. Campo mandatório para realizar transações de cancelamento: `TransactionType` = “5x”. Deve ser utilizado juntamente com os campos: `RefundDatetime`, `RefundNSU` e `RefundAuthorizationCode`. Na utilização deste campo, o campo `RefundPaymentId` não é mandatório.
`RefundDatetime`	string	N14	O	Data e hora da transação original a ser cancelada no formato “AAAAMMDDhhmmss”. Campo mandatório para realizar transações de cancelamento: `TransactionType` = “5x”. Deve ser utilizado juntamente com os campos: `RefundMerchantOrderId`, `RefundNSU` e `RefundAuthorizationCode`. Na utilização deste campo, o campo `RefundPaymentId` não é mandatório.
`RefundNSU`	string	A6	O	NSU da transação a ser cancelada. Campo mandatório para realizar transações de cancelamento: `TransactionType` = “5x”. Deve ser utilizado juntamente com os campos: `RefundMerchantOrderId`, `RefundDatetime` e `RefundAuthorizationCode`. Na utilização deste campo, o campo `RefundPaymentId` não é mandatório.
`RefundAuthorizationCode`	string	A6	O	Código de autorização da transação de pagamento a ser cancelada. Campo mandatório para realizar transações de cancelamento: “TransactionType” = “5x”. Deve ser utilizado juntamente com os campos: `RefundMerchantOrderId`, `RefundDatetime` e `RefundNSU`. Na utilização deste campo, o campo `RefundPaymentId` não é mandatório.
`Tokenize`	string	N..2	O	Solicita a tokenização do cartão após a autorização do pagamento: “1” = solicitar tokenização ou “0” = não tokenizar. A tokenização somente é efetivada quando a transação é aprovada (`PhysicalTransactionStatus`= “2” ou “20”).

Mensagem de notificação recebida na callback da operação

Durante o processamento, a biblioteca Client Conecta pode enviar notificações de status por meio da função de callback.

Campo	Tipo	Formato	Presença	Descrição
`Oper`	string	N..3	ME	Código da operação: fixo “5” (`CFL_OPER_TRANSACTION`).
`Code`	string	N2	M	Código de identificação do conteúdo
do JSON enviado na função de
callback. Contém o código da
mensagem de notificação.
`MsgNotify`	string	A..99	M	Mensagem de notificação gerada
durante o processamento da
transação.

Dados de resposta recebido na callback da operação

Após a conclusão da operação, os dados são retornados via callback.

Campos retornados:

Campo	Tipo	Formato	Presença	Descrição
`Oper`	string	N..3	ME	Código da operação: fixo “5” (`CFL_OPER_TRANSACTION`).
`Code`	string	N2	M	Código da mensagem. fixo “0” = indica que o JSON contém os dados de resposta da operação realizada.
`TransactionType`	string	N2	ME	Tipo da transação realizada.
`Amount`	string	N..12	ME	Valor da transação realizada.
`Installments`	string	N..2	ME	Número de parcelas, de “01” a “99”.
`MerchantOrderId`	string	N15	ME	Chave única de identificação da transação.
`Datetime`	string	N14	M	Data e hora da transação no formato “AAAAMMDDhhmmss”.
`PhysicalTransactionStatus`	string	N..2	M	Status da transação realizada: “0” = não processada; “2” = aprovada, pendente de confirmação; “3” = não aprovada/negada; “10” = cancelada; “13” = abortada e/ou desfeita; “20” = confirmada.
`ReturnCode`	string	A3	O	Código de erro ou resposta da transação no Cielo Conecta.
`ReturnMessage`	string	A..99	O	Mensagem de erro ou resposta da transação no Cielo Conecta.
`ExtendedMessage`	string	A..99	O	Mensagem estendida de resposta ou de erro recebida do Cielo Conecta para a transação realizada.
`PaymentId`	string	A36	O	Chave única de identificação da transação no Cielo Conecta.
`NSU`	string	A6	O	NSU da transação realizada.
`AuthorizationCode`	string	A6	O	Código de autorização da transação realizada.
`BrandInfoName`	string	A..99	O	Bandeira do cartão.
`NSUOriginal`	string	A6	O	NSU da transação que foi cancelada. Campo enviado e mandatório apenas quando está realizando uma operação de cancelamento (`TransactionType`= “5x”).
`TransactionReceiptCliImg`	string	A..999	O	Base64 da imagem da via do cliente do comprovante da transação. Campo mandatório quando a transação é aprovada e/ou confirmada. `PhysicalTransactionStatus` = “2” ou `PhysicalTransactionStatus` = “20”.
`TransactionReceiptMchImg`	string	A..999	O	Base64 da imagem da via do estabelecimento do comprovante da transação. Campo mandatório quando a transação é aprovada e/ou confirmada. `PhysicalTransactionStatus` = “2” ou `PhysicalTransactionStatus` = “20”.
`TransactionReceiptCli`	string	A..999	O	Via do cliente do comprovante da transação em formato texto. Campo mandatório quando a transação é aprovada e/ou confirmada. `PhysicalTransactionStatus` = “2” ou `PhysicalTransactionStatus` = “20”.
`TransactionReceiptMch`	string	A..999	O	Via do estabelecimento do comprovante da transação em formato texto. Campo mandatório quando a transação é aprovada e/ou confirmada. `PhysicalTransactionStatus` = “2” ou `PhysicalTransactionStatus` = “20”.
`CardToken`	string	A36	O	Token do cartão gerado por Cielo E-commerce durante o pagamento, retornado no body de resposta do callback, no mesmo nível dos demais campos da transação (ex.: PaymentId, NSU, AuthorizationCode). Está presente apenas quando o campo `Tokenize` foi informado na requisição e a transação foi aprovada (`PhysicalTransactionStatus` = “2” ou “20”). Formato GUID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. A Automação Comercial deve ler e persistir esse valor para uso em transações futuras (pagamento com token, no E-commerce Cielo).

Retornos

Código	Descrição
`CFL_OK`	Operação realizada com sucesso
`CFL_ERROR_INVCALL`	Operação não permitida no momento
`CFL_ERROR_INVPARAM`	Parâmetros inválidos
`CFL_ERROR_NETWORK`	Erro na comunicação com Cielo Conecta