README

A PHP SDK for integrating with the PayMongo API across payments, checkout, subscriptions, webhooks, transfers, issuing, and onboarding resources.

Features

Broad PayMongo API coverage for currently implemented resources
Payment Intents, Payment Methods, Payments, Refunds
Checkout Sessions, Links
QR Ph payments
Subscriptions, Plans, Invoices
Fraud Detection (Reviews, Rules, Scores)
Wallets, Transfers, Ledgers
Forex (Rates, Quotes)
Card Issuing (Programs, Cardholders, Cards)
Merchant Onboarding
Webhook signature verification
Idempotency support

Requirements

PHP 8.2 or higher
cURL extension
JSON extension
mbstring extension

Installation

Install via Composer:

composer require leodyversemilla07/paymongo-php

Quick Start

<?php

require_once 'vendor/autoload.php';

use Paymongo\PaymongoClient;

$client = new PaymongoClient('sk_test_your_secret_key');

// Create a payment intent
$paymentIntent = $client->paymentIntents->create([
    'amount' => 10000, // Amount in cents (100.00 PHP)
    'currency' => 'PHP',
    'payment_method_allowed' => ['card', 'gcash', 'grab_pay'],
    'description' => 'Order #12345',
]);

echo $paymentIntent->id;
echo $paymentIntent->client_key;

Usage Examples

Payment Intents

// Create a payment intent
$paymentIntent = $client->paymentIntents->create([
    'amount' => 10000,
    'currency' => 'PHP',
    'payment_method_allowed' => ['card'],
]);

// Retrieve a payment intent
$paymentIntent = $client->paymentIntents->retrieve('pi_xxx');

// Attach a payment method to a payment intent
$paymentIntent = $client->paymentIntents->attach('pi_xxx', [
    'payment_method' => 'pm_xxx',
]);

// Capture a payment intent
$paymentIntent = $client->paymentIntents->capture('pi_xxx', [
    'amount' => 10000,
]);

// Cancel a payment intent
$paymentIntent = $client->paymentIntents->cancel('pi_xxx');

Checkout Sessions

$checkoutSession = $client->checkoutSessions->create([
    'description' => 'Order #12345',
    'line_items' => [
        [
            'name' => 'Product Name',
            'quantity' => 1,
            'amount' => 10000,
            'currency' => 'PHP',
        ],
    ],
    'payment_method_types' => ['card', 'gcash', 'grab_pay'],
    'success_url' => 'https://example.com/success',
    'cancel_url' => 'https://example.com/cancel',
]);

// Redirect user to checkout
header('Location: ' . $checkoutSession->url);

Refunds

// Create a refund
$refund = $client->refunds->create([
    'amount' => 5000,
    'payment_id' => 'pay_xxx',
    'reason' => 'requested_by_customer',
]);

// List refunds
$refunds = $client->refunds->all(['limit' => 10]);

Webhooks

// Create a webhook
$webhook = $client->webhooks->create([
    'url' => 'https://example.com/webhooks/paymongo',
    'events' => [
        'payment.paid',
        'payment.failed',
    ],
]);

// Verify webhook signature
try {
    $payload = file_get_contents('php://input');
    $signatureHeader = $_SERVER['HTTP_PAYMONGO_SIGNATURE'];
    
    $event = $client->webhooks->constructEvent([
        'payload' => $payload,
        'signature_header' => $signatureHeader,
        'webhook_secret_key' => 'whsec_xxx',
    ]);

    switch ($event->type) {
        case 'payment.paid':
            // Handle successful payment
            break;
        case 'payment.failed':
            // Handle failed payment
            break;
    }

    http_response_code(200);
} catch (\Paymongo\Exceptions\SignatureVerificationException $e) {
    http_response_code(400);
    exit('Invalid signature');
}

Subscriptions

// Create a plan
$plan = $client->plans->create([
    'name' => 'Premium Plan',
    'amount' => 99900,
    'currency' => 'PHP',
    'interval' => 'month',
]);

// Create a subscription
$subscription = $client->subscriptions->create([
    'customer_id' => 'cus_xxx',
    'plan_id' => 'plan_xxx',
    'payment_method_id' => 'pm_xxx',
]);

// Cancel a subscription
$subscription = $client->subscriptions->cancel('sub_xxx');

Error Handling

use Paymongo\Exceptions\InvalidRequestException;
use Paymongo\Exceptions\AuthenticationException;
use Paymongo\Exceptions\ResourceNotFoundException;

try {
    $paymentIntent = $client->paymentIntents->create([
        'amount' => 10000,
        'currency' => 'PHP',
        'payment_method_allowed' => ['card'],
    ]);
} catch (AuthenticationException $e) {
    // Invalid API key
    echo 'Authentication failed: ' . $e->getMessage();
} catch (InvalidRequestException $e) {
    // Invalid parameters
    foreach ($e->getError() as $error) {
        echo $error->detail;
    }
} catch (ResourceNotFoundException $e) {
    // Resource not found
    echo 'Resource not found';
}

Configuration

$client = new PaymongoClient('sk_test_xxx', [
    'timeout' => 30,
    'connect_timeout' => 10,
    'idempotency_key' => 'unique-request-id',
]);

For customersV2, you can provide a Bearer token when your integration uses PayMongo's JWT-based customer authentication flow:

$client = new PaymongoClient('sk_test_xxx', [
    'customer_bearer_token' => 'jwt_customer_token',
]);

Available Services

Service	Description
`paymentIntents`	Payment Intents API
`paymentMethods`	Payment Methods API
`payments`	Payments API
`refunds`	Refunds API
`customers`	Customers API (v1)
`customersV2`	Customers API (v2, supports `customer_bearer_token`)
`checkoutSessions`	Checkout Sessions API
`links`	Payment Links API
`webhooks`	Webhooks API
`subscriptions`	Subscriptions API
`plans`	Plans API
`invoices`	Invoices API
`qrPh`	QR Ph API
`reviews`	Fraud Reviews API
`rules`	Fraud Rules API
`scores`	Fraud Scores API
`wallets`	Wallets API
`transfers`	Transfers API
`ledgers`	Ledgers API
`rates`	Forex Rates API
`quotes`	Forex Quotes API
`cards`	Card Issuing API
`cardPrograms`	Card Programs API
`cardholders`	Cardholders API
`workflows`	Workflows API
`policies`	Policies API

Testing

composer test

Test Coverage Notes

Unit tests validate request construction, entity hydration, and webhook signature handling.
Integration-style tests use a fake HTTP client to verify service responses and error propagation.

Legacy APIs

sources remains available for legacy integrations, but PayMongo's current documentation recommends using Payment Intents for new implementations.

customers maps to the older customer/card-vaulting surface, while customersV2 maps to the current v2 customer endpoints. When using customersV2, set customer_bearer_token in the client config if your integration follows PayMongo's JWT Bearer authentication flow for that API.

Not Yet Implemented

The current PayMongo documentation also includes newer product areas that are not yet covered by this SDK, including Platforms, Capital, Reconciliation, and Prism/Data surfaces.

Required vs Optional Fields

Entity constructors now validate required fields and throw Paymongo\Exceptions\UnexpectedValueException when the API response is missing required attributes. Optional fields are safely defaulted to null.

Example:

use Paymongo\ApiResource;
use Paymongo\Entities\PaymentIntent;
use Paymongo\Exceptions\UnexpectedValueException;

$resource = new ApiResource([
    'data' => [
        'id' => 'pi_test_123',
        'attributes' => [
            // 'amount' is missing here
            'capture_type' => 'automatic',
            'client_key' => 'pi_client_key',
            'currency' => 'PHP',
            'livemode' => false,
            'status' => 'awaiting_payment_method',
            'payment_method_allowed' => ['card'],
            'created_at' => 0,
            'updated_at' => 0,
        ],
    ],
]);

try {
    new PaymentIntent($resource);
} catch (UnexpectedValueException $e) {
    echo $e->getMessage();
}

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email security@example.com instead of using the issue tracker.

Credits

License

MIT License. See LICENSE.

leodyversemilla07 / paymongo-php

Maintainers

Package info

Statistics

Security

README

Features

Requirements

Installation

Quick Start

Usage Examples

Payment Intents

Checkout Sessions

Refunds

Webhooks

Subscriptions

Error Handling

Configuration

Available Services

Testing

Test Coverage Notes

Legacy APIs

Not Yet Implemented

Required vs Optional Fields

Changelog

Contributing

Security

Credits

License

Resources