README

PayMaya SDK for PHP

A modern and type-safe PayMaya SDK for PHP, built with Saloon on top of Guzzle.
Provides an elegant API for working with Checkout, Customizations, and Webhooks.

Support us

If you find this package helpful, consider supporting its development via Ko-fi or PayPal.

Requirements

• PHP 8.3+
• Composer

We always encourage using the latest PHP versions for better performance and security.
See supported PHP versions and what's new.

Installation

You can install the package via Composer:

composer require lloricode/paymaya-sdk-php

Upgrading from v2? Check the Upgrade Guide.

Upgrading from v2 to v3

We have introduced breaking changes in v3, including:

• PHP 8.3 requirement
• Switch to Saloon for HTTP requests
• DTOs and Enums for better type safety
• Unified PaymayaConnector instead of multiple clients

➡ See full details in the Upgrade Guide.

Laravel Integration

If you're using Laravel, we recommend installing the official Laravel package for a seamless experience:

composer require lloricode/laravel-maya-sdk

This package provides:

• Service Provider & Facade for easy access
• Configuration file for managing API keys and environment
• Laravel-specific helpers for better developer experience

📘 Learn more here: Laravel Maya SDK

Usage

Below are common usage examples.
Refer to PayMaya API Docs for full details.

Checkout

https://developers.maya.ph/reference/createv1checkout

use Lloricode\Paymaya\DataTransferObjects\Checkout\Amount\AmountDetailDto;
use Lloricode\Paymaya\DataTransferObjects\Checkout\Amount\AmountDto;
use Lloricode\Paymaya\DataTransferObjects\Checkout\Buyer\BillingAddressDto;
use Lloricode\Paymaya\DataTransferObjects\Checkout\Buyer\BuyerDto;
use Lloricode\Paymaya\DataTransferObjects\Checkout\Buyer\ContactDto;
use Lloricode\Paymaya\DataTransferObjects\Checkout\Buyer\ShippingAddressDto;
use Lloricode\Paymaya\DataTransferObjects\Checkout\CheckoutDto;
use Lloricode\Paymaya\DataTransferObjects\Checkout\ItemDto;
use Lloricode\Paymaya\DataTransferObjects\Checkout\MetaDataDto;
use Lloricode\Paymaya\DataTransferObjects\Checkout\RedirectUrlDto;
use Lloricode\Paymaya\DataTransferObjects\Checkout\TotalAmountDto;
use Lloricode\Paymaya\Enums\Environment;
use Lloricode\Paymaya\Paymaya;

$api = new Paymaya(
    environment: Environment::Sandbox,
    secretKey: 'sk-X8qolYjy62kIzEbr0QRK1h4b4KDVHaNcwMYk39jInSl',
    publicKey: 'pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah',
);

$checkout = new CheckoutDto(
    totalAmount: new TotalAmountDto(
        value: 100,
        details: new AmountDetailDto(
            subtotal: 100
        )
    ),
    buyer: new BuyerDto(
        firstName: 'John',
        middleName: 'Paul',
        lastName: 'Doe',
        birthday: '1995-10-24',
        customerSince: '1995-10-24',
        gender: 'M',
        contact: new ContactDto(
            phone: '+639181008888',
            email: 'merchant@merchantsite.com'
        ),
        shippingAddress: new ShippingAddressDto(
            firstName: 'John',
            middleName: 'Paul',
            lastName: 'Doe',
            phone: '+639181008888',
            email: 'merchant@merchantsite.com',
            line1: '6F Launchpad',
            line2: 'Reliance Street',
            city: 'Mandaluyong City',
            state: 'Metro Manila',
            zipCode: '1552',
            countryCode: 'PH',
            shippingType: 'ST'
        ),
        billingAddress: new BillingAddressDto(
            line1: '6F Launchpad',
            line2: 'Reliance Street',
            city: 'Mandaluyong City',
            state: 'Metro Manila',
            zipCode: '1552',
            countryCode: 'PH'
        )
    ),
    items: [
        new ItemDto(
            name: 'Canvas Slip Ons',
            quantity: 1,
            code: 'CVG-096732',
            description: 'Shoes',
            amount: new AmountDto(
                value: 100,
                details: new AmountDetailDto(
                    discount: 0,
                    serviceCharge: 0,
                    shippingFee: 0,
                    tax: 0,
                    subtotal: 100
                )
            ),
            totalAmount: new AmountDto(
                value: 100,
                details: new AmountDetailDto(
                    discount: 0,
                    serviceCharge: 0,
                    shippingFee: 0,
                    tax: 0,
                    subtotal: 100
                )
            )
        ),
    ],
    redirectUrl: new RedirectUrlDto(
        success: 'https://www.merchantsite.com/success',
        failure: 'https://www.merchantsite.com/failure',
        cancel: 'https://www.merchantsite.com/cancel'
    ),
    requestReferenceNumber: '1551191039',
    metadata: new MetaDataDto(
        smi: 'smi',
        smn: 'smn',
        mci: 'mci',
        mpc: 'mpc',
        mco: 'mco',
        mst: 'mst'
    )
);

// submit
$checkoutResponse = $api->createCheckout($checkout);

echo 'id: '.$checkoutResponse->checkoutId."\n";
echo 'url: '.$checkoutResponse->redirectUrl."\n";

// retrieve
$checkoutDto = $api->getCheckout($checkoutResponse->checkoutId);

Customization

https://developers.maya.ph/reference/setv1customizations-1

use Lloricode\Paymaya\DataTransferObjects\Checkout\Customization\CustomizationDto;
use Lloricode\Paymaya\Enums\Environment;
use Lloricode\Paymaya\Paymaya;

$api = new Paymaya(
    environment: Environment::Sandbox,
    secretKey: 'sk-X8qolYjy62kIzEbr0QRK1h4b4KDVHaNcwMYk39jInSl',
    publicKey: 'pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah',
);

// register (readonly DTO via constructor)
$api->createCustomization(
    new CustomizationDto(
        logoUrl: 'https://image-logo.png',
        iconUrl: 'https://image-icon.png',
        appleTouchIconUrl: 'https://image-apple.png',
        customTitle: 'Test Title Mock',
        colorScheme: '#e01c44',
    )
);

// retrieve
$customizationDto = $api->customizations();

// delete
$api->deleteCustomization();

Webhook

Checkout Webhook

https://developers.maya.ph/reference/createv1webhook-1

use Lloricode\Paymaya\DataTransferObjects\Webhook\WebhookDto;
use Lloricode\Paymaya\Enums\Environment;
use Lloricode\Paymaya\Enums\Webhook;
use Lloricode\Paymaya\Paymaya;

$api = new Paymaya(
    environment: Environment::Sandbox,
    secretKey: 'sk-X8qolYjy62kIzEbr0QRK1h4b4KDVHaNcwMYk39jInSl',
    publicKey: 'pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah',
);

// retrieve
/** @var array<string, WebhookDto> $webhooks */
$webhooks = $api->webhooks();

// delete all
foreach ($webhooks as $webhook) {
    $api->deleteWebhook($webhook->id);
}

// register (readonly DTOs via constructors)
$createdWebhookDto = $api->createWebhook(
    new WebhookDto(
        name: Webhook::CHECKOUT_SUCCESS,
        callbackUrl: 'https://web.test/test/success'
    )
);

// update (create a new readonly DTO with the existing id and new callback URL)
$existing = $webhooks[Webhook::CHECKOUT_SUCCESS];
$updatingDto = new WebhookDto(
    id: $existing->id,
    name: $existing->name,
    callbackUrl: 'https://web.test/test/update-success'
);

$webhookDto = $api->updateWebhooks($updatingDto);

Testing

Run the tests with:

vendor/bin/phpunit

Changelog

See CHANGELOG for details.

Contributing

Please see CONTRIBUTING for guidelines.

Security

Please review our security policy for details.

Credits

• Lloric Mayuga Garcia
• All Contributors

License

The MIT License (MIT). See LICENSE for more information.