[Feature] Chargeback

examples/Chargeback/Get.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace Examples\Chargeback;
+
+// Step 1: Require the Composer library
+require_once '../../vendor/autoload.php';
+
+use MercadoPago\Client\Chargeback\ChargebackClient;
+use MercadoPago\Client\Common\RequestOptions;
+use MercadoPago\Exceptions\MPApiException;
+use MercadoPago\MercadoPagoConfig;
+
+// Step 2: Set the production or sandbox access token
+MercadoPagoConfig::setAccessToken("<YOUR_ACCESS_TOKEN>");
+
+// Step 3: Initialize the API client
+$client = new ChargebackClient();
+
+try {
+    // Step 4: Get chargeback by ID
+    $chargeback_id = "CHARGEBACK_ID";
+    $chargeback = $client->get($chargeback_id);
+
+    echo "Chargeback ID: " . $chargeback->id . "\n";
+    echo "Payment ID: " . $chargeback->payment_id . "\n";
+    echo "Amount: " . $chargeback->amount . "\n";
+    echo "Status: " . $chargeback->status . "\n";
+    echo "Reason: " . $chargeback->reason . "\n";
+    echo "Stage: " . $chargeback->stage . "\n";
+
+    // Step 5: Handle exceptions
+} catch (MPApiException $e) {
+    echo "Status code: " . $e->getApiResponse()->getStatusCode() . "\n";
+    echo "Content: ";
+    var_dump($e->getApiResponse()->getContent());
+    echo "\n";
+} catch (\Exception $e) {
+    echo $e->getMessage();
+} 

examples/Chargeback/Search.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Examples\Chargeback;
+
+// Step 1: Require the Composer library
+require_once '../../vendor/autoload.php';
+
+use MercadoPago\Client\Chargeback\ChargebackClient;
+use MercadoPago\Client\Common\RequestOptions;
+use MercadoPago\Exceptions\MPApiException;
+use MercadoPago\MercadoPagoConfig;
+use MercadoPago\Net\MPSearchRequest;
+
+// Step 2: Set the production or sandbox access token
+MercadoPagoConfig::setAccessToken("<YOUR_ACCESS_TOKEN>");
+
+// Step 3: Initialize the API client
+$client = new ChargebackClient();
+
+try {
+    // Step 4: Create search filters
+    $search_filters = array(
+        "payment_id" => "PAYMENT_ID", // Optional: filter by payment ID
+        "status" => "open", // Optional: filter by status (open, closed, etc.)
+        "stage" => "chargeback", // Optional: filter by stage
+        "offset" => 0,
+        "limit" => 50
+    );
+
+    $search_request = new MPSearchRequest($search_filters);
+
+    // Step 5: Perform the search
+    $search_result = $client->search($search_request);
+
+    echo "Total results: " . $search_result->paging->total . "\n";
+    echo "Results found: " . count($search_result->results) . "\n\n";
+
+    // Step 6: Display results
+    foreach ($search_result->results as $chargeback) {
+        echo "Chargeback ID: " . $chargeback->id . "\n";
+        echo "Payment ID: " . $chargeback->payment_id . "\n";
+        echo "Amount: " . $chargeback->amount . " " . $chargeback->currency . "\n";
+        echo "Status: " . $chargeback->status . "\n";
+        echo "Reason: " . $chargeback->reason . "\n";
+        echo "Date Created: " . $chargeback->date_created . "\n";
+        echo "---\n";
+    }
+
+    // Step 7: Handle exceptions
+} catch (MPApiException $e) {
+    echo "Status code: " . $e->getApiResponse()->getStatusCode() . "\n";
+    echo "Content: ";
+    var_dump($e->getApiResponse()->getContent());
+    echo "\n";
+} catch (\Exception $e) {
+    echo $e->getMessage();
+} 

src/MercadoPago/Client/Chargeback/ChargebackClient.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace MercadoPago\Client\Chargeback;
+
+use MercadoPago\Client\Common\RequestOptions;
+use MercadoPago\Client\MercadoPagoClient;
+use MercadoPago\MercadoPagoConfig;
+use MercadoPago\Net\HttpMethod;
+use MercadoPago\Net\MPHttpClient;
+use MercadoPago\Net\MPSearchRequest;
+use MercadoPago\Resources\Chargeback;
+use MercadoPago\Resources\ChargebackSearch;
+use MercadoPago\Serialization\Serializer;
+
+/** Client responsible for performing chargeback actions. */
+final class ChargebackClient extends MercadoPagoClient
+{
+    private const URL = "/v1/chargebacks";
+
+    private const URL_WITH_ID = "/v1/chargebacks/%s";
+
+    private const URL_SEARCH = "/v1/chargebacks/search";
+
+    /** Default constructor. Uses the default http client used by the SDK or custom http client provided. */
+    public function __construct(?MPHttpClient $MPHttpClient = null)
+    {
+        parent::__construct($MPHttpClient ?: MercadoPagoConfig::getHttpClient());
+    }
+
+    /**
+     * Method responsible for getting chargeback.
+     * @param string $id chargeback ID.
+     * @param \MercadoPago\Client\Common\RequestOptions request options to be sent.
+     * @return \MercadoPago\Resources\Chargeback chargeback found.
+     * @throws \MercadoPago\Exceptions\MPApiException if the request fails.
+     * @throws \Exception if the request fails.
+     */
+    public function get(string $id, ?RequestOptions $request_options = null): Chargeback
+    {
+        $response = parent::send(sprintf(self::URL_WITH_ID, $id), HttpMethod::GET, null, null, $request_options);
+        $result = Serializer::deserializeFromJson(Chargeback::class, $response->getContent());
+        $result->setResponse($response);
+        return $result;
+    }
+
+    /**
+     * Method responsible for search chargebacks.
+     * @param \MercadoPago\Net\MPSearchRequest $request search request.
+     * @param \MercadoPago\Client\Common\RequestOptions request options to be sent.
+     * @return \MercadoPago\Resources\ChargebackSearch search results.
+     * @throws \MercadoPago\Exceptions\MPApiException if the request fails.
+     * @throws \Exception if the request fails.
+     */
+    public function search(MPSearchRequest $request, ?RequestOptions $request_options = null): ChargebackSearch
+    {
+        $query_params = isset($request) ? $request->getParameters() : null;
+        $response = parent::send(self::URL_SEARCH, HttpMethod::GET, null, $query_params, $request_options);
+        $result = Serializer::deserializeFromJson(ChargebackSearch::class, $response->getContent());
+        $result->setResponse($response);
+        return $result;
+    }
+} 

src/MercadoPago/Resources/Chargeback.php

@@ -0,0 +1,90 @@
+<?php
+
+namespace MercadoPago\Resources;
+
+use MercadoPago\Net\MPResource;
+use MercadoPago\Serialization\Mapper;
+
+/** Chargeback class. */
+class Chargeback extends MPResource
+{
+    /** Class mapper. */
+    use Mapper;
+
+    /** Chargeback ID. */
+    public ?string $id;
+
+    /** Payment ID associated with the chargeback. */
+    public ?int $payment_id;
+
+    /** Chargeback amount. */
+    public ?float $amount;
+
+    /** Currency of the chargeback. */
+    public ?string $currency;
+
+    /** Chargeback reason. */
+    public ?string $reason;
+
+    /** Stage of the chargeback. */
+    public ?string $stage;
+
+    /** Status of the chargeback. */
+    public ?string $status;
+
+    /** Date when the chargeback was created. */
+    public ?string $date_created;
+
+    /** Date when the chargeback was last updated. */
+    public ?string $date_last_updated;
+
+    /** Documentation deadline for the chargeback. */
+    public ?string $documentation_deadline;
+
+    /** Coverage applied to the chargeback. */
+    public ?bool $coverage_applied;
+
+    /** Coverage eligible for the chargeback. */
+    public ?bool $coverage_eligible;
+
+    /** External reference of the chargeback. */
+    public ?string $external_reference;
+
+    /** Metadata associated with the chargeback. */
+    public array|object|null $metadata;
+
+    /** Documentation status. */
+    public ?string $documentation_status;
+
+    /** Chargeback sequence number. */
+    public ?int $chargeback_sequence_number;
+
+    /** Source information. */
+    public array|object|null $source;
+
+    /** Case information. */
+    public array|object|null $case;
+
+    /** Risk score. */
+    public ?float $risk_score;
+
+    /** Payment method information. */
+    public array|object|null $payment_method;
+
+    /** Transaction details. */
+    public array|object|null $transaction_details;
+
+    private $map = [
+        "source" => "MercadoPago\Resources\Common\Source",
+        "payment_method" => "MercadoPago\Resources\Payment\PaymentMethod",
+        "transaction_details" => "MercadoPago\Resources\Payment\TransactionDetails",
+    ];
+
+    /**
+     * Method responsible for getting map of entities.
+     */
+    public function getMap(): array
+    {
+        return $this->map;
+    }
+} 

src/MercadoPago/Resources/ChargebackSearch.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace MercadoPago\Resources;
+
+use MercadoPago\Net\MPResource;
+use MercadoPago\Serialization\Mapper;
+
+/** ChargebackSearch class. */
+class ChargebackSearch extends MPResource
+{
+    /** Class mapper. */
+    use Mapper;
+
+    /** Paging information. */
+    public array|object|null $paging;
+
+    /** List of chargebacks. */
+    public ?array $results;
+
+    private $map = [
+        "results" => "MercadoPago\Resources\Chargeback",
+        "paging" => "MercadoPago\Resources\Common\Paging",
+    ];
+
+    /**
+     * Method responsible for getting map of entities.
+     */
+    public function getMap(): array
+    {
+        return $this->map;
+    }
+} 

tests/MercadoPago/Client/Unit/Chargeback/ChargebackClientUnitTest.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace MercadoPago\Tests\Client\Unit\Chargeback;
+
+use MercadoPago\Client\Chargeback\ChargebackClient;
+use MercadoPago\MercadoPagoConfig;
+use MercadoPago\Net\MPDefaultHttpClient;
+use MercadoPago\Net\MPSearchRequest;
+use MercadoPago\Tests\Client\Unit\Base\BaseClient;
+
+/**
+ * ChargebackClient unit tests.
+ */
+final class ChargebackClientUnitTest extends BaseClient
+{
+    public function testGetSuccess(): void
+    {
+        $filepath = '../../../../Resources/Mocks/Response/Chargeback/chargeback_base.json';
+        $mock_http_request = $this->mockHttpRequest($filepath, 200);
+
+        $http_client = new MPDefaultHttpClient($mock_http_request);
+        MercadoPagoConfig::setHttpClient($http_client);
+
+        $client = new ChargebackClient();
+        $chargeback = $client->get("123456");
+
+        $this->assertSame(200, $chargeback->getResponse()->getStatusCode());
+        $this->assertSame("123456", $chargeback->id);
+        $this->assertSame(987654321, $chargeback->payment_id);
+        $this->assertSame(100.0, $chargeback->amount);
+        $this->assertSame("BRL", $chargeback->currency);
+        $this->assertSame("fraud", $chargeback->reason);
+        $this->assertSame("chargeback", $chargeback->stage);
+        $this->assertSame("open", $chargeback->status);
+    }
+
+    public function testSearchSuccess(): void
+    {
+        $filepath = '../../../../Resources/Mocks/Response/Chargeback/chargeback_search.json';
+        $mock_http_request = $this->mockHttpRequest($filepath, 200);
+
+        $http_client = new MPDefaultHttpClient($mock_http_request);
+        MercadoPagoConfig::setHttpClient($http_client);
+
+        $client = new ChargebackClient();
+        $filters = array("payment_id" => "987654321");
+        $search_request = new MPSearchRequest(50, 0, $filters);
+        $search_result = $client->search($search_request);
+
+        $this->assertSame(200, $search_result->getResponse()->getStatusCode());
+        $this->assertSame(1, $search_result->paging->total);
+        $this->assertSame(1, count($search_result->results));
+        $this->assertSame("123456", $search_result->results[0]->id);
+        $this->assertSame(987654321, $search_result->results[0]->payment_id);
+    }
+} 

tests/MercadoPago/Resources/Mocks/Response/Chargeback/chargeback_base.json

@@ -0,0 +1,42 @@
+{
+  "id": "123456",
+  "payment_id": 987654321,
+  "amount": 100.0,
+  "currency": "BRL",
+  "reason": "fraud",
+  "stage": "chargeback",
+  "status": "open",
+  "date_created": "2023-01-15T10:30:00.000-04:00",
+  "date_last_updated": "2023-01-15T10:30:00.000-04:00",
+  "documentation_deadline": "2023-01-22T23:59:59.000-04:00",
+  "coverage_applied": false,
+  "coverage_eligible": true,
+  "external_reference": "ext_ref_123",
+  "metadata": {
+    "key1": "value1",
+    "key2": "value2"
+  },
+  "documentation_status": "pending",
+  "chargeback_sequence_number": 1,
+  "source": {
+    "id": "475845652",
+    "name": "Test Source",
+    "type": "collector"
+  },
+  "case": {
+    "id": "case_123",
+    "number": "CB-123456789",
+    "type": "chargeback"
+  },
+  "risk_score": 75.5,
+  "payment_method": {
+    "id": "visa",
+    "type": "credit_card"
+  },
+  "transaction_details": {
+    "net_received_amount": 95.0,
+    "total_paid_amount": 100.0,
+    "overpaid_amount": 0,
+    "installment_amount": 100.0
+  }
+}