18 KiB
18 KiB
Introduction
Endpoint collections provide a fluent interface for interacting with Mollie's API. Each collection manages specific resource types like payments, customers, and subscriptions, offering methods to create, retrieve, update, and delete these resources.
Setup
- Initialize the Mollie Client:
$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setApiKey("test_*************************");
- Access Endpoints via the Client:
// Payments endpoint
$mollie->payments->...
// Customers endpoint
$mollie->customers->...
// Other endpoints
$mollie->balances->...
$mollie->orders->...
- Call methods
Simple: Using arrays This approach is direct but provides less type safety:
$payment = $mollie->payments->create([
'amount' => [
'currency' => 'EUR',
'value' => '10.00'
],
'description' => 'My first API payment'
]);
Advanced: Using typed array params
You can use dedicated Data objects to add partial type safety to your parameters.
use Mollie\Api\Http\Data\Money;
use Mollie\Api\Http\Data\CreatePaymentPayload;
$payment = $mollie->payments->create([
'description' => 'My first API payment',
'amount' => new Money('EUR', '10.00')
]);
If you're starting with an array and need to convert it into a structured request, you can use a specific factory designed for this purpose.
use Mollie\Api\Http\Data\Money;
use Mollie\Api\Factories\CreatePaymentRequestFactory;
// Fully untyped data
$createPaymentRequest = CreatePaymentRequestFactory::new([
'amount' => [
'currency' => 'EUR',
'value' => '10.00'
],
'description' => 'My first API payment'
]);
// Partially untyped
$createPaymentRequest = CreatePaymentRequestFactory::new([
'amount' => new Money('EUR', '10.00'),
'description' => 'My first API payment'
]);
This method lets you effortlessly transform arrays into typed objects, thereby enhancing IDE support and increasing type safety while handling your data.
Available Endpoints
Balances
Available Queries:
GetPaginatedBalanceQuery- For listing balances with pagination
Balance Information
// Get primary balance
$balance = $mollie->balances->primary();
// Get specific balance
$balance = $mollie->balances->get('bal_12345');
// List balances
$balances = $mollie->balances->page();
Balance Reports
Available Queries:
GetBalanceReportQuery- For retrieving balance reports
Balance Report Details
// Get report for specific balance
$report = $mollie->balanceReports->getForId('bal_12345', [
'from' => '2024-01-01',
'until' => '2024-01-31',
'grouping' => 'transaction-categories'
]);
Balance Transactions
Available Queries:
GetPaginatedBalanceQuery- For listing balance transactions with pagination
Balance Transaction Management
// Get transactions for a balance
$transactions = $mollie->balanceTransactions->pageFor($balance);
// Use iterator for all transactions
foreach ($mollie->balanceTransactions->iteratorFor($balance) as $transaction) {
echo $transaction->id;
}
Chargebacks
Available Queries:
GetPaginatedChargebacksQuery- For listing chargebacks with pagination
Chargeback Management
// Get all chargebacks
$chargebacks = $mollie->chargebacks->page();
// Use iterator for all chargebacks
foreach ($mollie->chargebacks->iterator() as $chargeback) {
echo $chargeback->id;
}
Clients
Available Queries:
GetClientQuery- For retrieving client details
Client Management
// Get a specific client
$client = $mollie->clients->get('org_12345678', [
'testmode' => true
]);
// List all clients
$clients = $mollie->clients->page(
from: 'org_12345678',
limit: 50
);
Customers
Available Payloads:
CreateCustomerPayload- For creating new customersUpdateCustomerPayload- For updating existing customers
Customer Management
// Create a customer
$customer = $mollie->customers->create([
'name' => 'John Doe',
'email' => 'john@example.org',
]);
// Get a customer
$customer = $mollie->customers->get('cst_8wmqcHMN4U');
// Update a customer
$customer = $mollie->customers->update('cst_8wmqcHMN4U', [
'name' => 'Updated Name'
]);
// Delete a customer
$mollie->customers->delete('cst_8wmqcHMN4U');
// List customers
$customers = $mollie->customers->page();
Invoices
Available Queries:
GetPaginatedInvoiceQuery- For listing invoices with pagination
Invoice Management
// Get a specific invoice
$invoice = $mollie->invoices->get('inv_xBEbP9rvAq');
// List all invoices
$invoices = $mollie->invoices->page(
from: 'inv_xBEbP9rvAq',
limit: 50
);
Mandates
Available Payloads:
CreateMandatePayload- For creating new mandates
Mandate Management
// Create a mandate for a customer
$mandate = $mollie->mandates->createFor($customer, [
'method' => \Mollie\Api\Types\PaymentMethod::DIRECTDEBIT,
'consumerName' => 'John Doe',
'consumerAccount' => 'NL55INGB0000000000',
'consumerBic' => 'INGBNL2A',
'signatureDate' => '2024-01-01',
'mandateReference' => 'YOUR-COMPANY-MD13804'
]);
// Get a mandate
$mandate = $mollie->mandates->getFor($customer, 'mdt_h3gAaD5zP');
// Revoke a mandate
$mollie->mandates->revokeFor($customer, 'mdt_h3gAaD5zP');
// List mandates
$mandates = $mollie->mandates->pageFor($customer);
Methods
Available Queries:
GetPaymentMethodQuery- For retrieving method detailsGetAllMethodsQuery- For listing all available methodsGetEnabledPaymentMethodsQuery- For listing enabled methods
Payment Methods
// Get a method
$method = $mollie->methods->get(\Mollie\Api\Types\PaymentMethod::IDEAL);
// List all methods
$methods = $mollie->methods->all();
// List enabled methods
$methods = $mollie->methods->allEnabled([
'amount' => [
'currency' => 'EUR',
'value' => '100.00'
]
]);
Method Issuers
// Enable an issuer
$issuer = $mollie->methodIssuers->enable(
'pfl_v9hTwCvYqw',
\Mollie\Api\Types\PaymentMethod::IDEAL,
'ideal_INGBNL2A'
);
// Disable an issuer
$mollie->methodIssuers->disable(
'pfl_v9hTwCvYqw',
\Mollie\Api\Types\PaymentMethod::IDEAL,
'ideal_INGBNL2A'
);
Onboarding
Available Queries:
GetOnboardingStatusQuery- For retrieving onboarding status
Onboarding Management
// Get onboarding status
$onboarding = $mollie->onboarding->status();
Organizations
Available Queries:
GetOrganizationQuery- For retrieving organization details
Organization Management
// Get an organization
$organization = $mollie->organizations->get('org_12345678');
// Get current organization
$organization = $mollie->organizations->current();
// Get partner status
$partner = $mollie->organizations->partnerStatus();
Permissions
Available Queries:
GetPermissionQuery- For retrieving permission details
Permission Management
// Get a permission
$permission = $mollie->permissions->get('payments.read');
// List all permissions
$permissions = $mollie->permissions->list();
Payments
Available Payloads:
CreatePaymentPayload- For creating new paymentsUpdatePaymentPayload- For updating existing payments
Available Queries:
GetPaymentQuery- For retrieving payments with optional embedsGetPaginatedPaymentsQuery- For listing payments with pagination
Payment Management
// Create a payment using typed payload
use Mollie\Api\Http\Data\Money;
use Mollie\Api\Http\Data\CreatePaymentPayload;
$payload = new CreatePaymentPayload(
description: 'Order #12345',
amount: new Money('EUR', '10.00'),
redirectUrl: 'https://webshop.example.org/order/12345/',
webhookUrl: 'https://webshop.example.org/mollie-webhook/'
);
$payment = $mollie->payments->create($payload);
// Get a payment
$payment = $mollie->payments->get('tr_7UhSN1zuXS');
// Update a payment
$payment = $mollie->payments->update('tr_7UhSN1zuXS', [
'description' => 'Updated description'
]);
// Cancel a payment
$mollie->payments->cancel('tr_7UhSN1zuXS');
// List payments
$payments = $mollie->payments->page();
Payment Links
Available Payloads:
CreatePaymentLinkPayload- For creating payment linksUpdatePaymentLinkPayload- For updating payment links
Payment Captures
Available Payloads:
CreatePaymentCapturePayload- For creating captures
Available Queries:
GetPaymentCaptureQuery- For retrieving capture detailsGetPaginatedPaymentCapturesQuery- For listing captures
Payment Chargebacks
// Get a chargeback
$chargeback = $mollie->paymentChargebacks->getFor($payment, 'chb_n9z0tp');
// List chargebacks for payment
$chargebacks = $mollie->paymentChargebacks->pageFor($payment);
Payment Routes
// Update release date for a route
$route = $mollie->paymentRoutes->updateReleaseDateFor(
$payment,
'rt_abc123',
'2024-01-01'
);
Profiles
Available Payloads:
CreateProfilePayload- For creating new profiles
Available Factories:
ProfileFactory- For creating profile instances
Profile Management
// Create a profile
$profile = $mollie->profiles->create(new CreateProfilePayload(
'My Test Profile',
'https://example.org',
'info@example.org',
'+31612345678',
'test'
));
// Get a profile
$profile = $mollie->profiles->get('pfl_v9hTwCvYqw');
// Get current profile
$profile = $mollie->profiles->getCurrent();
// Update a profile
$profile = $mollie->profiles->update('pfl_v9hTwCvYqw', [
'name' => 'Updated Profile Name'
]);
// Delete a profile
$mollie->profiles->delete('pfl_v9hTwCvYqw');
// List profiles
$profiles = $mollie->profiles->page();
Profile Methods
// Enable a method
$method = $mollie->profileMethods->enable(
'pfl_v9hTwCvYqw',
\Mollie\Api\Types\PaymentMethod::IDEAL
);
// Disable a method
$mollie->profileMethods->disable(
'pfl_v9hTwCvYqw',
\Mollie\Api\Types\PaymentMethod::IDEAL
);
Refunds
Available Payloads:
CreateRefundPaymentPayload- For creating refunds on paymentsCreateRefundOrderPayload- For creating refunds on orders
Available Queries:
GetPaginatedRefundsQuery- For listing refunds with pagination
Refund Management
// Create a refund for a payment
$refund = $mollie->refunds->createForPayment($paymentId, [
'amount' => [
'currency' => 'EUR',
'value' => '15.00'
],
'description' => 'Refund for returned item'
]);
// List refunds
$refunds = $mollie->refunds->page();
Sales Invoices
[Official Documentation TBA]
Available Payloads:
CreateSalesInvoicePayload- For creating sales invoicesUpdateSalesInvoicePayload- For updating existing sales invoices
Available Queries:
GetPaginatedSalesInvoiceQuery- For listing sales invoices with pagination
Sales Invoice Management
use Mollie\Api\Types\VatMode;
use Mollie\Api\Types\VatScheme;
use Mollie\Api\Types\PaymentTerm;
use Mollie\Api\Types\RecipientType;
use Mollie\Api\Types\RecipientType;
use Mollie\Api\Types\SalesInvoiceStatus;
// Create a sales invoice
$salesInvoice = $mollie->salesInvoices->create([
'currency' => 'EUR',
'status' => SalesInvoiceStatus::DRAFT,
'vatScheme' => VatScheme::STANDARD,
'vatMode' => VatMode::INCLUSIVE,
'paymentTerm' => PaymentTerm::DAYS_30,
'recipientIdentifier' => 'XXXXX',
'recipient' => [
'type' => RecipientType::CONSUMER,
'email' => 'darth@vader.deathstar',
'streetAndNumber' => 'Sample Street 12b',
'postalCode' => '2000 AA',
'city' => 'Amsterdam',
'country' => 'NL',
'locale' => 'nl_NL'
],
'lines' => [
[
'description' => 'Monthly subscription fee',
'quantity' => 1,
'vatRate' => '21',
'unitPrice' => [
'currency' => 'EUR',
'value' => '10,00'
]
]
]
]);
// Get a sales invoice
$salesInvoice = $mollie->salesInvoices->get('invoice_12345');
// Update a sales invoice
$salesInvoice = $mollie->salesInvoices->update('invoice_12345', [
'description' => 'Updated description'
]);
// Delete a sales invoice
$mollie->salesInvoices->delete('invoice_12345');
// List sales invoices
$salesInvoices = $mollie->salesInvoices->page();
Sessions
Available Payloads:
CreateSessionPayload- For creating sessions
Available Queries:
GetPaginatedSessionsQuery- For listing sessions with pagination
Session Management
// Create a session
$session = $mollie->sessions->create([
'amount' => [
'currency' => 'EUR',
'value' => '100.00'
],
'description' => 'Session for service'
]);
// Get a session
$session = $mollie->sessions->get('sessionId');
Settlements
Available Queries:
GetPaginatedSettlementsQuery- For listing settlements with pagination
Settlement Management
// Get a settlement
$settlement = $mollie->settlements->get('settlementId');
// List settlements
$settlements = $mollie->settlements->page();
Settlement Captures
// Get captures for a settlement
$captures = $mollie->settlementCaptures->pageFor($settlement);
// Use iterator
foreach ($mollie->settlementCaptures->iteratorFor($settlement) as $capture) {
echo $capture->id;
}
Settlement Chargebacks
// List chargebacks for a settlement
$chargebacks = $mollie->settlementChargebacks->pageFor($settlement);
// Use iterator
foreach ($mollie->settlementChargebacks->iteratorFor($settlement) as $chargeback) {
echo $chargeback->id;
}
Settlement Payments
// List payments in a settlement
$payments = $mollie->settlementPayments->pageFor($settlement);
// Use iterator
foreach ($mollie->settlementPayments->iteratorFor($settlement) as $payment) {
echo $payment->id;
}
Subscriptions
Available Payloads:
CreateSubscriptionPayload- For creating subscriptions
Available Queries:
GetAllPaginatedSubscriptionsQuery- For listing all subscriptions
Subscription Management
// Create a subscription
$subscription = $mollie->subscriptions->createForCustomer('customerId', [
'amount' => [
'currency' => 'EUR',
'value' => '25.00'
],
'interval' => '1 month',
'description' => 'Monthly subscription'
]);
// List subscriptions
$subscriptions = $mollie->subscriptions->pageForCustomer('customerId');
Terminals
Available Queries:
GetPaginatedTerminalsQuery- For listing terminals with pagination
Terminal Management
// Get a terminal
$terminal = $mollie->terminals->get('terminalId');
// List terminals
$terminals = $mollie->terminals->page();
Wallets
Available Payloads:
RequestApplePayPaymentSessionPayload- For requesting Apple Pay payment sessions
Wallet Management
// Request an Apple Pay payment session
$session = $mollie->wallets->requestApplePayPaymentSession([
'domainName' => 'example.com',
'validationUrl' => 'https://apple-pay-gateway.apple.com/paymentservices/startSession'
]);
Common Patterns
Pagination
Most list methods support pagination:
// Get first page
$payments = $mollie->payments->page();
// Get specific page
$payments = $mollie->payments->page(
from: 'tr_7UhSN1zuXS', // Start from this ID
limit: 50 // Items per page
);
// Get all items using iterator
foreach ($mollie->payments->iterator() as $payment) {
echo $payment->id;
}
Error Handling
Handle errors using ApiException:
try {
$payment = $mollie->payments->get('tr_xxx');
} catch (\Mollie\Api\Exceptions\ApiException $e) {
echo "API call failed: {$e->getMessage()}";
}
Common Data Types
Money- For handling currency amountsDataCollection- For handling collections of dataData- Base class for payload/query objects
Factories
Query Factories:
PaginatedQueryFactory- For creating paginated queriesSortablePaginatedQueryFactory- For creating sortable paginated queries
Payload Factories:
CreatePaymentPayloadFactory- For creating payment payloads