README

SDK de integração com a API E-commerce Cielo: cartão de crédito, consulta, captura, cancelamento, Zero Auth, tokenização e parser do Post de Notificação.

Funcionalidades

Cartão de crédito: autorização com captura automática ou posterior (inclui parcelamento e CardToken)
Captura total ou parcial (PUT /1/sales/{PaymentId}/capture)
Cancelamento e estorno (void / refund) total ou parcial por PaymentId ou MerchantOrderId
Consulta por PaymentId, Tid e MerchantOrderId (API de query)
Zero Auth (validação de cartão) e tokenização (Cartão Protegido)
Parser do Post de Notificação
Mapeamento dos status transacionais da Cielo

Requisitos

PHP >= 8.1
Guzzle HTTP

Instalação

composer require devsitarget/sdk-cielo-php

Configuração

<?php

use CieloSdk\Cielo;
use CieloSdk\Environment;
use CieloSdk\Store;

$store = new Store(
    merchantId: 'SEU_MERCHANT_ID',
    merchantKey: 'SEU_MERCHANT_KEY',
    environment: Environment::sandbox() // ou Environment::production()
);

$cielo = new Cielo($store);

Valores monetários são sempre enviados em centavos (int), como exige a API Cielo (Amount = 15700 equivale a R$ 157,00).

Uso básico

Criar pagamento com cartão de crédito (captura automática)

<?php

use CieloSdk\Address;
use CieloSdk\CreditCard\CreditCard;
use CieloSdk\CreditCard\CreditCardRequest;
use CieloSdk\Customer;

$sale = $cielo->createCreditCardPayment(new CreditCardRequest(
    merchantOrderId: '2017051001',
    amount: 15700,
    customer: new Customer(
        name: 'Aline de Souza',
        email: 'aline@email.com',
        identity: '12345678909',
        address: new Address(
            street: 'Alameda Xingu',
            number: '512',
            zipCode: '12345987',
            city: 'São Paulo',
            state: 'SP'
        )
    ),
    creditCard: new CreditCard(
        holder: 'Aline de Souza',
        expirationDate: '12/2035',
        brand: 'Visa',
        number: '4091688625337641',
        securityCode: '333'
    ),
    installments: 1,
    capture: true,
    softDescriptor: 'LojaTeste'
));

// $sale->paymentId, $sale->tid, $sale->status, $sale->proofOfSale, $sale->authorizationCode

Autorizar agora e capturar depois

Envie capture: false na criação e chame capture() com o PaymentId retornado:

$sale = $cielo->createCreditCardPayment(new CreditCardRequest(
    merchantOrderId: '2017051001',
    amount: 15700,
    customer: $customer,
    creditCard: $creditCard,
    capture: false
));

$captured = $cielo->capture($sale->paymentId);           // total
$captured = $cielo->capture($sale->paymentId, 5000);     // parcial (centavos)

Cancelamento e estorno

Na API Cielo, cancelamento e estorno usam o mesmo endpoint (PUT /1/sales/{PaymentId}/void). O que muda é o momento:

até 23h59 do dia da autorização → status Voided (10), cancelamento
depois disso → status Refunded (11), estorno

refund() é alias de void(). Aceitam PaymentId ou acquirerTid (Tid). A Cielo só cancela por PaymentId; se vier só o Tid, o SDK consulta a transação e resolve o identificador.

$voided = $cielo->void($sale->paymentId);                          // total
$voided = $cielo->refund($sale->paymentId);                        // por PaymentId
$voided = $cielo->refund(acquirerTid: $sale->tid);                 // por Tid da adquirente
$voided = $cielo->refundByTid($sale->tid, 3000);                   // parcial via Tid
$voided = $cielo->void($sale->paymentId, null, 'HighRisk');        // motivo fraude
$voided = $cielo->refundByMerchantOrderId('2017051001', 15700);

Consultar transação

$sale = $cielo->getSale($sale->paymentId);
$sale = $cielo->getSaleByTid($sale->tid);
$list = $cielo->getSalesByMerchantOrderId('2017051001');
$status = $cielo->checkPaymentStatus($sale->paymentId);

A consulta usa a API de query (apiquerysandbox / apiquery), distinta da API transacional.

Zero Auth e tokenização

$validation = $cielo->zeroAuth($creditCard);
if ($validation->valid) {
    $token = $cielo->createCardToken($creditCard, 'Aline de Souza');
    // $token->cardToken
}

Pagamento com cartão já tokenizado:

$sale = $cielo->createCreditCardPayment(new CreditCardRequest(
    merchantOrderId: '2017051001',
    amount: 15700,
    customer: $customer,
    creditCard: new CreditCard(
        holder: 'Aline de Souza',
        expirationDate: '12/2035',
        brand: 'Visa',
        securityCode: '333',
        cardToken: $token->cardToken
    )
));

Post de Notificação

$parsed = Cielo::parseNotification($payload);
// $parsed['paymentId'], $parsed['changeType'], $parsed['changeTypeDescription']
$sale = $cielo->getSale($parsed['paymentId']);

Status transacionais

Código	Enum	Descrição
0	`NotFinished`	Aguardando atualização de status
1	`Authorized`	Autorizado, apto a capturar
2	`PaymentConfirmed`	Confirmado / capturado
3	`Denied`	Negado pelo autorizador
10	`Voided`	Cancelado
11	`Refunded`	Estornado após o dia da autorização
12	`Pending`	Aguardando instituição financeira
13	`Aborted`	Abortado por falha ou antifraude
20	`Scheduled`	Recorrência agendada

Docker

make build
make up
make install
make test
make phpstan
make cs-check
make shell

Variáveis de ambiente em env.example: CIELO_MERCHANT_ID, CIELO_MERCHANT_KEY, CIELO_ENVIRONMENT.

Estrutura

src/Cielo/
  Cielo.php                 # Facade
  CieloBaseClient.php       # HTTP (Guzzle) + headers MerchantId/MerchantKey
  Store.php / Environment.php
  CreditCard/               # Criação, captura e cancelamento
  Query/                    # Consultas na API de query
  Card/                     # Zero Auth e CardToken
  Notification/             # Parser do webhook

devsitarget / sdk-cielo-php

Maintainers

Package info

Statistics

Security