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

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

• Leodyver Semilla
• All Contributors

License

MIT License. See LICENSE.

Resources

• PayMongo API Documentation
• PayMongo Dashboard