# Services & methods

Every service on the `Luigel\Paymongo\Facades\Paymongo` facade and its public methods. Call a method as `Paymongo::{service}()->{method}(...)`. Every method throws a `PaymongoException` subclass when PayMongo answers with an error.

Parameter and return types are named by their short name. The data objects they return are listed on [Data objects](/data-objects.md).

## paymentIntents()

`Paymongo::paymentIntents()` returns `Luigel\Paymongo\Services\PaymentIntentService`.

### paymentIntents()->create()

```php
create(array $attributes, ?string $idempotencyKey = null): PaymentIntent
```

Returns [`PaymentIntent`](/data-objects.md#paymentintent).

### paymentIntents()->retrieve()

```php
retrieve(string $id): PaymentIntent
```

Returns [`PaymentIntent`](/data-objects.md#paymentintent).

### paymentIntents()->retrieveUsingClientKey()

```php
retrieveUsingClientKey(string $id, string $clientKey): PaymentIntent
```

Retrieve a payment intent client-side: authenticates with the configured public key and passes the intent's client key as a query parameter.

Returns [`PaymentIntent`](/data-objects.md#paymentintent).

### paymentIntents()->attach()

```php
attach(string $id, string $paymentMethodId, ?string $returnUrl = null, ?string $clientKey = null): PaymentIntent
```

Attach a payment method to the payment intent.

- `$returnUrl`: Required by PayMongo for e-wallet, DOB and BillEase payments.

Returns [`PaymentIntent`](/data-objects.md#paymentintent).

### paymentIntents()->capture()

```php
capture(string $id, ?int $amount = null): PaymentIntent
```

Capture a manually-captured intent; omit the amount for a full capture.

Returns [`PaymentIntent`](/data-objects.md#paymentintent).

### paymentIntents()->cancel()

```php
cancel(string $id): PaymentIntent
```

Returns [`PaymentIntent`](/data-objects.md#paymentintent).

## paymentMethods()

`Paymongo::paymentMethods()` returns `Luigel\Paymongo\Services\PaymentMethodService`.

### paymentMethods()->create()

```php
create(array $attributes): PaymentMethod
```

Returns [`PaymentMethod`](/data-objects.md#paymentmethod).

### paymentMethods()->retrieve()

```php
retrieve(string $id): PaymentMethod
```

Returns [`PaymentMethod`](/data-objects.md#paymentmethod).

## payments()

`Paymongo::payments()` returns `Luigel\Paymongo\Services\PaymentService`.

### payments()->create()

```php
create(array $attributes, ?string $idempotencyKey = null): Payment
```

Charge a chargeable source. This is the last step of the legacy Sources flow; payment intents create their payment for you.

- `$attributes`: Supported keys: amount (centavos, min 100), currency, source (`['id' => $sourceId, 'type' => 'source']`), description, statement_descriptor, metadata.

Returns [`Payment`](/data-objects.md#payment).

### payments()->retrieve()

```php
retrieve(string $id): Payment
```

Returns [`Payment`](/data-objects.md#payment).

### payments()->list()

```php
list(array $params = []): CursorPage
```

- `$params`: Supported keys: limit, before, after.

Returns [`CursorPage<Payment>`](/data-objects.md#payment).

## refunds()

`Paymongo::refunds()` returns `Luigel\Paymongo\Services\RefundService`.

### refunds()->create()

```php
create(array $attributes, ?string $idempotencyKey = null): Refund
```

Returns [`Refund`](/data-objects.md#refund).

### refunds()->retrieve()

```php
retrieve(string $id): Refund
```

Returns [`Refund`](/data-objects.md#refund).

### refunds()->list()

```php
list(array $params = []): CursorPage
```

- `$params`: Supported keys: limit, before, after, payment_id.

Returns [`CursorPage<Refund>`](/data-objects.md#refund).

## webhooks()

`Paymongo::webhooks()` returns `Luigel\Paymongo\Services\WebhookService`.

### webhooks()->create()

```php
create(string $url, array $events): Webhook
```

Returns [`Webhook`](/data-objects.md#webhook).

### webhooks()->list()

```php
list(array $params = []): CursorPage
```

- `$params`: Supported keys: limit, before, after, url.

Returns [`CursorPage<Webhook>`](/data-objects.md#webhook).

### webhooks()->retrieve()

```php
retrieve(string $id): Webhook
```

Returns [`Webhook`](/data-objects.md#webhook).

### webhooks()->update()

```php
update(string $id, array $attributes): Webhook
```

- `$attributes`: Supported keys: url, events.

Returns [`Webhook`](/data-objects.md#webhook).

### webhooks()->enable()

```php
enable(string $id): Webhook
```

Returns [`Webhook`](/data-objects.md#webhook).

### webhooks()->disable()

```php
disable(string $id): Webhook
```

Returns [`Webhook`](/data-objects.md#webhook).

### webhooks()->delete()

```php
delete(string $id): bool
```

Delete the endpoint. The client throws on failure, so reaching the return value always means the deletion succeeded.

Returns `bool`.

## sources()

`Paymongo::sources()` returns `Luigel\Paymongo\Services\SourceService`.

> **Deprecated.** The PayMongo Sources API is deprecated. Use payment intents with e-wallet payment methods instead.

### sources()->create()

```php
create(array $attributes): Source
```

Returns [`Source`](/data-objects.md#source).

### sources()->retrieve()

```php
retrieve(string $id): Source
```

Returns [`Source`](/data-objects.md#source).

## checkoutSessions()

`Paymongo::checkoutSessions()` returns `Luigel\Paymongo\Services\CheckoutSessionService`.

### checkoutSessions()->create()

```php
create(array $attributes, ?string $idempotencyKey = null): CheckoutSession
```

Returns [`CheckoutSession`](/data-objects.md#checkoutsession).

### checkoutSessions()->retrieve()

```php
retrieve(string $id): CheckoutSession
```

Returns [`CheckoutSession`](/data-objects.md#checkoutsession).

### checkoutSessions()->expire()

```php
expire(string $id): CheckoutSession
```

Expire an active checkout session so it can no longer be paid.

Returns [`CheckoutSession`](/data-objects.md#checkoutsession).

## links()

`Paymongo::links()` returns `Luigel\Paymongo\Services\LinkService`.

### links()->create()

```php
create(array $attributes): Link
```

Returns [`Link`](/data-objects.md#link).

### links()->retrieve()

```php
retrieve(string $id): Link
```

Returns [`Link`](/data-objects.md#link).

### links()->retrieveByReference()

```php
retrieveByReference(string $referenceNumber): ?Link
```

Find a link by its reference number, or null when none matches.

Returns [`?Link`](/data-objects.md#link).

### links()->list()

```php
list(array $params = []): CursorPage
```

- `$params`: Supported keys: limit, before, after.

Returns [`CursorPage<Link>`](/data-objects.md#link).

### links()->archive()

```php
archive(string $id): Link
```

Returns [`Link`](/data-objects.md#link).

### links()->unarchive()

```php
unarchive(string $id): Link
```

Returns [`Link`](/data-objects.md#link).

## paymentLinks()

`Paymongo::paymentLinks()` returns `Luigel\Paymongo\Services\PaymentLinkService`.

### paymentLinks()->create()

```php
create(array $attributes, ?string $idempotencyKey = null): PaymentLink
```

- `$attributes`: Supported keys: amount (min 100), currency (uppercase), description, remarks, metadata, restrictions (e.g. `['completed_sessions' => 1]`).

Returns [`PaymentLink`](/data-objects.md#paymentlink).

### paymentLinks()->retrieve()

```php
retrieve(string $id): PaymentLink
```

Returns [`PaymentLink`](/data-objects.md#paymentlink).

### paymentLinks()->update()

```php
update(string $id, array $attributes): PaymentLink
```

- `$attributes`: Updatable fields, including `status` (`active` / `archived`).

Returns [`PaymentLink`](/data-objects.md#paymentlink).

### paymentLinks()->archive()

```php
archive(string $id): PaymentLink
```

Returns [`PaymentLink`](/data-objects.md#paymentlink).

### paymentLinks()->unarchive()

```php
unarchive(string $id): PaymentLink
```

Returns [`PaymentLink`](/data-objects.md#paymentlink).

### paymentLinks()->list()

```php
list(array $params = []): CursorPage
```

List payment links. Items in the response are flat objects, so the page is assembled here rather than through the shared triple-resource helper; the next page repeats the request with `after` set to the last item's id.

- `$params`: Supported keys: limit, before, after.

Returns [`CursorPage<PaymentLink>`](/data-objects.md#paymentlink).

### paymentLinks()->payments()

```php
payments(string $id, array $params = []): CursorPage
```

The payments collected through a payment link. Items are standard v1 `{id, type, attributes}` payment resources with `has_more` pagination (assumed from the v1 conventions; the official docs do not spell the list envelope out).

- `$params`: Supported keys: limit, before, after.

Returns [`CursorPage<Payment>`](/data-objects.md#payment).

### paymentLinks()->refund()

```php
refund(string $id, array $attributes = []): Refund
```

Refund a payment collected through a payment link. The request is a flat body; the response is a standard `{id, type, attributes}` refund resource. Caveat: PayMongo documents this endpoint's request `amount` in pesos (major units), unlike every other amount, while the refund it returns carries `amount` in centavos.

- `$attributes`: Supported keys: payment_id, amount (pesos), reason, metadata.

Returns [`Refund`](/data-objects.md#refund).

## customers()

`Paymongo::customers()` returns `Luigel\Paymongo\Services\CustomerService`.

### customers()->create()

```php
create(array $attributes): Customer
```

- `$attributes`: Supported keys: first_name, last_name, phone, email, default_device.

Returns [`Customer`](/data-objects.md#customer).

### customers()->retrieve()

```php
retrieve(string $id): Customer
```

Returns [`Customer`](/data-objects.md#customer).

### customers()->update()

```php
update(string $id, array $attributes): Customer
```

- `$attributes`: Same keys as `create()`.

Returns [`Customer`](/data-objects.md#customer).

### customers()->delete()

```php
delete(string $id): bool
```

Delete the customer. The client throws on failure, so reaching the return value always means the deletion succeeded.

Returns `bool`.

### customers()->paymentMethods()

```php
paymentMethods(string $customerId): array
```

The payment methods saved against the customer.

Returns [`list<CustomerPaymentMethod>`](/data-objects.md#customerpaymentmethod).

### customers()->deletePaymentMethod()

```php
deletePaymentMethod(string $customerId, string $paymentMethodId): bool
```

Remove a saved payment method from the customer.

Returns `bool`.

## plans()

`Paymongo::plans()` returns `Luigel\Paymongo\Services\PlanService`.

### plans()->create()

```php
create(array $attributes): Plan
```

- `$attributes`: Supported keys: name, description, amount, currency, interval, interval_count, plan_type, cycle_count, metadata.

Returns [`Plan`](/data-objects.md#plan).

### plans()->retrieve()

```php
retrieve(string $id): Plan
```

Returns [`Plan`](/data-objects.md#plan).

### plans()->update()

```php
update(string $id, array $attributes): Plan
```

Returns [`Plan`](/data-objects.md#plan).

### plans()->list()

```php
list(array $params = []): CursorPage
```

- `$params`: Supported keys: limit, before, after.

Returns [`CursorPage<Plan>`](/data-objects.md#plan).

## subscriptions()

`Paymongo::subscriptions()` returns `Luigel\Paymongo\Services\SubscriptionService`.

### subscriptions()->create()

```php
create(string $customerId, string $planId): Subscription
```

Subscribe a customer to a plan.

Returns [`Subscription`](/data-objects.md#subscription).

### subscriptions()->retrieve()

```php
retrieve(string $id): Subscription
```

Returns [`Subscription`](/data-objects.md#subscription).

### subscriptions()->list()

```php
list(array $params = []): CursorPage
```

- `$params`: Supported keys: limit, before, after.

Returns [`CursorPage<Subscription>`](/data-objects.md#subscription).

### subscriptions()->cancel()

```php
cancel(string $id, CancellationReason|string $reason): Subscription
```

Cancel the subscription. PayMongo requires a cancellation reason.

Returns [`Subscription`](/data-objects.md#subscription).

### subscriptions()->changePlan()

```php
changePlan(string $id, string $planId): Subscription
```

Move the subscription onto a different plan.

Returns [`Subscription`](/data-objects.md#subscription).

### subscriptions()->changePaymentMethod()

```php
changePaymentMethod(string $id, string $paymentMethodId, ?string $redirectUrl = null): Subscription
```

Change the payment method future cycles are charged against.

- `$redirectUrl`: Where the customer lands after authorizing the new method.

Returns [`Subscription`](/data-objects.md#subscription).

### subscriptions()->triggerTestCycle()

```php
triggerTestCycle(string $id): void
```

Trigger an immediate billing cycle on a test-mode subscription.

Returns `void`.

## qrph()

`Paymongo::qrph()` returns `Luigel\Paymongo\Services\QrphService`.

### qrph()->generate()

```php
generate(array $attributes): MpmQr
```

Generate an MPM QR code.

- `$attributes`: Supported keys: nation, mode, type, transaction_currency, transaction_amount (dynamic only), expiry_seconds, qr_image, metadata.

Returns [`MpmQr`](/data-objects.md#mpmqr).

### qrph()->execute()

```php
execute(array $attributes): QrExecution
```

Execute an MPM QR string, moving real money from the scanner's account. The response only acknowledges the request; PayMongo settles the transfer asynchronously.

- `$attributes`: Supported keys: qr_string, amount, reference_number, metadata.

Returns [`QrExecution`](/data-objects.md#qrexecution).

### qrph()->retrieve()

```php
retrieve(string $id, bool $qrString = false, bool $qrImage = false): MpmQr
```

Retrieve an MPM QR code, optionally including its QR string and rendered image.

Returns [`MpmQr`](/data-objects.md#mpmqr).

### qrph()->expire()

```php
expire(string $id): MpmQr
```

Returns [`MpmQr`](/data-objects.md#mpmqr).

### qrph()->generateStatic()

```php
generateStatic(array $attributes): StaticQr
```

Generate a static in-store QR Ph code via the v1 `/qrph/generate` endpoint (normal `data.attributes` envelope).

- `$attributes`: Supported keys: kind ("instore", required), mobile_number, notes.

Returns [`StaticQr`](/data-objects.md#staticqr).

## payouts()

`Paymongo::payouts()` returns `Luigel\Paymongo\Services\PayoutService`.

### payouts()->list()

```php
list(array $params = []): CursorTokenPage
```

- `$params`: Supported keys: limit (default 20), after, before, search, payout_status (pending|on_hold|in_transit|deposited|returned|cancelled), provider (paymongo_central_hub|unionbank), created_at.between (`YYYY-MM-DD..YYYY-MM-DD`), sort_by (created_at|net_amount), order (asc|desc).

Returns [`CursorTokenPage<Payout>`](/data-objects.md#payout).

### payouts()->retrieve()

```php
retrieve(string $id): Payout
```

Returns [`Payout`](/data-objects.md#payout).

### payouts()->transactions()

```php
transactions(string $payoutId, array $params = []): CursorTokenPage
```

The transactions lined up in a payout.

- `$params`: Supported keys: limit, after, before.

Returns [`CursorTokenPage<PayoutTransaction>`](/data-objects.md#payouttransaction).

### payouts()->schedule()

```php
schedule(string $merchantId): PayoutSchedule
```

The payout schedule of a merchant (organization id, e.g. `org_...`).

Returns [`PayoutSchedule`](/data-objects.md#payoutschedule).

## disputes()

`Paymongo::disputes()` returns `Luigel\Paymongo\Services\DisputeService`.

### disputes()->retrieve()

```php
retrieve(string $id): Dispute
```

Returns [`Dispute`](/data-objects.md#dispute).

### disputes()->list()

```php
list(array $params = []): CursorPage
```

- `$params`: Supported keys: limit, before, after.

Returns [`CursorPage<Dispute>`](/data-objects.md#dispute).