### Install Gifty PHP SDK

Source: https://github.com/giftyhq/gifty-php/blob/main/README.md

Use Composer to install the library in your project.

```bash
composer require gifty/gifty-php
```

--------------------------------

### Development Commands

Source: https://github.com/giftyhq/gifty-php/blob/main/README.md

Commands for cloning the repository, installing dependencies, and running tests.

```bash
git clone https://github.com/giftyhq/gifty-php
```

```bash
composer install
```

```bash
composer test
```

```bash
composer phpstan
```

```bash
composer phpcs
```

--------------------------------

### GET /packages

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Retrieves all gift card packages available in the account.

```APIDOC
## GET /packages

### Description
Get all gift card packages (predefined value configurations) available in your account.

### Method
GET

### Endpoint
/packages
```

--------------------------------

### GET /locations

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Retrieves all store locations configured in the Gifty account.

```APIDOC
## GET /locations

### Description
Get all store locations configured in your Gifty account.

### Method
GET

### Endpoint
/locations
```

--------------------------------

### GET /packages/{id}

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Fetches details of a specific gift card package by ID.

```APIDOC
## GET /packages/{id}

### Description
Fetch details of a specific package by ID.

### Method
GET

### Endpoint
/packages/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The package ID.
```

--------------------------------

### Initialize Gifty Client

Source: https://github.com/giftyhq/gifty-php/blob/main/README.md

Initialize the client with an API key. Optional headers can be passed as a second argument.

```php
$gifty = new \Gifty\Client\GiftyClient('eyJ0eXAi....');
$giftCard = $gifty->giftCards->get('ABCDABCDABCDABCD');
```

```php
$gifty = new \Gifty\Client\GiftyClient('eyJ0eXAi....', ['api_headers' => [
  'Accept-Language' => 'en',
  'X-Gifty-Location' => 'lc_123456789'
]]);
$giftCard = $gifty->giftCards->get('ABCDABCDABCDABCD');
```

--------------------------------

### Initialize Gifty Client

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Configure the GiftyClient with an API key and optional headers. Use validateApiKey() to verify credentials before performing operations.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

// Basic initialization
$gifty = new GiftyClient('your-api-key-here');

// With custom headers (e.g., for language and location)
$gifty = new GiftyClient('your-api-key-here', [
    'api_headers' => [
        'Accept-Language' => 'en',
        'X-Gifty-Location' => 'lc_123456789'
    ]
]);

// Validate API key
if ($gifty->validateApiKey()) {
    echo "API key is valid";
} else {
    echo "Invalid API key";
}
```

--------------------------------

### Retrieve All Packages with PHP

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Retrieves all predefined gift card package configurations available in the account.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    $packages = $gifty->packages->all();

    foreach ($packages as $package) {
        echo "Package ID: " . $package->getId() . "\n";              // gp_WxBZ9wp4ov6Da1d1rgjal6Dk
        echo "Title: " . $package->getTitle() . "\n";                // Lunch for 2
        echo "Description: " . $package->getDescription() . "\n";    // Lunch for 2, drinks excluded.
        echo "Amount: " . $package->getAmount() . "\n";              // 5950 (in cents)
        echo "Currency: " . $package->getCurrency() . "\n";          // EUR
        echo "Active: " . ($package->getActive() ? 'Yes' : 'No') . "\n";
        echo "---\n";
    }
} catch (ApiException $e) {
    echo "Error: " . $e->getMessage();
}
```

--------------------------------

### Handle API Exceptions and Checkout Flows in PHP

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Demonstrates catching specific Gifty exceptions and implementing a multi-step gift card payment process with balance validation and transaction capture.

```php
<?php

use Gifty\\\Client\\\GiftyClient;
use Gifty\\\Client\\\Exceptions\\\ApiException;
use Gifty\\\Client\\\Exceptions\\\MissingParameterException;

$gifty = new GiftyClient('your-api-key');

try {
    $giftCard = $gifty->giftCards->get('INVALID_CODE');
} catch (ApiException $e) {
    // Handle API errors (invalid code, network issues, etc.)
    echo "API Error: " . $e->getMessage() . "\n";
    echo "Error Code: " . $e->getCode() . "\n";
} catch (MissingParameterException $e) {
    // Handle missing required parameters
    echo "Missing Parameter: " . $e->getMessage() . "\n";
}

// Full checkout flow with error handling
function processGiftCardPayment(GiftyClient $gifty, string $code, int $amount): ?string
{
    try {
        // Step 1: Check gift card
        $giftCard = $gifty->giftCards->get($code);

        if (!$giftCard->isRedeemable()) {
            throw new \\Exception("Gift card cannot be redeemed");
        }

        if ($giftCard->getBalance() < $amount) {
            throw new \\Exception("Insufficient balance");
        }

        // Step 2: Create pending redemption
        $transaction = $gifty->giftCards->redeem($code, [
            'amount' => $amount,
            'currency' => 'EUR',
            'capture' => false
        ]);

        // Step 3: Capture after order confirmation
        $captured = $gifty->transactions->capture($transaction->getId());

        return $captured->getId();

    } catch (ApiException $e) {
        error_log("Gift card payment failed: " . $e->getMessage());
        return null;
    }
}
```

--------------------------------

### Retrieve a Single Package with PHP

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Fetches details for a specific gift card package using its unique ID.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    $package = $gifty->packages->get('gp_ABCDABCD');

    echo "Package: " . $package->getTitle() . "\n";
    echo "Value: €" . number_format($package->getAmount() / 100, 2) . "\n";
    echo "Description: " . $package->getDescription() . "\n";

    if ($package->getActive()) {
        echo "This package is currently available for purchase.\n";
    }
} catch (ApiException $e) {
    echo "Error: " . $e->getMessage();
}
```

--------------------------------

### Retrieve Locations

Source: https://github.com/giftyhq/gifty-php/blob/main/README.md

Fetch all available store locations.

```php
$locations = $gifty->locations->all();
```

--------------------------------

### Retrieve All Locations with PHP

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Fetches all store locations configured in the Gifty account.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    $locations = $gifty->locations->all();

    foreach ($locations as $location) {
        echo "Location ID: " . $location->getId() . "\n";            // lc_RVyje31w8pmKwwmqlZW096M7
        echo "Street: " . $location->getStreet() . "\n";             // Edisonweg
        echo "House Number: " . $location->getHouseNumber() . "\n";  // 5 bis
        echo "Addition: " . $location->getAddition() . "\n";
        echo "Postal Code: " . $location->getPostalCode() . "\n";    // 3404LA
        echo "City: " . $location->getCity() . "\n";                 // IJsselstein
        echo "---\n";
    }
} catch (ApiException $e) {
    echo "Error: " . $e->getMessage();
}
```

--------------------------------

### Retrieve Packages

Source: https://github.com/giftyhq/gifty-php/blob/main/README.md

Fetch all gift card packages or a specific package by ID.

```php
$packages = $gifty->packages->all();
```

```php
$package = $gifty->packages->get('gp_ABCDABCD');
```

--------------------------------

### Retrieve All Transactions

Source: https://context7.com/giftyhq/gifty-php/llms.txt

List all transactions with optional filtering by gift card ID and pagination using a limit. Requires a GiftyClient instance initialized with an API key.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    // Get all transactions with limit
    $transactions = $gifty->transactions->all(['limit' => 10]);

    foreach ($transactions as $transaction) {
        echo sprintf(
            "ID: %s | Amount: %d | Type: %s | Status: %s\n",
            $transaction->getId(),
            $transaction->getAmount(),
            $transaction->getType(),
            $transaction->getStatus()
        );
    }

    // Filter transactions by gift card ID
    $giftCardTransactions = $gifty->transactions->all([
        'giftcard' => 'gc_123456789'
    ]);

    foreach ($giftCardTransactions as $tx) {
        echo "Transaction: " . $tx->getId() . " - " . $tx->getDescription() . "\n";
    }
} catch (ApiException $e) {
    echo "Error: " . $e->getMessage();
}

```

--------------------------------

### Manage Transactions

Source: https://github.com/giftyhq/gifty-php/blob/main/README.md

Methods for retrieving, capturing, releasing, and refunding transactions.

```php
$transactions = $gifty->transactions->all(['limit' => 5]);
```

```php
$transactions = $gifty->transactions->all(['giftcard' => 'gc_123456789']);
```

```php
$transaction = $gifty->transactions->get('tr_BV94pGgqRvgobxvrLX28jEl0');
```

```php
$transaction = $gifty->transactions->capture('tr_BV94pGgqRvgobxvrLX28jEl0');
```

```php
$transaction = $gifty->transactions->release('tr_BV94pGgqRvgobxvrLX28jEl0');
```

```php
$transaction = $gifty->transactions->refund(
  'tr_BV94pGgqRvgobxvrLX28jEl0',
  [
    "amount" => 1250,
    "currency" => "EUR",
    "reason" => "CUSTOMER_REQUEST",
    "reason_description" => "Customer returned one item from the order"
  ]
);
```

--------------------------------

### Redeem a Gift Card (One-Phase and Two-Phase)

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Redeem value from a gift card. Use `capture: true` for immediate finalization or `capture: false` to create a pending authorization that can be captured later. Requires a GiftyClient instance initialized with an API key.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    // Immediate capture (one-phase)
    $transaction = $gifty->giftCards->redeem('ABCDABCDABCDABCD', [
        'amount' => 1250,           // Amount in cents (€12.50)
        'currency' => 'EUR',
        'capture' => true           // Immediately finalize the redemption
    ]);

    // Two-phase redemption (reserve now, capture later)
    $transaction = $gifty->giftCards->redeem('ABCDABCDABCDABCD', [
        'amount' => 1250,
        'currency' => 'EUR',
        'capture' => false          // Creates a pending authorization
    ]);

    echo "Transaction ID: " . $transaction->getId() . "\n";
    echo "Status: " . $transaction->getStatus() . "\n";              // pending (if capture=false)
    echo "Is Capturable: " . ($transaction->isCapturable() ? 'Yes' : 'No') . "\n";

    // Later, capture or release the transaction
    if ($transaction->isCapturable()) {
        // Finalize the payment
        $capturedTx = $gifty->transactions->capture($transaction->getId());
        echo "Captured at: " . $capturedTx->getCapturedAt() . "\n";
    }
} catch (ApiException $e) {
    echo "Redeem failed: " . $e->getMessage();
}

```

--------------------------------

### Manage Gift Cards

Source: https://github.com/giftyhq/gifty-php/blob/main/README.md

Methods for retrieving, issuing, redeeming, and extending gift cards.

```php
$giftCard = $gifty->giftCards->get('ABCDABCDABCDABCD');
```

```php
$transaction = $gifty->giftCards->issue(
  'ABCDABCDABCDABCD',
  [
    "amount" => 1250,
    "currency" => "EUR",
    "promotional" => false
  ]
);
```

```php
$transaction = $gifty->giftCards->redeem(
  'ABCDABCDABCDABCD',
  [
    "amount" => 1250,
    "currency" => "EUR",
    "capture" => false
  ]
);
```

```php
$transaction = $gifty->giftCards->extend(
  'ABCDABCDABCDABCD',
  [
    "expires_at" => "2027-09-15T12:42:42+00:00"
  ]
);
```

--------------------------------

### Refund a Transaction with PHP

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Refunds a previously captured transaction, returning the value to the gift card.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    $transaction = $gifty->transactions->refund('tr_BV94pGgqRvgobxvrLX28jEl0', [
        'amount' => 1250,                              // Amount to refund in cents
        'currency' => 'EUR',
        'reason' => 'CUSTOMER_REQUEST',                // Refund reason code
        'reason_description' => 'Customer returned one item from the order'
    ]);

    echo "Refund Transaction ID: " . $transaction->getId() . "\n";
    echo "Refund Amount: " . $transaction->getAmount() . "\n";
    echo "Status: " . $transaction->getStatus() . "\n";

    $refundDetails = $transaction->getRefundDetails();
    if ($refundDetails) {
        print_r($refundDetails);
    }
} catch (ApiException $e) {
    echo "Refund failed: " . $e->getMessage();
}
```

--------------------------------

### Capture a Transaction

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Finalize a pending transaction that was created with `capture: false`. Requires a GiftyClient instance initialized with an API key and the transaction ID.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    $transaction = $gifty->transactions->capture('tr_BV94pGgqRvgobxvrLX28jEl0');

    echo "Transaction captured successfully\n";
    echo "Status: " . $transaction->getStatus() . "\n";              // success
    echo "Captured At: " . $transaction->getCapturedAt() . "\n";
} catch (ApiException $e) {
    echo "Capture failed: " . $e->getMessage();
}

```

--------------------------------

### Release a Transaction with PHP

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Cancels a pending transaction and returns the reserved amount to the gift card.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    $transaction = $gifty->transactions->release('tr_BV94pGgqRvgobxvrLX28jEl0');

    echo "Transaction released successfully\n";
    echo "Status: " . $transaction->getStatus() . "\n";
} catch (ApiException $e) {
    echo "Release failed: " . $e->getMessage();
}
```

--------------------------------

### Retrieve Gift Card Details

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Fetch card information by code and check capabilities like redeemability or expiration status. Gift card codes are automatically cleaned of spaces and dashes.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    // Gift card codes can include spaces/dashes - they're automatically cleaned
    $giftCard = $gifty->giftCards->get('ABCD-EFGH-IJKL-MNOP');

    echo "Card ID: " . $giftCard->getId() . "\n";                    // gc_Lb6PkYKoqvAbAQmVz9A3xRON
    echo "Balance: " . $giftCard->getBalance() . "\n";               // 1249 (in cents)
    echo "Currency: " . $giftCard->getCurrency() . "\n";             // EUR
    echo "Is Promotional: " . ($giftCard->getPromotional() ? 'Yes' : 'No') . "\n";
    echo "Expires At: " . $giftCard->getExpiresAt() . "\n";          // 2027-09-15T12:42:42+00:00
    echo "Created At: " . $giftCard->getCreatedAt() . "\n";
    echo "Package ID: " . $giftCard->getPackageId() . "\n";

    // Check card capabilities
    if ($giftCard->isRedeemable()) {
        echo "Card can be redeemed\n";
    }
    if ($giftCard->isIssuable()) {
        echo "Card can be issued\n";
    }
    if ($giftCard->isExtendable()) {
        echo "Card expiration can be extended\n";
    }
} catch (ApiException $e) {
    echo "Error: " . $e->getMessage();
}
```

--------------------------------

### Retrieve a Single Transaction

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Fetch details of a specific transaction by its ID. Requires a GiftyClient instance initialized with an API key.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    $transaction = $gifty->transactions->get('tr_BV94pGgqRvgobxvrLX28jEl0');

    echo "Transaction ID: " . $transaction->getId() . "\n";
    echo "Amount: " . $transaction->getAmount() . " " . $transaction->getCurrency() . "\n";
    echo "Status: " . $transaction->getStatus() . "\n";
    echo "Type: " . $transaction->getType() . "\n";
    echo "Description: " . $transaction->getDescription() . "\n";
    echo "Is Capturable: " . ($transaction->isCapturable() ? 'Yes' : 'No') . "\n";
    echo "Captured At: " . ($transaction->getCapturedAt() ?? 'Not captured') . "\n";
    echo "Created At: " . $transaction->getCreatedAt() . "\n";

    // Check refund details if available
    $refundDetails = $transaction->getRefundDetails();
    if ($refundDetails) {
        print_r($refundDetails);
    }
} catch (ApiException $e) {
    echo "Error: " . $e->getMessage();
}

```

--------------------------------

### POST /transactions/{id}/refund

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Refunds a previously captured transaction, returning value to the gift card.

```APIDOC
## POST /transactions/{id}/refund

### Description
Refund a previously captured transaction, returning value to the gift card.

### Method
POST

### Endpoint
/transactions/{id}/refund

### Parameters
#### Path Parameters
- **id** (string) - Required - The transaction ID to refund.

#### Request Body
- **amount** (integer) - Required - Amount to refund in cents
- **currency** (string) - Required - Currency code (e.g., EUR)
- **reason** (string) - Required - Refund reason code
- **reason_description** (string) - Optional - Description of the refund reason
```

--------------------------------

### POST /transactions/{id}/release

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Cancels a pending transaction and returns the reserved amount to the gift card.

```APIDOC
## POST /transactions/{id}/release

### Description
Cancel a pending transaction and return the reserved amount to the gift card.

### Method
POST

### Endpoint
/transactions/{id}/release

### Parameters
#### Path Parameters
- **id** (string) - Required - The transaction ID to release.
```

--------------------------------

### Issue New Gift Card Value

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Add value to a gift card using the issue method. Amounts must be provided in cents.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    $transaction = $gifty->giftCards->issue('ABCDABCDABCDABCD', [
        'amount' => 2500,           // Amount in cents (€25.00)
        'currency' => 'EUR',
        'promotional' => false      // Set true for promotional gift cards
    ]);

    echo "Transaction ID: " . $transaction->getId() . "\n";          // tr_BV94pGgqRvgobxvrLX28jEl0
    echo "Amount: " . $transaction->getAmount() . "\n";              // 2500
    echo "Status: " . $transaction->getStatus() . "\n";              // success
    echo "Type: " . $transaction->getType() . "\n";                  // issue
    echo "Description: " . $transaction->getDescription() . "\n";    // Issue amount of '€ 25,00'
    echo "Created At: " . $transaction->getCreatedAt() . "\n";
} catch (ApiException $e) {
    echo "Issue failed: " . $e->getMessage();
}
```

--------------------------------

### Extend Gift Card Expiration

Source: https://context7.com/giftyhq/gifty-php/llms.txt

Extend the expiration date of a gift card. Requires a GiftyClient instance initialized with an API key and the gift card's ID. The new expiration date must be in ISO 8601 format.

```php
<?php

use Gifty\Client\GiftyClient;
use Gifty\Client\Exceptions\ApiException;

$gifty = new GiftyClient('your-api-key');

try {
    $transaction = $gifty->giftCards->extend('ABCDABCDABCDABCD', [
        'expires_at' => '2027-09-15T12:42:42+00:00'  // ISO 8601 format
    ]);

    echo "Extension Transaction ID: " . $transaction->getId() . "\n";
    echo "Type: " . $transaction->getType() . "\n";                  // extend
    echo "Status: " . $transaction->getStatus() . "\n";
} catch (ApiException $e) {
    echo "Extension failed: " . $e->getMessage();
}

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.