Laravel PayMongo

Sources (deprecated)

PayMongo has deprecated the Sources API, and its Source Resource reference says the Sources workflow is no longer supported. For GCash, GrabPay, and every other e-wallet, use a payment intent with an e-wallet payment method, or a checkout session. Paymongo::sources() is kept only for integrations that still create sources.

A source was PayMongo's older way to take a GCash or GrabPay payment:

  1. Create a source, and send the customer to its checkout URL.
  2. The customer authorizes the payment in GCash or GrabPay. The source becomes chargeable, and PayMongo sends source.chargeable.
  3. Create a payment from the chargeable source to take the money.

payments()->create() does step 3. With a payment intent, PayMongo creates the payment itself as soon as the customer authorizes, so there is no third step. Upgrading from v2 shows the replacement.

Create a source

create() takes the e-wallet, the amount, and where to send the customer afterwards. It returns a Luigel\Paymongo\Data\Source (see the Source reference):

use Luigel\Paymongo\Facades\Paymongo;

$source = Paymongo::sources()->create([
    'type' => 'gcash', // or grab_pay
    'amount' => 150050, // centavos, at least 10000 (PHP 100.00)
    'currency' => 'PHP',
    'redirect' => [
        'success' => 'https://example.com/orders/1234/paid',
        'failed' => 'https://example.com/orders/1234/failed',
    ],
]);

$checkoutUrl = $source->redirect?->checkoutUrl; // send the customer here to authorize
  • type is gcash or grab_pay.
  • amount is integer centavos, at least 10000 (PHP 100.00).
  • redirect.success and redirect.failed are both required. The customer returns to one of them after authorizing or failing.

Retrieve a source

use Luigel\Paymongo\Facades\Paymongo;

$source = Paymongo::sources()->retrieve('src_hsJNpsRFU1LxgVbxW4YJHRs6');

$source->status;             // ?string: "pending", "chargeable", "cancelled", "expired" or "paid"
$source->sourceType;         // ?PaymentMethodType: Gcash or GrabPay
$source->money()?->format(); // "₱1,500.50"
$source->redirect?->success;

status is a plain string, not an enum. PayMongo lists pending, chargeable, cancelled, expired and paid. A source is pending until the customer authorizes it, and chargeable after.

The package dispatches source.chargeable as Luigel\Paymongo\Events\SourceChargeable. See Webhooks.

Charge a chargeable source

A chargeable source takes no money until you create a payment from it. payments()->create() takes the amount, the currency, and the source, and returns a Payment:

use Luigel\Paymongo\Facades\Paymongo;

// Once the source is chargeable (the source.chargeable webhook), charge it:
$payment = Paymongo::payments()->create([
    'amount' => 150050, // centavos, the source's amount
    'currency' => 'PHP',
    'source' => ['id' => 'src_hsJNpsRFU1LxgVbxW4YJHRs6', 'type' => 'source'],
    'description' => 'Order #1234',
], idempotencyKey: 'order-1234-charge');

$payment->status; // ?PaymentStatus: Paid, or Failed with $payment->attribute('failed_message')
  • amount is integer centavos, at least 100, and should be the source's amount.
  • source is ['id' => $sourceId, 'type' => 'source'].
  • idempotencyKey: makes a retried request return the same payment instead of charging twice. Use a key unique to this order.

Charge a source when SourceChargeable arrives rather than when the customer returns to your success URL, and only once: PayMongo's Create a Payment reference lists description, statement_descriptor, and metadata as the other attributes.

For every attribute, see PayMongo's Create a Source and Source Resource references.